cytoscape-dom-node 1.3.0 → 2.0.1

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,141 @@ 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.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.
+
 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.
+
+## 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,229 @@
+"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 DomNodeRenderer = class {
+  constructor(cy, options = {}) {
+    __publicField(this, "cy");
+    __publicField(this, "nodeElements", /* @__PURE__ */ new Map());
+    __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();
+    });
+    this.cy = cy;
+    this.container = resolveDomContainer(cy, options);
+    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();
+  }
+  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);
+    this.resizeObserver.observe(element);
+    this.syncNodeSize(element);
+    this.syncNodePosition(node);
+    this.syncNodeState(node);
+  }
+  removeNode(node) {
+    const element = this.nodeElements.get(node.id());
+    if (!element) {
+      return;
+    }
+    this.resizeObserver.unobserve(element);
+    delete element.__cy_id;
+    this.nodeElements.delete(node.id());
+  }
+  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;
+  }
+};
+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\";\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 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\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 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  public constructor(cy: cytoscape.Core, options: DomNodeOptions = {}) {\n    this.cy = cy;\n    this.container = resolveDomContainer(cy, options);\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  }\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    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 element = this.nodeElements.get(node.id());\n\n    if (!element) {\n      return;\n    }\n\n    this.resizeObserver.unobserve(element);\n    delete element.__cy_id;\n    this.nodeElements.delete(node.id());\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\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,94 @@
+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;
+}
+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 resizeObserver;
+    private readonly container;
+    private readonly handleNodeAdd;
+    private readonly handleNodeRemove;
+    private readonly handleNodePosition;
+    private readonly handleNodeState;
+    private readonly handleViewport;
+    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;
+}
+
+/**
+ * Register the extension with Cytoscape.
+ */
+declare function register(cytoscapeInstance?: CytoscapeRegistry): void;
+
+export { DomNodeRenderer as CytoscapeDomNode, type DomNodeOptions, DomNodeRenderer, type ResizeObserverConstructor, register as default };

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+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;
+}
+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 resizeObserver;
+    private readonly container;
+    private readonly handleNodeAdd;
+    private readonly handleNodeRemove;
+    private readonly handleNodePosition;
+    private readonly handleNodeState;
+    private readonly handleViewport;
+    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;
+}
+
+/**
+ * Register the extension with Cytoscape.
+ */
+declare function register(cytoscapeInstance?: CytoscapeRegistry): void;
+
+export { DomNodeRenderer as CytoscapeDomNode, type DomNodeOptions, DomNodeRenderer, type ResizeObserverConstructor, register as default };