cytoscape-dom-node 1.3.0 → 2.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (C) 2021 Michael Wright <mjw@methodanalysis.com>
+Copyright (C) 2021-2026 Michael Wright <mjw@methodanalysis.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -6,83 +6,170 @@ rendered on top of the node, and the node will be set to the size of the DOM
 element.
 
 For a full working demo, see [codepen abWdVOG](https://codepen.io/mwri/pen/abWdVOG).
+There are also more demos in [./demos](./demos/README.md).
 
-## Depenedencies
+## History
 
-* cytoscape ^3.19.0
+v2.1.0 has bug fixes / improvements outstanding since v1.
+v2.0.0 - v2.0.1 is a typescript conversion, and SHOULD be backwards compatible with v1.
+v1.3.0 is the latest pre typescript incarnation.
+
+## Dependencies
+
+- cytoscape ^3.19.0
 
 ## Extension registration
 
-Either import/require `cytoscape-dom-node`, and register it as an extension with Cytoscape:
+Import `cytoscape-dom-node`, and register it as an extension with Cytoscape:
+
+```ts
+import cytoscape from "cytoscape";
+import cytoscapeDomNode from "cytoscape-dom-node";
+
+cytoscape.use(cytoscapeDomNode);
+```
+
+CommonJS is still supported:
 
 ```js
-const cytoscape = require('cytoscape');
-cytoscape.use(require('cytoscape-dom-node'));
+const cytoscape = require("cytoscape");
+const cytoscapeDomNode = require("cytoscape-dom-node");
+
+cytoscape.use(cytoscapeDomNode);
 ```
 
 Or it can be included via a `<script>` tag after `cytoscape`, and will register itself:
 
 ```html
 <script type="text/javascript" charset="utf8" src="path/to/cytoscape.js"></script>
-<script type="text/javascript" charset="utf8" src="path/to/cytoscape-dom-node.js"></script>
+<script
+  type="text/javascript"
+  charset="utf8"
+  src="path/to/cytoscape-dom-node.global.js"
+></script>
 ```
 
 ## Usage instructions
 
 Create a `cytoscape` instance and call `domNode` on it:
 
-```js
-let cy = cytoscape({
-    'container': document.getElementById('id-of-my-cytoscape-container'),
-    'elements': [],
+```ts
+const cy = cytoscape({
+  container: document.getElementById("id-of-my-cytoscape-container"),
+  elements: [],
 });
 
-cy.domNode();
+const domNodeRenderer = cy.domNode();
 ```
 
 Now add a node with `dom` in the data, set to a DOM element:
 
-```js
-let div = document.createElement("div");
+```ts
+const div = document.createElement("div");
 div.innerHTML = `node ${id}`;
 
 cy.add({
-    'data': {
-        'id':  id,
-        'dom': div,
-    },
+  data: {
+    dom: div,
+    id,
+  },
 });
 ```
 
 The `div` you created will be shown as the node now.
 
+You can retrieve the DOM element for a Cytoscape node id:
+
+```ts
+const nodeElement = domNodeRenderer.nodeDom(id);
+```
+
+The previous `node_dom(id)` method is kept as a backwards compatible alias.
+
+When a Cytoscape node is removed, `cytoscape-dom-node` removes the DOM element
+it appended for that node. Nodes using `skipNodeAppend` remain caller-owned and
+are not removed from the DOM.
+
 See [codepen abWdVOG](https://codepen.io/mwri/pen/abWdVOG) for a working
 example.
 
 ### Skip Node Append
-The `skip_node_append` option is a boolean flag (passed with node data) that controls whether the `cytoscape-dom-node` appends the provided node to the provided DOM container.
-By default, this option is set to false, meaning the `cytoscape-dom-node` will append the node to the container.
 
-However, in certain scenarios, such as when using EmberJS or another front-end framework, you might have already rendered the nodes to the DOM.
-In these cases, you can set `skip_node_append` to true to prevent the library from appending the node, allowing you to maintain control over the node's rendering process.
+The `skipNodeAppend` node data option controls whether `cytoscape-dom-node`
+appends the provided DOM node to the configured DOM container. By default,
+`cytoscape-dom-node` appends the node to the container.
 
-```js
-let div = document.querySelector("#alreadyRenderedNodeId");
+In certain scenarios, such as when using EmberJS or another front-end framework,
+you might have already rendered the nodes to the DOM. In these cases, set
+`skipNodeAppend` to `true` to keep control over rendering.
+
+```ts
+const div = document.querySelector("#alreadyRenderedNodeId");
 cy.add({
-    'data': {
-        'id': id,
-        'dom': div,
-        'skip_node_append': true,
-    }
-})
+  data: {
+    dom: div,
+    id,
+    skipNodeAppend: true,
+  },
+});
 ```
 
+The legacy `skip_node_append` name remains supported.
+
 ## Options
 
-One option is supported, `dom_container` allows an container element to be specified which
-will be used for nodes instead of the element it would otherwise create and use. It is the
-callers responsibility to style the given element appropriately, for example:
+`domContainer` allows a container element to be specified. It will be used for
+nodes instead of the element `cytoscape-dom-node` would otherwise create. It is
+the caller's responsibility to style the given element appropriately:
 
-```js
-cy.domNode({'dom_container': some_element});
+```ts
+cy.domNode({ domContainer: someElement });
+```
+
+The legacy `dom_container` name remains supported.
+
+`interactiveSelector` sets which child elements should receive native DOM
+interaction instead of becoming Cytoscape gestures. Matching controls get
+`pointer-events: auto`, and `pointerdown`, `mousedown`, and `touchstart` are
+stopped during capture so inputs and buttons do not start graph drags. It
+defaults to common controls:
+
+```ts
+cy.domNode({
+  interactiveSelector:
+    "input, button, select, textarea, a[href], [contenteditable]:not([contenteditable='false']), [data-cy-dom-node-interactive]",
+});
+```
+
+For draggable DOM-backed nodes, make the node shell pass pointer events through
+to Cytoscape and let the renderer re-enable matching controls:
+
+```css
+.dom-node {
+  pointer-events: none;
+}
+```
+
+Set `interactiveSelector` to `false` to disable this control isolation.
+
+## Interaction State
+
+DOM nodes mirror Cytoscape selection state with the `selected` class. Selected
+or grabbed nodes receive z-index `11`; other DOM nodes receive z-index `10`.
+
+## Development
+
+This package is authored in TypeScript and emits CommonJS, ESM, browser global,
+and declaration outputs into `dist`.
+
+Useful commands:
+
+```sh
+npm run lint
+npm run typecheck
+npm run test
+npm run test:coverage
+npm run build
+npm run docs
+npm run check
 ```

package/dist/index.cjs

@@ -0,0 +1,298 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CytoscapeDomNode: () => DomNodeRenderer,
+  DomNodeRenderer: () => DomNodeRenderer,
+  default: () => register
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_Z_INDEX = "10";
+var ACTIVE_Z_INDEX = "11";
+var SELECTED_CLASS_NAME = "selected";
+var DEFAULT_INTERACTIVE_SELECTOR = "input, button, select, textarea, a[href], [contenteditable]:not([contenteditable='false']), [data-cy-dom-node-interactive]";
+var DEFAULT_INTERACTIVE_EVENTS = ["pointerdown", "mousedown", "touchstart"];
+var DomNodeRenderer = class {
+  constructor(cy, options = {}) {
+    __publicField(this, "cy");
+    __publicField(this, "nodeElements", /* @__PURE__ */ new Map());
+    __publicField(this, "appendedNodeIds", /* @__PURE__ */ new Set());
+    __publicField(this, "interactiveElementBindings", /* @__PURE__ */ new Map());
+    __publicField(this, "interactiveEvents");
+    __publicField(this, "interactiveSelector");
+    __publicField(this, "resizeObserver");
+    __publicField(this, "container");
+    __publicField(this, "handleNodeAdd", (event) => {
+      this.addNode(event.target);
+    });
+    __publicField(this, "handleNodeRemove", (event) => {
+      this.removeNode(event.target);
+    });
+    __publicField(this, "handleNodePosition", (event) => {
+      this.syncNodePosition(event.target);
+    });
+    __publicField(this, "handleNodeState", (event) => {
+      this.syncNodeState(event.target);
+    });
+    __publicField(this, "handleViewport", () => {
+      this.syncViewport();
+    });
+    __publicField(this, "stopInteractiveEvent", (event) => {
+      event.stopPropagation();
+    });
+    var _a, _b;
+    this.cy = cy;
+    this.container = resolveDomContainer(cy, options);
+    this.interactiveEvents = (_a = options.interactiveEvents) != null ? _a : DEFAULT_INTERACTIVE_EVENTS;
+    this.interactiveSelector = (_b = options.interactiveSelector) != null ? _b : DEFAULT_INTERACTIVE_SELECTOR;
+    this.resizeObserver = new (resolveResizeObserver(options))((entries) => {
+      for (const entry of entries) {
+        this.syncNodeSize(entry.target);
+      }
+    });
+    this.bindEvents();
+    cy.nodes().forEach((node) => {
+      this.addNode(node);
+    });
+    this.syncViewport();
+  }
+  /**
+   * Return the DOM element that backs a Cytoscape node id.
+   */
+  nodeDom(id) {
+    return this.nodeElements.get(id);
+  }
+  /**
+   * @deprecated Use {@link nodeDom}.
+   */
+  node_dom(id) {
+    return this.nodeDom(id);
+  }
+  /**
+   * Remove event handlers and disconnect resize observation.
+   */
+  destroy() {
+    this.cy.off("add", "node", this.handleNodeAdd);
+    this.cy.off("remove", "node", this.handleNodeRemove);
+    this.cy.off("pan zoom", this.handleViewport);
+    this.cy.off("position bounds", "node", this.handleNodePosition);
+    this.cy.off("select unselect grab free", "node", this.handleNodeState);
+    this.resizeObserver.disconnect();
+    this.nodeElements.clear();
+    this.appendedNodeIds.clear();
+    this.clearInteractiveElements();
+  }
+  bindEvents() {
+    this.cy.on("add", "node", this.handleNodeAdd);
+    this.cy.on("remove", "node", this.handleNodeRemove);
+    this.cy.on("pan zoom", this.handleViewport);
+    this.cy.on("position bounds", "node", this.handleNodePosition);
+    this.cy.on("select unselect grab free", "node", this.handleNodeState);
+  }
+  addNode(node) {
+    const data = node.data();
+    const element = data.dom;
+    if (!element) {
+      return;
+    }
+    const nodeId = node.id();
+    const shouldAppend = data.skipNodeAppend !== true && data.skip_node_append !== true;
+    if (shouldAppend && element.parentNode !== this.container) {
+      this.container.appendChild(element);
+    }
+    element.__cy_id = nodeId;
+    this.nodeElements.set(nodeId, element);
+    if (shouldAppend) {
+      this.appendedNodeIds.add(nodeId);
+    } else {
+      this.appendedNodeIds.delete(nodeId);
+    }
+    this.bindInteractiveElements(nodeId, element);
+    this.resizeObserver.observe(element);
+    this.syncNodeSize(element);
+    this.syncNodePosition(node);
+    this.syncNodeState(node);
+  }
+  removeNode(node) {
+    var _a;
+    const nodeId = node.id();
+    const element = this.nodeElements.get(nodeId);
+    if (!element) {
+      return;
+    }
+    this.resizeObserver.unobserve(element);
+    delete element.__cy_id;
+    this.nodeElements.delete(nodeId);
+    this.clearInteractiveElements(nodeId);
+    if (this.appendedNodeIds.delete(nodeId)) {
+      (_a = element.parentNode) == null ? void 0 : _a.removeChild(element);
+    }
+  }
+  syncViewport() {
+    const pan = this.cy.pan();
+    const zoom = this.cy.zoom();
+    const transform = `translate(${String(pan.x)}px, ${String(
+      pan.y
+    )}px) scale(${String(zoom)})`;
+    setMsTransform(this.container, transform);
+    this.container.style.transform = transform;
+  }
+  syncNodeSize(element) {
+    if (!element.__cy_id) {
+      return;
+    }
+    const node = this.cy.getElementById(element.__cy_id);
+    if (node.empty()) {
+      return;
+    }
+    node.style({
+      height: element.offsetHeight,
+      shape: "rectangle",
+      width: element.offsetWidth
+    });
+  }
+  syncNodePosition(node) {
+    const element = this.nodeElements.get(node.id());
+    if (!element) {
+      return;
+    }
+    const position = node.position();
+    const transform = `translate(-50%, -50%) translate(${position.x.toFixed(
+      2
+    )}px, ${position.y.toFixed(2)}px)`;
+    element.style.webkitTransform = transform;
+    setMsTransform(element, transform);
+    element.style.transform = transform;
+    element.style.display = "inline";
+    element.style.position = "absolute";
+  }
+  syncNodeState(node) {
+    const element = this.nodeElements.get(node.id());
+    if (!element) {
+      return;
+    }
+    const isSelected = node.selected();
+    const isActive = isSelected || node.grabbed();
+    element.classList.toggle(SELECTED_CLASS_NAME, isSelected);
+    element.style.zIndex = isActive ? ACTIVE_Z_INDEX : DEFAULT_Z_INDEX;
+  }
+  bindInteractiveElements(nodeId, root) {
+    this.clearInteractiveElements(nodeId);
+    if (!this.interactiveSelector) {
+      return;
+    }
+    const elements = root.querySelectorAll(this.interactiveSelector);
+    const bindings = [];
+    for (const element of elements) {
+      bindings.push({
+        element,
+        previousPointerEvents: element.style.pointerEvents
+      });
+      element.style.pointerEvents = "auto";
+      for (const eventName of this.interactiveEvents) {
+        element.addEventListener(eventName, this.stopInteractiveEvent, true);
+      }
+    }
+    if (bindings.length > 0) {
+      this.interactiveElementBindings.set(nodeId, bindings);
+    }
+  }
+  clearInteractiveElements(nodeId) {
+    if (nodeId) {
+      this.clearInteractiveElementBindings(nodeId);
+      return;
+    }
+    for (const id of this.interactiveElementBindings.keys()) {
+      this.clearInteractiveElementBindings(id);
+    }
+  }
+  clearInteractiveElementBindings(nodeId) {
+    const bindings = this.interactiveElementBindings.get(nodeId);
+    if (!bindings) {
+      return;
+    }
+    for (const binding of bindings) {
+      binding.element.style.pointerEvents = binding.previousPointerEvents;
+      for (const eventName of this.interactiveEvents) {
+        binding.element.removeEventListener(eventName, this.stopInteractiveEvent, true);
+      }
+    }
+    this.interactiveElementBindings.delete(nodeId);
+  }
+};
+function register(cytoscapeInstance) {
+  if (!cytoscapeInstance) {
+    return;
+  }
+  cytoscapeInstance(
+    "core",
+    "domNode",
+    function domNode(options) {
+      return new DomNodeRenderer(this, options);
+    }
+  );
+}
+function resolveDomContainer(cy, options) {
+  var _a;
+  const providedContainer = (_a = options.domContainer) != null ? _a : options.dom_container;
+  if (providedContainer) {
+    return providedContainer;
+  }
+  const cyContainer = cy.container();
+  const canvas = cyContainer == null ? void 0 : cyContainer.querySelector("canvas");
+  if (!(canvas == null ? void 0 : canvas.parentNode)) {
+    throw new Error(
+      "cytoscape-dom-node requires a Cytoscape container with a canvas, or a domContainer option."
+    );
+  }
+  const container = document.createElement("div");
+  container.style.position = "absolute";
+  container.style.transformOrigin = "0 0";
+  container.style.zIndex = DEFAULT_Z_INDEX;
+  canvas.parentNode.appendChild(container);
+  return container;
+}
+function resolveResizeObserver(options) {
+  var _a;
+  const ResizeObserverClass = (_a = options.resizeObserver) != null ? _a : globalThis.ResizeObserver;
+  if (!ResizeObserverClass) {
+    throw new Error(
+      "cytoscape-dom-node requires ResizeObserver. Provide a polyfill or pass resizeObserver."
+    );
+  }
+  return ResizeObserverClass;
+}
+function setMsTransform(element, transform) {
+  element.style.msTransform = transform;
+}
+var globalCytoscape = globalThis;
+if (globalCytoscape.cytoscape) {
+  register(globalCytoscape.cytoscape);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CytoscapeDomNode,
+  DomNodeRenderer
+});
+module.exports = Object.assign(module.exports.default, module.exports);
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Index.\n *\n * @packageDocumentation\n */\n\nimport type cytoscape from \"cytoscape\";\n\nconst DEFAULT_Z_INDEX = \"10\";\nconst ACTIVE_Z_INDEX = \"11\";\nconst SELECTED_CLASS_NAME = \"selected\";\nconst DEFAULT_INTERACTIVE_SELECTOR =\n  \"input, button, select, textarea, a[href], [contenteditable]:not([contenteditable='false']), [data-cy-dom-node-interactive]\";\nconst DEFAULT_INTERACTIVE_EVENTS = [\"pointerdown\", \"mousedown\", \"touchstart\"] as const;\n\ntype CytoscapeRegistry = typeof cytoscape;\n\n/**\n * Constructor shape for ResizeObserver implementations or polyfills.\n */\nexport type ResizeObserverConstructor = new (\n  callback: ResizeObserverCallback,\n) => ResizeObserver;\n\ntype DomNodeElement = HTMLElement & {\n  __cy_id?: string;\n};\n\ninterface InteractiveElementBinding {\n  element: HTMLElement;\n  previousPointerEvents: string;\n}\n\ninterface DomNodeData {\n  dom?: HTMLElement;\n  skipNodeAppend?: boolean;\n  skip_node_append?: boolean;\n}\n\n/**\n * Options for {@link DomNodeRenderer}.\n */\nexport interface DomNodeOptions {\n  /**\n   * Container that receives node DOM elements. When omitted, the extension\n   * creates an absolutely positioned overlay next to Cytoscape's canvas.\n   */\n  domContainer?: HTMLElement;\n\n  /**\n   * @deprecated Use `domContainer`.\n   */\n  dom_container?: HTMLElement;\n\n  /**\n   * ResizeObserver implementation. This is mainly useful for tests or\n   * browser environments that provide a polyfill.\n   */\n  resizeObserver?: ResizeObserverConstructor;\n\n  /**\n   * Selector for child controls that should receive native DOM interaction\n   * instead of starting Cytoscape gestures. Set to `false` to disable this\n   * automatic event isolation.\n   */\n  interactiveSelector?: string | false;\n\n  /**\n   * Event names stopped on interactive child controls during the capture phase.\n   */\n  interactiveEvents?: readonly string[];\n}\n\ndeclare global {\n  namespace cytoscape {\n    interface Core {\n      /**\n       * Enable DOM-backed Cytoscape nodes for this core instance.\n       */\n      domNode(options?: DomNodeOptions): DomNodeRenderer;\n    }\n  }\n}\n\ndeclare module \"cytoscape\" {\n  namespace cytoscape {\n    interface Core {\n      /**\n       * Enable DOM-backed Cytoscape nodes for this core instance.\n       */\n      domNode(options?: DomNodeOptions): DomNodeRenderer;\n    }\n  }\n}\n\n/**\n * Keeps Cytoscape node positions, dimensions, and interaction state mirrored\n * onto caller-supplied DOM elements.\n */\nexport class DomNodeRenderer {\n  private readonly cy: cytoscape.Core;\n  private readonly nodeElements = new Map<string, DomNodeElement>();\n  private readonly appendedNodeIds = new Set<string>();\n  private readonly interactiveElementBindings = new Map<\n    string,\n    InteractiveElementBinding[]\n  >();\n  private readonly interactiveEvents: readonly string[];\n  private readonly interactiveSelector: string | false;\n  private readonly resizeObserver: ResizeObserver;\n  private readonly container: HTMLElement;\n\n  private readonly handleNodeAdd = (event: cytoscape.EventObject): void => {\n    this.addNode(event.target as cytoscape.NodeSingular);\n  };\n\n  private readonly handleNodeRemove = (event: cytoscape.EventObject): void => {\n    this.removeNode(event.target as cytoscape.NodeSingular);\n  };\n\n  private readonly handleNodePosition = (event: cytoscape.EventObject): void => {\n    this.syncNodePosition(event.target as cytoscape.NodeSingular);\n  };\n\n  private readonly handleNodeState = (event: cytoscape.EventObject): void => {\n    this.syncNodeState(event.target as cytoscape.NodeSingular);\n  };\n\n  private readonly handleViewport = (): void => {\n    this.syncViewport();\n  };\n\n  private readonly stopInteractiveEvent = (event: Event): void => {\n    event.stopPropagation();\n  };\n\n  public constructor(cy: cytoscape.Core, options: DomNodeOptions = {}) {\n    this.cy = cy;\n    this.container = resolveDomContainer(cy, options);\n    this.interactiveEvents = options.interactiveEvents ?? DEFAULT_INTERACTIVE_EVENTS;\n    this.interactiveSelector =\n      options.interactiveSelector ?? DEFAULT_INTERACTIVE_SELECTOR;\n    this.resizeObserver = new (resolveResizeObserver(options))((entries) => {\n      for (const entry of entries) {\n        this.syncNodeSize(entry.target as DomNodeElement);\n      }\n    });\n\n    this.bindEvents();\n    cy.nodes().forEach((node) => {\n      this.addNode(node);\n    });\n    this.syncViewport();\n  }\n\n  /**\n   * Return the DOM element that backs a Cytoscape node id.\n   */\n  public nodeDom(id: string): HTMLElement | undefined {\n    return this.nodeElements.get(id);\n  }\n\n  /**\n   * @deprecated Use {@link nodeDom}.\n   */\n  public node_dom(id: string): HTMLElement | undefined {\n    return this.nodeDom(id);\n  }\n\n  /**\n   * Remove event handlers and disconnect resize observation.\n   */\n  public destroy(): void {\n    this.cy.off(\"add\", \"node\", this.handleNodeAdd);\n    this.cy.off(\"remove\", \"node\", this.handleNodeRemove);\n    this.cy.off(\"pan zoom\", this.handleViewport);\n    this.cy.off(\"position bounds\", \"node\", this.handleNodePosition);\n    this.cy.off(\"select unselect grab free\", \"node\", this.handleNodeState);\n    this.resizeObserver.disconnect();\n    this.nodeElements.clear();\n    this.appendedNodeIds.clear();\n    this.clearInteractiveElements();\n  }\n\n  private bindEvents(): void {\n    this.cy.on(\"add\", \"node\", this.handleNodeAdd);\n    this.cy.on(\"remove\", \"node\", this.handleNodeRemove);\n    this.cy.on(\"pan zoom\", this.handleViewport);\n    this.cy.on(\"position bounds\", \"node\", this.handleNodePosition);\n    this.cy.on(\"select unselect grab free\", \"node\", this.handleNodeState);\n  }\n\n  private addNode(node: cytoscape.NodeSingular): void {\n    const data = node.data() as DomNodeData;\n    const element = data.dom as DomNodeElement | undefined;\n\n    if (!element) {\n      return;\n    }\n\n    const nodeId = node.id();\n    const shouldAppend = data.skipNodeAppend !== true && data.skip_node_append !== true;\n\n    if (shouldAppend && element.parentNode !== this.container) {\n      this.container.appendChild(element);\n    }\n\n    element.__cy_id = nodeId;\n    this.nodeElements.set(nodeId, element);\n    if (shouldAppend) {\n      this.appendedNodeIds.add(nodeId);\n    } else {\n      this.appendedNodeIds.delete(nodeId);\n    }\n    this.bindInteractiveElements(nodeId, element);\n    this.resizeObserver.observe(element);\n\n    this.syncNodeSize(element);\n    this.syncNodePosition(node);\n    this.syncNodeState(node);\n  }\n\n  private removeNode(node: cytoscape.NodeSingular): void {\n    const nodeId = node.id();\n    const element = this.nodeElements.get(nodeId);\n\n    if (!element) {\n      return;\n    }\n\n    this.resizeObserver.unobserve(element);\n    delete element.__cy_id;\n    this.nodeElements.delete(nodeId);\n    this.clearInteractiveElements(nodeId);\n\n    if (this.appendedNodeIds.delete(nodeId)) {\n      element.parentNode?.removeChild(element);\n    }\n  }\n\n  private syncViewport(): void {\n    const pan = this.cy.pan();\n    const zoom = this.cy.zoom();\n    const transform = `translate(${String(pan.x)}px, ${String(\n      pan.y,\n    )}px) scale(${String(zoom)})`;\n\n    setMsTransform(this.container, transform);\n    this.container.style.transform = transform;\n  }\n\n  private syncNodeSize(element: DomNodeElement): void {\n    if (!element.__cy_id) {\n      return;\n    }\n\n    const node = this.cy.getElementById(element.__cy_id);\n\n    if (node.empty()) {\n      return;\n    }\n\n    node.style({\n      height: element.offsetHeight,\n      shape: \"rectangle\",\n      width: element.offsetWidth,\n    });\n  }\n\n  private syncNodePosition(node: cytoscape.NodeSingular): void {\n    const element = this.nodeElements.get(node.id());\n\n    if (!element) {\n      return;\n    }\n\n    const position = node.position();\n    const transform = `translate(-50%, -50%) translate(${position.x.toFixed(\n      2,\n    )}px, ${position.y.toFixed(2)}px)`;\n\n    element.style.webkitTransform = transform;\n    setMsTransform(element, transform);\n    element.style.transform = transform;\n    element.style.display = \"inline\";\n    element.style.position = \"absolute\";\n  }\n\n  private syncNodeState(node: cytoscape.NodeSingular): void {\n    const element = this.nodeElements.get(node.id());\n\n    if (!element) {\n      return;\n    }\n\n    const isSelected = node.selected();\n    const isActive = isSelected || node.grabbed();\n\n    element.classList.toggle(SELECTED_CLASS_NAME, isSelected);\n    element.style.zIndex = isActive ? ACTIVE_Z_INDEX : DEFAULT_Z_INDEX;\n  }\n\n  private bindInteractiveElements(nodeId: string, root: DomNodeElement): void {\n    this.clearInteractiveElements(nodeId);\n\n    if (!this.interactiveSelector) {\n      return;\n    }\n\n    const elements = root.querySelectorAll<HTMLElement>(this.interactiveSelector);\n    const bindings: InteractiveElementBinding[] = [];\n\n    for (const element of elements) {\n      bindings.push({\n        element,\n        previousPointerEvents: element.style.pointerEvents,\n      });\n      element.style.pointerEvents = \"auto\";\n\n      for (const eventName of this.interactiveEvents) {\n        element.addEventListener(eventName, this.stopInteractiveEvent, true);\n      }\n    }\n\n    if (bindings.length > 0) {\n      this.interactiveElementBindings.set(nodeId, bindings);\n    }\n  }\n\n  private clearInteractiveElements(nodeId?: string): void {\n    if (nodeId) {\n      this.clearInteractiveElementBindings(nodeId);\n      return;\n    }\n\n    for (const id of this.interactiveElementBindings.keys()) {\n      this.clearInteractiveElementBindings(id);\n    }\n  }\n\n  private clearInteractiveElementBindings(nodeId: string): void {\n    const bindings = this.interactiveElementBindings.get(nodeId);\n\n    if (!bindings) {\n      return;\n    }\n\n    for (const binding of bindings) {\n      binding.element.style.pointerEvents = binding.previousPointerEvents;\n\n      for (const eventName of this.interactiveEvents) {\n        binding.element.removeEventListener(eventName, this.stopInteractiveEvent, true);\n      }\n    }\n\n    this.interactiveElementBindings.delete(nodeId);\n  }\n}\n\n/**\n * Backwards-compatible class export for consumers that referenced the previous\n * implementation name from bundled output.\n */\nexport { DomNodeRenderer as CytoscapeDomNode };\n\n/**\n * Register the extension with Cytoscape.\n */\nexport default function register(cytoscapeInstance?: CytoscapeRegistry): void {\n  if (!cytoscapeInstance) {\n    return;\n  }\n\n  cytoscapeInstance(\n    \"core\",\n    \"domNode\",\n    function domNode(this: cytoscape.Core, options?: DomNodeOptions): DomNodeRenderer {\n      return new DomNodeRenderer(this, options);\n    },\n  );\n}\n\nfunction resolveDomContainer(cy: cytoscape.Core, options: DomNodeOptions): HTMLElement {\n  const providedContainer = options.domContainer ?? options.dom_container;\n\n  if (providedContainer) {\n    return providedContainer;\n  }\n\n  const cyContainer = cy.container();\n  const canvas = cyContainer?.querySelector(\"canvas\");\n\n  if (!canvas?.parentNode) {\n    throw new Error(\n      \"cytoscape-dom-node requires a Cytoscape container with a canvas, or a domContainer option.\",\n    );\n  }\n\n  const container = document.createElement(\"div\");\n  container.style.position = \"absolute\";\n  container.style.transformOrigin = \"0 0\";\n  container.style.zIndex = DEFAULT_Z_INDEX;\n\n  canvas.parentNode.appendChild(container);\n\n  return container;\n}\n\nfunction resolveResizeObserver(options: DomNodeOptions): ResizeObserverConstructor {\n  const ResizeObserverClass = options.resizeObserver ?? globalThis.ResizeObserver;\n\n  if (!ResizeObserverClass) {\n    throw new Error(\n      \"cytoscape-dom-node requires ResizeObserver. Provide a polyfill or pass resizeObserver.\",\n    );\n  }\n\n  return ResizeObserverClass;\n}\n\nfunction setMsTransform(element: HTMLElement, transform: string): void {\n  (element.style as CSSStyleDeclaration & { msTransform?: string }).msTransform =\n    transform;\n}\n\nconst globalCytoscape = globalThis as typeof globalThis & {\n  cytoscape?: CytoscapeRegistry;\n};\n\n/* v8 ignore next 3 */\nif (globalCytoscape.cytoscape) {\n  register(globalCytoscape.cytoscape);\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.mts

@@ -0,0 +1,112 @@
+import cytoscape from 'cytoscape';
+
+/**
+ * Index.
+ *
+ * @packageDocumentation
+ */
+
+type CytoscapeRegistry = typeof cytoscape;
+/**
+ * Constructor shape for ResizeObserver implementations or polyfills.
+ */
+type ResizeObserverConstructor = new (callback: ResizeObserverCallback) => ResizeObserver;
+/**
+ * Options for {@link DomNodeRenderer}.
+ */
+interface DomNodeOptions {
+    /**
+     * Container that receives node DOM elements. When omitted, the extension
+     * creates an absolutely positioned overlay next to Cytoscape's canvas.
+     */
+    domContainer?: HTMLElement;
+    /**
+     * @deprecated Use `domContainer`.
+     */
+    dom_container?: HTMLElement;
+    /**
+     * ResizeObserver implementation. This is mainly useful for tests or
+     * browser environments that provide a polyfill.
+     */
+    resizeObserver?: ResizeObserverConstructor;
+    /**
+     * Selector for child controls that should receive native DOM interaction
+     * instead of starting Cytoscape gestures. Set to `false` to disable this
+     * automatic event isolation.
+     */
+    interactiveSelector?: string | false;
+    /**
+     * Event names stopped on interactive child controls during the capture phase.
+     */
+    interactiveEvents?: readonly string[];
+}
+declare global {
+    namespace cytoscape {
+        interface Core {
+            /**
+             * Enable DOM-backed Cytoscape nodes for this core instance.
+             */
+            domNode(options?: DomNodeOptions): DomNodeRenderer;
+        }
+    }
+}
+declare module "cytoscape" {
+    namespace cytoscape {
+        interface Core {
+            /**
+             * Enable DOM-backed Cytoscape nodes for this core instance.
+             */
+            domNode(options?: DomNodeOptions): DomNodeRenderer;
+        }
+    }
+}
+/**
+ * Keeps Cytoscape node positions, dimensions, and interaction state mirrored
+ * onto caller-supplied DOM elements.
+ */
+declare class DomNodeRenderer {
+    private readonly cy;
+    private readonly nodeElements;
+    private readonly appendedNodeIds;
+    private readonly interactiveElementBindings;
+    private readonly interactiveEvents;
+    private readonly interactiveSelector;
+    private readonly resizeObserver;
+    private readonly container;
+    private readonly handleNodeAdd;
+    private readonly handleNodeRemove;
+    private readonly handleNodePosition;
+    private readonly handleNodeState;
+    private readonly handleViewport;
+    private readonly stopInteractiveEvent;
+    constructor(cy: cytoscape.Core, options?: DomNodeOptions);
+    /**
+     * Return the DOM element that backs a Cytoscape node id.
+     */
+    nodeDom(id: string): HTMLElement | undefined;
+    /**
+     * @deprecated Use {@link nodeDom}.
+     */
+    node_dom(id: string): HTMLElement | undefined;
+    /**
+     * Remove event handlers and disconnect resize observation.
+     */
+    destroy(): void;
+    private bindEvents;
+    private addNode;
+    private removeNode;
+    private syncViewport;
+    private syncNodeSize;
+    private syncNodePosition;
+    private syncNodeState;
+    private bindInteractiveElements;
+    private clearInteractiveElements;
+    private clearInteractiveElementBindings;
+}
+
+/**
+ * Register the extension with Cytoscape.
+ */
+declare function register(cytoscapeInstance?: CytoscapeRegistry): void;
+
+export { DomNodeRenderer as CytoscapeDomNode, type DomNodeOptions, DomNodeRenderer, type ResizeObserverConstructor, register as default };