@jxsuite/studio 0.23.2 → 0.25.0

package/src/panels/{canvas-dnd.js → canvas-dnd.ts}

@@ -1,3 +1,5 @@
+/// <reference lib="dom" />
+/// <reference lib="dom.iterable" />
 /**
  * Canvas DnD — extracted from studio.js (Phase 4m). Registers canvas elements as drag-and-drop
  * targets using @atlaskit/pragmatic-drag-and-drop.
@@ -8,41 +10,35 @@ import {
   monitorForElements,
 } from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
 
-import { elToPath, canvasPanels, getNodeAtPath, VOID_ELEMENTS, isAncestor } from "../store.js";
-import { activeTab } from "../workspace/workspace.js";
-import { view } from "../view.js";
-import { applyDropInstruction } from "../panels/dnd.js";
-import { effectiveZoom } from "../canvas/canvas-helpers.js";
+import { elToPath, canvasPanels, getNodeAtPath, VOID_ELEMENTS, isAncestor } from "../store";
+import { activeTab } from "../workspace/workspace";
+import { view } from "../view";
+import { applyDropInstruction } from "../panels/dnd";
+import { effectiveZoom } from "../canvas/canvas-helpers";
 
-/**
- * @typedef {{
- *   mediaName: string | null;
- *   element: HTMLElement | null;
- *   canvas: HTMLElement;
- *   overlay: HTMLElement;
- *   overlayClk: HTMLElement;
- *   viewport: HTMLElement;
- *   scrollContainer: HTMLElement | null;
- *   dropLine: HTMLElement;
- *   _width: number | null;
- * }} CanvasPanel
- *
- * @typedef {(string | number)[]} JxPath
- *
- * @typedef {{ type: "reorder-above" | "reorder-below" | "make-child" }} DropInstruction
- *
- * @typedef {{ instruction: DropInstruction; referenceEl: HTMLElement; targetPath: JxPath }} DropResult
- */
+import type { CanvasPanel } from "../types";
+export type { CanvasPanel };
+
+import type { JxPath } from "../state";
+
+interface DropInstruction {
+  type: "reorder-above" | "reorder-below" | "make-child";
+}
+
+interface DropResult {
+  instruction: DropInstruction;
+  referenceEl: HTMLElement;
+  targetPath: JxPath;
+}
 
-/** @type {HTMLElement | null} */
-let _activeDropEl = null;
+let _activeDropEl: HTMLElement | null = null;
 
 /**
  * Register all canvas elements in a panel as DnD drop targets.
  *
  * @param {CanvasPanel} panel
  */
-export function registerPanelDnD(panel) {
+export function registerPanelDnD(panel: CanvasPanel) {
   const { canvas, dropLine } = panel;
   const allEls = canvas.querySelectorAll("*");
 
@@ -50,7 +46,7 @@ export function registerPanelDnD(panel) {
     onDragStart({ location }) {
       view.lastDragInput = location.current.input;
       for (const el of canvas.querySelectorAll("*")) {
-        /** @type {HTMLElement} */ (el).style.pointerEvents = "auto";
+        (el as HTMLElement).style.pointerEvents = "auto";
       }
       for (const p of canvasPanels) p.overlayClk.style.pointerEvents = "none";
     },
@@ -65,7 +61,7 @@ export function registerPanelDnD(panel) {
       }
       view.lastDragInput = null;
       for (const el of canvas.querySelectorAll("*")) {
-        /** @type {HTMLElement} */ (el).style.pointerEvents = "none";
+        (el as HTMLElement).style.pointerEvents = "none";
       }
       for (const p of canvasPanels) p.overlayClk.style.pointerEvents = "";
     },
@@ -77,17 +73,17 @@ export function registerPanelDnD(panel) {
     const elPath = elToPath.get(el);
     if (!elPath) continue;
 
-    const node = getNodeAtPath(document, elPath);
+    const node = getNodeAtPath(document!, elPath);
     const tag = (node?.tagName || "div").toLowerCase();
     const hasElementChildren =
       Array.isArray(node?.children) &&
-      node.children.some((/** @type {unknown} */ c) => c != null && typeof c === "object");
+      node.children.some((c: unknown) => c != null && typeof c === "object");
     const isLeaf = VOID_ELEMENTS.has(tag) || !hasElementChildren;
 
     const cleanup = dropTargetForElements({
       element: /** @type {HTMLElement} */ (el),
       canDrop({ source }) {
-        const srcPath = /** @type {JxPath | undefined} */ (source.data.path);
+        const srcPath = source.data.path as JxPath | undefined;
         if (srcPath && isAncestor(srcPath, elPath)) return false;
         return true;
       },
@@ -99,23 +95,19 @@ export function registerPanelDnD(panel) {
         if (_activeDropEl && _activeDropEl !== el) {
           _activeDropEl.classList.remove("canvas-drop-target");
         }
-        _activeDropEl = /** @type {HTMLElement} */ (el);
-        showCanvasDropIndicator(/** @type {HTMLElement} */ (el), elPath, isLeaf, panel);
+        _activeDropEl = el as HTMLElement;
+        showCanvasDropIndicator(el as HTMLElement, elPath, isLeaf, panel);
       },
       onDrag({ location }) {
         view.lastDragInput = location.current.input;
-        showCanvasDropIndicator(/** @type {HTMLElement} */ (el), elPath, isLeaf, panel);
+        showCanvasDropIndicator(el as HTMLElement, elPath, isLeaf, panel);
       },
       onDragLeave() {},
       onDrop({ source }) {
         dropLine.style.display = "none";
-        /** @type {HTMLElement} */ (el).classList.remove("canvas-drop-target");
+        (el as HTMLElement).classList.remove("canvas-drop-target");
         _activeDropEl = null;
-        const { instruction, targetPath } = getCanvasDropResult(
-          /** @type {HTMLElement} */ (el),
-          elPath,
-          isLeaf,
-        );
+        const { instruction, targetPath } = getCanvasDropResult(el as HTMLElement, elPath, isLeaf);
         applyDropInstruction(instruction, source.data, targetPath);
       },
     });
@@ -129,13 +121,13 @@ export function registerPanelDnD(panel) {
  * @param {boolean} isLeaf
  * @returns {DropResult}
  */
-function getCanvasDropResult(el, elPath, isLeaf) {
+function getCanvasDropResult(el: HTMLElement, elPath: JxPath, isLeaf: boolean): DropResult {
   if (!view.lastDragInput)
     return { instruction: { type: "make-child" }, referenceEl: el, targetPath: elPath };
   const y = view.lastDragInput.clientY;
 
   if (elPath.length === 0) {
-    const children = /** @type {HTMLElement[]} */ (Array.from(el.children));
+    const children = Array.from(el.children) as HTMLElement[];
     if (children.length === 0)
       return { instruction: { type: "make-child" }, referenceEl: el, targetPath: elPath };
     return nearestChildEdge(children, y, elPath);
@@ -146,9 +138,7 @@ function getCanvasDropResult(el, elPath, isLeaf) {
 
   if (isLeaf) {
     const instruction =
-      relY < 0.5
-        ? { type: /** @type {const} */ ("reorder-above") }
-        : { type: /** @type {const} */ ("reorder-below") };
+      relY < 0.5 ? { type: "reorder-above" as const } : { type: "reorder-below" as const };
     return { instruction, referenceEl: el, targetPath: elPath };
   }
 
@@ -168,9 +158,9 @@ function getCanvasDropResult(el, elPath, isLeaf) {
  * @param {JxPath} parentPath
  * @returns {DropResult}
  */
-function nearestChildEdge(children, cursorY, parentPath) {
+function nearestChildEdge(children: HTMLElement[], cursorY: number, parentPath: JxPath) {
   let closestDist = Infinity;
-  let instruction = /** @type {DropInstruction} */ ({ type: "reorder-below" });
+  let instruction = { type: "reorder-below" } as DropInstruction;
   let closestIdx = children.length - 1;
 
   for (let i = 0; i < children.length; i++) {
@@ -200,7 +190,12 @@ function nearestChildEdge(children, cursorY, parentPath) {
  * @param {boolean} isLeaf
  * @param {CanvasPanel} panel
  */
-function showCanvasDropIndicator(el, elPath, isLeaf, panel) {
+function showCanvasDropIndicator(
+  el: HTMLElement,
+  elPath: JxPath,
+  isLeaf: boolean,
+  panel: CanvasPanel,
+) {
   const { instruction, referenceEl } = getCanvasDropResult(el, elPath, isLeaf);
   const { dropLine, viewport } = panel;
 

package/src/panels/{data-explorer.js → data-explorer.ts}

@@ -1,3 +1,4 @@
+/// <reference lib="dom" />
 // ─── Data Explorer ──────────────────────────────────────────────────────────
 
 import { html, nothing } from "lit-html";
@@ -7,18 +8,14 @@ import { classMap } from "lit-html/directives/class-map.js";
 const expandedDataKeys = new Set();
 
 /** Unwrap a Vue ref (has .value and .__v_isRef) to get the underlying value. */
-function unwrapSignal(/** @type {unknown} */ value) {
-  if (
-    value &&
-    typeof value === "object" &&
-    /** @type {Record<string, unknown>} */ (value).__v_isRef
-  )
-    return /** @type {Record<string, unknown>} */ (value).value;
+function unwrapSignal(value: unknown) {
+  if (value && typeof value === "object" && (value as Record<string, unknown>).__v_isRef)
+    return (value as Record<string, unknown>).value;
   return value;
 }
 
 /** Type label for a signal value in the data explorer. */
-function dataTypeLabel(/** @type {unknown} */ value) {
+function dataTypeLabel(value: unknown) {
   const v = unwrapSignal(value);
   if (v === null) return "null";
   if (v === undefined) return "pending";
@@ -40,7 +37,16 @@ function dataTypeLabel(/** @type {unknown} */ value) {
  * }} callbacks
  * @returns {import("lit-html").TemplateResult}
  */
-export function renderDataExplorerTemplate(state, liveScope, callbacks) {
+export function renderDataExplorerTemplate(
+  state: Record<string, unknown>,
+  liveScope: Record<string, unknown> | null,
+  callbacks: {
+    renderCanvas: () => void;
+    renderLeftPanel: () => void;
+    defCategory: (def: unknown) => string;
+    defBadgeLabel: (def: unknown) => string;
+  },
+) {
   const { renderCanvas, renderLeftPanel, defCategory, defBadgeLabel } = callbacks;
 
   const defs = state || {};
@@ -99,10 +105,10 @@ export function renderDataExplorerTemplate(state, liveScope, callbacks) {
  * @returns {import("lit-html").TemplateResult}
  */
 export function renderDataTreeTemplate(
-  /** @type {unknown} */ value,
-  /** @type {number} */ depth,
+  value: unknown,
+  depth: number,
   maxDepth = 5,
-) {
+): import("lit-html").TemplateResult {
   const indent = `${(depth + 1) * 12}px`;
 
   if (depth > maxDepth) {
@@ -127,7 +133,7 @@ export function renderDataTreeTemplate(
 
   if (Array.isArray(value)) {
     const cap = 20;
-    const items = value.slice(0, cap).map((item, i) => {
+    const items: import("lit-html").TemplateResult[] = value.slice(0, cap).map((item, i) => {
       if (item === null || item === undefined || typeof item !== "object") {
         const valText =
           typeof item === "string" && item.length > 80
@@ -155,10 +161,10 @@ export function renderDataTreeTemplate(
   }
 
   // Object
-  const obj = /** @type {Record<string, unknown>} */ (value);
+  const obj = value as Record<string, unknown>;
   const keys = Object.keys(obj);
   const cap = 30;
-  const items = keys.slice(0, cap).map((key) => {
+  const items: import("lit-html").TemplateResult[] = keys.slice(0, cap).map((key) => {
     const v = obj[key];
     if (v === null || v === undefined || typeof v !== "object") {
       const valText =

package/src/panels/dnd.ts

@@ -0,0 +1,417 @@
+/// <reference lib="dom" />
+/**
+ * DnD registration functions — extracted from studio.js (Phase 4). Registers drag-and-drop behavior
+ * on layer rows, component cards, and element cards.
+ */
+
+import {
+  draggable,
+  dropTargetForElements,
+  monitorForElements,
+} from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
+import { combine } from "@atlaskit/pragmatic-drag-and-drop/combine";
+import {
+  attachInstruction,
+  extractInstruction,
+} from "@atlaskit/pragmatic-drag-and-drop-hitbox/tree-item";
+
+import {
+  leftPanel,
+  getNodeAtPath,
+  parentElementPath,
+  childIndex,
+  isAncestor,
+  renderOnly,
+} from "../store";
+import { transact, transactDoc, mutateMoveNode, mutateInsertNode } from "../tabs/transact";
+import { activeTab } from "../workspace/workspace";
+import { view } from "../view";
+import { componentRegistry, computeRelativePath } from "../files/components";
+import { renderComponentPreview } from "./stylebook-panel";
+import { defaultDef, unsafeTags } from "./shared";
+import type { JxPath } from "../state";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+
+interface DragCanDragArgs {
+  element: HTMLElement;
+  input: { clientX: number; clientY: number };
+}
+
+interface DragDropSourceArgs {
+  source: { data: Record<string, unknown>; element: HTMLElement };
+}
+
+interface DragSelfArgs {
+  self: { data: Record<string, unknown> };
+}
+
+interface DragMonitorDropArgs {
+  source: { data: Record<string, unknown>; element: HTMLElement };
+  location: { current: { dropTargets: { data: Record<string, unknown> }[] } };
+}
+
+/** Register DnD on layer rows — called from left-panel.js after render */
+export function registerLayersDnD() {
+  requestAnimationFrame(() => {
+    const container = leftPanel?.querySelector(".layers-container") as HTMLElement | null;
+    if (!container) return;
+
+    (container.querySelectorAll("[data-dnd-row]") as NodeListOf<HTMLElement>).forEach((row) => {
+      const rowPath = (row.dataset.path as string)
+        .split("/")
+        .map((s: string) => (/^\d+$/.test(s) ? parseInt(s) : s)) as JxPath;
+      const rowDepth = parseInt(row.dataset.dndDepth as string) || 0;
+      const isVoid = row.hasAttribute("data-dnd-void");
+      const isExpanded = row.hasAttribute("data-dnd-expanded");
+
+      const cleanup = combine(
+        draggable({
+          element: row,
+          canDrag({ element: _el, input }: DragCanDragArgs) {
+            const target = document.elementFromPoint(input.clientX, input.clientY) as HTMLElement;
+            if (target?.closest(".layer-actions")) return false;
+            return true;
+          },
+          getInitialData() {
+            return { type: "tree-node", path: rowPath };
+          },
+          onDragStart() {
+            row.classList.add("dragging");
+            view.layerDragSourceHeight = row.offsetHeight;
+            if (isExpanded) {
+              hideDescendantRows(row, container);
+            }
+          },
+          onDrop() {
+            row.classList.remove("dragging");
+            if (isExpanded) {
+              renderOnly("leftPanel");
+            }
+          },
+        }),
+        dropTargetForElements({
+          element: row,
+          canDrop({ source }: DragDropSourceArgs) {
+            const srcPath = source.data.path as JxPath | undefined;
+            if (srcPath && isAncestor(srcPath, rowPath)) return false;
+            return true;
+          },
+          getData({ input, element }: any) {
+            return attachInstruction(
+              { path: rowPath },
+              {
+                input,
+                element,
+                currentLevel: rowDepth,
+                indentPerLevel: 16,
+                mode: isExpanded ? "expanded" : "standard",
+                block: isVoid ? ["make-child"] : [],
+              },
+            ) as Record<string | symbol, unknown>;
+          },
+          onDragEnter({ self }: DragSelfArgs) {
+            showLayerDropGap(row, self.data, container);
+          },
+          onDrag({ self }: DragSelfArgs) {
+            showLayerDropGap(row, self.data, container);
+          },
+          onDragLeave() {
+            clearLayerDropGap(container);
+          },
+          onDrop() {
+            clearLayerDropGap(container);
+          },
+        }),
+      );
+      view.dndCleanups.push(cleanup);
+    });
+
+    // Global monitor
+    const monitorCleanup = monitorForElements({
+      onDrop({ source, location }: DragMonitorDropArgs) {
+        clearLayerDropGap(container);
+        const target = location.current.dropTargets[0];
+        if (!target) return;
+        const instruction = extractInstruction(target.data);
+        if (!instruction || instruction.type === "instruction-blocked") return;
+        const srcData = source.data;
+        const targetPath = target.data.path as JxPath;
+
+        // If the source had children, persist collapse at the new location
+        const srcRow = srcData.type === "tree-node" && source.element;
+        const wasExpanded = srcRow && srcRow.hasAttribute("data-dnd-expanded");
+
+        applyDropInstruction(instruction, srcData, targetPath);
+
+        if (wasExpanded) {
+          const tab = activeTab.value;
+          const newPath = tab?.session.selection;
+          if (newPath) {
+            const collapsed = view._layersCollapsed || (view._layersCollapsed = new Set());
+            collapsed.add(newPath.join("/"));
+          }
+        }
+      },
+    });
+    view.dndCleanups.push(monitorCleanup);
+  });
+}
+
+/** Register DnD on component rows — called from renderLeftPanel when tab=components */
+export function registerComponentsDnD() {
+  requestAnimationFrame(() => {
+    const container = leftPanel?.querySelector(".components-section") as HTMLElement | null;
+    if (!container) return;
+
+    (container.querySelectorAll("[data-component-tag]") as NodeListOf<HTMLElement>).forEach(
+      (row) => {
+        const tagName = row.dataset.componentTag;
+        if (!tagName) return;
+        const comp = componentRegistry.find(
+          (c: import("../files/components.js").ComponentEntry) => c.tagName === tagName,
+        );
+        if (!comp) return;
+
+        // Fill preview with live rendered component
+        const preview = row.querySelector(".element-card-preview");
+        if (preview && !preview.querySelector(tagName)) {
+          renderComponentPreview(comp).then((el: HTMLElement) => {
+            preview.textContent = "";
+            preview.appendChild(el);
+          });
+        }
+
+        const instanceDef = {
+          tagName: comp.tagName,
+          $props: comp.props
+            ? Object.fromEntries(
+                comp.props.map(
+                  (/** @type {{ name: string; default?: unknown; [k: string]: unknown }} */ p) => [
+                    p.name,
+                    p.default !== undefined ? p.default : "",
+                  ],
+                ),
+              )
+            : {},
+        };
+        const cleanup = draggable({
+          element: row,
+          getInitialData() {
+            return { type: "block", fragment: structuredClone(instanceDef) };
+          },
+        });
+        view.dndCleanups.push(cleanup);
+      },
+    );
+  });
+}
+
+/** Register DnD on element (HTML block) rows */
+export function registerElementsDnD() {
+  requestAnimationFrame(() => {
+    const container = leftPanel?.querySelector(".panel-body") as HTMLElement | null;
+    if (!container) return;
+    (container.querySelectorAll("[data-block-tag]") as NodeListOf<HTMLElement>).forEach((row) => {
+      const tag = row.dataset.blockTag as string;
+      const preview = row.querySelector(".element-card-preview");
+      if (preview && !preview.firstChild) {
+        const el = document.createElement(unsafeTags.has(tag) ? "span" : tag);
+        el.textContent = tag;
+        preview.appendChild(el);
+      }
+      const def = defaultDef(tag);
+      const cleanup = draggable({
+        element: row,
+        getInitialData() {
+          return { type: "block", fragment: structuredClone(def) };
+        },
+      });
+      view.dndCleanups.push(cleanup);
+    });
+  });
+}
+
+/**
+ * Hide descendant rows of the dragged item so it appears collapsed during drag.
+ *
+ * @param {HTMLElement} parentRow
+ * @param {HTMLElement} container
+ */
+function hideDescendantRows(parentRow: HTMLElement, container: HTMLElement) {
+  const prefix = parentRow.dataset.path + "/";
+  const rows = container.querySelectorAll(".layers-tree .layer-row");
+  for (const r of rows) {
+    if ((r as HTMLElement).dataset.path?.startsWith(prefix)) {
+      (r as HTMLElement).style.display = "none";
+    }
+  }
+}
+
+/**
+ * @param {HTMLElement} rowEl
+ * @param {Record<string, unknown>} data
+ * @param {HTMLElement} container
+ */
+export function showLayerDropGap(
+  rowEl: HTMLElement,
+  data: Record<string, unknown>,
+  container: HTMLElement,
+) {
+  const instruction = extractInstruction(data);
+
+  // Clear previous drop-target highlight
+  if (view._currentDropTargetRow && view._currentDropTargetRow !== rowEl) {
+    view._currentDropTargetRow.classList.remove("drop-target");
+  }
+
+  if (!instruction || instruction.type === "instruction-blocked") {
+    clearLayerDropGap(container);
+    return;
+  }
+
+  if (instruction.type === "make-child") {
+    clearLayerDropGap(container);
+    rowEl.classList.add("drop-target");
+    view._currentDropTargetRow = rowEl;
+    return;
+  }
+
+  rowEl.classList.remove("drop-target");
+  view._currentDropTargetRow = rowEl;
+
+  // Shift rows to create gap
+  const rows = Array.from(container.querySelectorAll(".layers-tree .layer-row"));
+  const targetIdx = rows.indexOf(rowEl);
+  const gap = view.layerDragSourceHeight;
+
+  for (let i = 0; i < rows.length; i++) {
+    if ((rows[i] as HTMLElement).classList.contains("dragging")) continue;
+    if (instruction.type === "reorder-above") {
+      (rows[i] as HTMLElement).style.transform = i >= targetIdx ? `translateY(${gap}px)` : "";
+    } else {
+      (rows[i] as HTMLElement).style.transform = i > targetIdx ? `translateY(${gap}px)` : "";
+    }
+  }
+}
+
+/** @param {HTMLElement} container */
+export function clearLayerDropGap(container: HTMLElement) {
+  if (view._currentDropTargetRow) {
+    view._currentDropTargetRow.classList.remove("drop-target");
+    view._currentDropTargetRow = null;
+  }
+  const rows = container.querySelectorAll(".layers-tree .layer-row");
+  for (const r of rows) (r as HTMLElement).style.transform = "";
+}
+
+/**
+ * Apply a DnD instruction to the state
+ *
+ * @param {{ type: string }} instruction
+ * @param {Record<string, unknown>} srcData
+ * @param {JxPath} targetPath
+ */
+export function applyDropInstruction(
+  instruction: { type: string },
+  srcData: Record<string, unknown>,
+  targetPath: JxPath,
+) {
+  const doc = activeTab.value?.doc.document as JxMutableNode;
+  if (srcData.type === "tree-node") {
+    const fromPath = srcData.path as JxPath;
+    const targetParent = parentElementPath(targetPath) as JxPath;
+    const targetIdx = childIndex(targetPath) as number;
+
+    switch (instruction.type) {
+      case "reorder-above":
+        transactDoc(activeTab.value, (t) => mutateMoveNode(t, fromPath, targetParent, targetIdx));
+        break;
+      case "reorder-below":
+        transactDoc(activeTab.value, (t) =>
+          mutateMoveNode(t, fromPath, targetParent, targetIdx + 1),
+        );
+        break;
+      case "make-child": {
+        const target = getNodeAtPath(doc, targetPath);
+        const len = target?.children?.length || 0;
+        transactDoc(activeTab.value, (t) => mutateMoveNode(t, fromPath, targetPath, len));
+        break;
+      }
+    }
+  } else if (srcData.type === "block") {
+    const targetParent = parentElementPath(targetPath) as JxPath;
+    const targetIdx = childIndex(targetPath) as number;
+
+    switch (instruction.type) {
+      case "reorder-above":
+        transactDoc(activeTab.value, (t) =>
+          mutateInsertNode(
+            t,
+            targetParent,
+            targetIdx,
+            structuredClone(srcData.fragment as JxMutableNode),
+          ),
+        );
+        break;
+      case "reorder-below":
+        transactDoc(activeTab.value, (t) =>
+          mutateInsertNode(
+            t,
+            targetParent,
+            targetIdx + 1,
+            structuredClone(srcData.fragment as JxMutableNode),
+          ),
+        );
+        break;
+      case "make-child": {
+        const target = getNodeAtPath(doc, targetPath);
+        const len = target?.children?.length || 0;
+        transactDoc(activeTab.value, (t) =>
+          mutateInsertNode(t, targetPath, len, structuredClone(srcData.fragment as JxMutableNode)),
+        );
+        break;
+      }
+    }
+
+    // Auto-import to $elements if the dropped block is a custom component
+    const fragment = srcData.fragment as JxMutableNode | undefined;
+    const tag = fragment?.tagName;
+    if (tag && tag.includes("-")) {
+      const comp = componentRegistry.find(
+        (c: import("../files/components.js").ComponentEntry) => c.tagName === tag,
+      );
+      if (comp) {
+        const tab = activeTab.value;
+        const elements = tab?.doc.document?.$elements || [];
+        if (comp.source === "npm") {
+          const specifier = comp.modulePath ? `${comp.package}/${comp.modulePath}` : comp.package;
+          if (!specifier) return;
+          const alreadyImported = elements.some(
+            (e: JxMutableNode | string | { $ref: string }) => e === specifier || e === comp.package,
+          );
+          if (!alreadyImported) {
+            transact(activeTab.value, (doc: JxMutableNode) => {
+              if (!doc.$elements) doc.$elements = [];
+              doc.$elements.push(specifier);
+            });
+          }
+        } else {
+          const alreadyImported = elements.some((e: JxMutableNode | string | { $ref: string }) => {
+            const ref = typeof e === "object" && e !== null ? e.$ref : undefined;
+            return (
+              ref &&
+              (ref === `./${comp.path}` || ref.endsWith(comp.path.split("/").pop() as string))
+            );
+          });
+          if (!alreadyImported) {
+            const relPath = computeRelativePath(tab?.documentPath ?? null, comp.path);
+            transact(activeTab.value, (doc: JxMutableNode) => {
+              if (!doc.$elements) doc.$elements = [];
+              doc.$elements.push({ $ref: relPath });
+            });
+          }
+        }
+      }
+    }
+  }
+}