@vanduo-oss/vd3-flowchart 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export {
   computeLayout,
   LAYOUT_MODES,
   VD_FLOWCHART_VERSION,
+  FLOWCHART_DOCUMENT_VERSION,
   FLOWCHART_NODE_TYPES,
   FLOWCHART_PORTS,
   FLOWCHART_EDGE_MARKERS,

package/dist/index.js

@@ -258,7 +258,8 @@ var EDGE_STROKE_PRESETS = [
   { id: "medium", label: "Medium", width: DEFAULT_EDGE_STROKE_WIDTH },
   { id: "bold", label: "Bold", width: 3.5 }
 ];
-var VD_FLOWCHART_VERSION = "1.2.0";
+var VD_FLOWCHART_VERSION = "1.3.0";
+var FLOWCHART_DOCUMENT_VERSION = "1.2.0";
 var FLOWCHART_NODE_TYPES = [
   "rounded-rect",
   "rect",
@@ -495,17 +496,45 @@ function normalizeEdge(rawEdge, index, nodeIds, usedIds) {
   syncEdgeKind(edge);
   return edge;
 }
+function parseDocumentVersion(value) {
+  const raw = typeof value === "number" && Number.isFinite(value) ? String(value) : typeof value === "string" ? value.trim() : "";
+  const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(raw);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2] ?? 0),
+    patch: Number(match[3] ?? 0)
+  };
+}
+function isSupportedDocumentVersion(value) {
+  const parsed = parseDocumentVersion(value);
+  const max = parseDocumentVersion(FLOWCHART_DOCUMENT_VERSION);
+  if (!parsed || !max || parsed.major !== max.major) return false;
+  if (parsed.minor > max.minor) return false;
+  if (parsed.minor === max.minor && parsed.patch > max.patch) return false;
+  return true;
+}
 function normalizeDocument(input) {
   let source = input;
   if (typeof source === "string") {
     try {
       source = JSON.parse(source);
     } catch {
-      source = {};
+      throw new TypeError("Invalid flowchart JSON. The current document was not changed.");
     }
   }
   if (!isPlainObject(source)) {
-    source = {};
+    throw new TypeError("A flowchart document must be an object.");
+  }
+  if (source.version !== void 0 && !isSupportedDocumentVersion(source.version)) {
+    throw new RangeError(
+      `Unsupported flowchart document version: ${String(source.version)}. Supported through ${FLOWCHART_DOCUMENT_VERSION}.`
+    );
+  }
+  for (const key of ["nodes", "edges"]) {
+    if (source[key] !== void 0 && !Array.isArray(source[key])) {
+      throw new TypeError(`Flowchart ${key} must be an array.`);
+    }
   }
   const usedNodeIds = /* @__PURE__ */ new Set();
   const nodes = (Array.isArray(source.nodes) ? source.nodes : []).slice(0, MAX_NODES).map((node, index) => normalizeNode(node, index, usedNodeIds));
@@ -513,7 +542,7 @@ function normalizeDocument(input) {
   const usedEdgeIds = /* @__PURE__ */ new Set();
   const edges = (Array.isArray(source.edges) ? source.edges : []).slice(0, MAX_EDGES).map((edge, index) => normalizeEdge(edge, index, nodeIds, usedEdgeIds)).filter(Boolean);
   return {
-    version: VD_FLOWCHART_VERSION,
+    version: FLOWCHART_DOCUMENT_VERSION,
     viewport: normalizeViewport(source.viewport),
     nodes,
     edges
@@ -968,6 +997,8 @@ function getBounds(nodes) {
 function createField(labelText, control) {
   const wrapper = createElement("div", { className: "vd-flowchart-field" });
   const label = createElement("label", { text: labelText });
+  control.id || (control.id = nextId("flowchart-field"));
+  label.htmlFor = control.id;
   wrapper.appendChild(label);
   wrapper.appendChild(control);
   return wrapper;
@@ -1352,14 +1383,127 @@ var VdFlowchart = class {
     this.jsonActions.appendChild(this.loadJsonButton);
     this.jsonPanel.appendChild(this.jsonTextarea);
     this.jsonPanel.appendChild(this.jsonActions);
+    this.jsonStatus = createElement("p", { className: "vd-flowchart-json-status" });
+    this.jsonStatus.setAttribute("role", "status");
+    this.jsonPanel.appendChild(this.jsonStatus);
     this.inspectorPanel.appendChild(this.jsonPanel);
     this.body.appendChild(this.palettePanel);
     this.body.appendChild(this.canvasEl);
     this.body.appendChild(this.inspectorPanel);
     this.root.appendChild(this.toolbar);
     this.root.appendChild(this.body);
+    this.buildGraphOutline();
     this.element.appendChild(this.root);
   }
+  buildGraphOutline() {
+    this.graphOutline = createElement("details", { className: "vd-flowchart-outline" });
+    this.graphOutline.appendChild(createElement("summary", { text: "Graph outline" }));
+    this.graphOutline.addEventListener("toggle", () => {
+      if (this.graphOutline.open) this.renderGraphOutline();
+    });
+    this.graphStatus = createElement("p", { className: "vd-flowchart-sr-only" });
+    this.graphStatus.setAttribute("role", "status");
+    this.canvasEl.appendChild(this.graphStatus);
+    this.graphControls = createElement("div", { className: "vd-flowchart-outline-controls" });
+    this.graphNodeSelect = createElement("select");
+    this.graphNodeSelect.setAttribute("aria-label", "Selected node");
+    this.graphNodeSelect.addEventListener(
+      "change",
+      () => this.selectNode(this.graphNodeSelect.value)
+    );
+    this.graphTargetSelect = createElement("select");
+    this.graphTargetSelect.setAttribute("aria-label", "Connection target");
+    this.graphTargetSelect.addEventListener("change", () => this.renderGraphOutline());
+    this.graphConnectButton = createElement("button", {
+      text: "Connect nodes",
+      type: "button",
+      className: "vd-flowchart-btn"
+    });
+    this.graphConnectButton.addEventListener("click", () => {
+      if (this.readonly || this.graphNodeSelect.value === this.graphTargetSelect.value) {
+        return;
+      }
+      this.addEdge({
+        from: this.graphNodeSelect.value,
+        to: this.graphTargetSelect.value,
+        autoPort: true
+      });
+    });
+    this.graphEditButton = createElement("button", {
+      text: "Edit selected label",
+      type: "button",
+      className: "vd-flowchart-btn"
+    });
+    this.graphEditButton.addEventListener(
+      "click",
+      () => this.startTextEdit(this.graphNodeSelect.value)
+    );
+    this.graphControls.append(
+      createField("Selected node", this.graphNodeSelect),
+      createField("Connection target", this.graphTargetSelect),
+      this.graphConnectButton,
+      this.graphEditButton
+    );
+    this.graphOutline.appendChild(this.graphControls);
+    this.graphList = createElement("ul");
+    this.graphList.setAttribute("aria-label", "Nodes and connections");
+    this.graphOutline.appendChild(this.graphList);
+    this.root.appendChild(this.graphOutline);
+    this.canvasEl.setAttribute("role", "group");
+    this.canvasEl.setAttribute(
+      "aria-label",
+      "Diagram canvas. Arrow keys select nodes; Enter edits a label. Graph outline provides connections."
+    );
+    this.jsonTextarea.setAttribute("aria-label", "Flowchart JSON");
+  }
+  renderGraphOutline() {
+    if (!this.graphOutline) return;
+    const nodes = this.documentData.nodes;
+    const edges = this.documentData.edges;
+    const labels = new Map(nodes.map((node) => [node.id, node.text || node.id]));
+    const selected = this.selection?.kind === "node" ? this.selection.id : null;
+    this.graphStatus.textContent = selected ? `Selected: ${labels.get(selected)}. ${nodes.length} nodes, ${edges.length} connections.` : `${nodes.length} nodes, ${edges.length} connections.`;
+    if (!this.graphOutline.open) return;
+    const signature = JSON.stringify([
+      nodes.map((node) => [node.id, node.text]),
+      edges.map((edge) => [edge.id, edge.from.nodeId, edge.to.nodeId, edge.label])
+    ]);
+    if (signature !== this.graphSignature) {
+      this.graphSignature = signature;
+      for (const select of [this.graphNodeSelect, this.graphTargetSelect]) {
+        const previous = select.value;
+        select.replaceChildren();
+        for (const node of nodes)
+          select.appendChild(
+            createElement("option", { value: node.id, text: labels.get(node.id) })
+          );
+        if (labels.has(previous)) select.value = previous;
+      }
+      this.graphList.replaceChildren();
+      const outgoing = new Map(nodes.map((node) => [node.id, []]));
+      const incoming = new Map(nodes.map((node) => [node.id, []]));
+      for (const edge of edges) {
+        outgoing.get(edge.from.nodeId)?.push(`${labels.get(edge.to.nodeId)}${edge.label ? ` (${edge.label})` : ""}`);
+        incoming.get(edge.to.nodeId)?.push(labels.get(edge.from.nodeId));
+      }
+      for (const node of nodes) {
+        const to = outgoing.get(node.id);
+        const from = incoming.get(node.id);
+        const relationships = [
+          to.length ? `Connects to ${to.join(", ")}.` : "No outgoing connections.",
+          from.length ? `Connected from ${from.join(", ")}.` : ""
+        ];
+        this.graphList.appendChild(
+          createElement("li", { text: `${labels.get(node.id)}. ${relationships.join(" ")}` })
+        );
+      }
+    }
+    if (selected) this.graphNodeSelect.value = selected;
+    this.graphNodeSelect.disabled = nodes.length === 0;
+    this.graphTargetSelect.disabled = this.readonly || nodes.length < 2;
+    this.graphConnectButton.disabled = this.readonly || nodes.length < 2 || this.graphNodeSelect.value === this.graphTargetSelect.value;
+    this.graphEditButton.disabled = this.readonly || nodes.length === 0;
+  }
   bindEvents() {
     this.toolbar.addEventListener("click", this.handleToolbarClick);
     this.arrangeSelect.addEventListener("change", this.handleArrangeChange);
@@ -1466,7 +1610,12 @@ var VdFlowchart = class {
       return;
     }
     if (action === "load" && !this.readonly) {
-      this.load(this.jsonTextarea.value);
+      try {
+        this.load(this.jsonTextarea.value);
+        this.jsonStatus.textContent = "";
+      } catch (error) {
+        this.jsonStatus.textContent = error.message;
+      }
     }
   }
   handleSelectionFieldInput(event) {
@@ -1537,10 +1686,31 @@ var VdFlowchart = class {
     }
   }
   handleKeyDown(event) {
-    if (this.readonly) return;
     if (event.target && (event.target.tagName === "INPUT" || event.target.tagName === "TEXTAREA" || event.target.tagName === "SELECT")) {
       return;
     }
+    if (event.target === this.canvasEl) {
+      const nodes = this.documentData.nodes;
+      const index = nodes.findIndex((node) => node.id === this.selection?.id);
+      let next = -1;
+      if (event.key === "ArrowDown" || event.key === "ArrowRight")
+        next = (index + 1) % nodes.length;
+      if (event.key === "ArrowUp" || event.key === "ArrowLeft")
+        next = index < 0 ? nodes.length - 1 : (index - 1 + nodes.length) % nodes.length;
+      if (event.key === "Home") next = 0;
+      if (event.key === "End") next = nodes.length - 1;
+      if (nodes[next]) {
+        event.preventDefault();
+        this.selectNode(nodes[next].id);
+        return;
+      }
+      if (event.key === "Enter" && !this.readonly && this.selection?.kind === "node") {
+        event.preventDefault();
+        this.startTextEdit(this.selection.id);
+        return;
+      }
+    }
+    if (this.readonly) return;
     if (event.key === "Escape" && this.activeTool) {
       event.preventDefault();
       this.setActiveTool(null);
@@ -1831,7 +2001,7 @@ var VdFlowchart = class {
         node.x = nextX;
         node.y = nextY;
         this.interaction.moved = true;
-        this.render({ inspector: false, json: false });
+        this.renderDraggedNode(node);
       }
       return;
     }
@@ -2206,11 +2376,13 @@ var VdFlowchart = class {
       if (event.key === "Escape") {
         event.preventDefault();
         this.stopTextEdit({ commit: false });
+        this.canvasEl.focus();
         return;
       }
       if (event.key === "Enter" && (event.ctrlKey || event.metaKey)) {
         event.preventDefault();
         this.stopTextEdit({ commit: true });
+        this.canvasEl.focus();
       }
     });
     textarea.addEventListener("blur", () => {
@@ -2284,6 +2456,7 @@ var VdFlowchart = class {
     if (shouldRenderScene) this.renderScene();
     if (shouldRenderInspector) this.renderSelectionPanel();
     if (shouldRenderJson) this.syncJsonTextarea();
+    if (shouldRenderInspector) this.renderGraphOutline();
     this.updateToolbarLabel();
     this.updatePaletteState();
     this.positionTextEditor();
@@ -2299,15 +2472,28 @@ var VdFlowchart = class {
     clearChildren(this.nodesLayer);
     clearChildren(this.overlayLayer);
     const nodeMap = new Map(this.documentData.nodes.map((node) => [node.id, node]));
+    this.sceneNodeMap = nodeMap;
+    this.nodeElements = /* @__PURE__ */ new Map();
+    this.edgeElements = /* @__PURE__ */ new Map();
+    this.incidentEdges = /* @__PURE__ */ new Map();
     this.documentData.edges.forEach((edge) => {
       const edgeElement = this.renderEdge(edge, nodeMap);
-      if (edgeElement) this.edgesLayer.appendChild(edgeElement);
+      if (edgeElement) {
+        this.edgesLayer.appendChild(edgeElement);
+        this.edgeElements.set(edge.id, edgeElement);
+        for (const id of /* @__PURE__ */ new Set([edge.from.nodeId, edge.to.nodeId])) {
+          if (!this.incidentEdges.has(id)) this.incidentEdges.set(id, []);
+          this.incidentEdges.get(id).push(edge);
+        }
+      }
     });
     if (this.interaction?.kind === "connect" || this.interaction?.kind === "reconnect") {
       this.previewLayer.appendChild(this.renderPreviewEdge(this.interaction));
     }
     this.documentData.nodes.forEach((node) => {
-      this.nodesLayer.appendChild(this.renderNode(node));
+      const element = this.renderNode(node);
+      this.nodesLayer.appendChild(element);
+      this.nodeElements.set(node.id, element);
     });
     if (this.reconnectEdgeId && !this.readonly) {
       const reconnectEdge = this.findEdge(this.reconnectEdgeId);
@@ -2323,6 +2509,25 @@ var VdFlowchart = class {
     }
     this.syncConnectingState();
   }
+  // Drag frames change one translation and its connected paths. Keep unrelated
+  // SVG elements intact; the release event still refreshes inspector/history.
+  renderDraggedNode(node) {
+    const element = this.nodeElements?.get(node.id);
+    if (!element) {
+      this.render({ inspector: false, json: false });
+      return;
+    }
+    element.setAttribute("transform", `translate(${formatNumber(node.x)} ${formatNumber(node.y)})`);
+    element.classList.add("is-dragging");
+    for (const edge of this.incidentEdges.get(node.id) || []) {
+      const previous = this.edgeElements.get(edge.id);
+      const next = this.renderEdge(edge, this.sceneNodeMap);
+      if (previous && next) {
+        previous.replaceWith(next);
+        this.edgeElements.set(edge.id, next);
+      }
+    }
+  }
   applyEdgeMarkers(pathElement, edge) {
     if (edge.startMarker && edge.startMarker !== "none") {
       pathElement.setAttribute(
@@ -3337,20 +3542,69 @@ var VdFlowchart = class {
     this.emitChange("clear");
     return this;
   }
+  updateOptions(options = {}) {
+    if (this.destroyed) return this;
+    if ("readonly" in options) {
+      if (options.readonly && !this.readonly) {
+        this.stopTextEdit({ commit: true });
+        this.interaction = null;
+        this.activeTool = null;
+        this.reconnectEdgeId = null;
+      }
+      this.readonly = Boolean(options.readonly);
+      this.root.classList.toggle("vd-flowchart-readonly", this.readonly);
+      this.arrangeSelect.disabled = this.readonly;
+      this.clearButton.disabled = this.readonly;
+      this.loadJsonButton.disabled = this.readonly;
+    }
+    if ("gridSize" in options) {
+      this.gridSize = clamp(toFiniteNumber(options.gridSize, DEFAULT_GRID_SIZE), 12, 64);
+      const pattern = this.svg.querySelector("pattern");
+      pattern.setAttribute("width", this.gridSize);
+      pattern.setAttribute("height", this.gridSize);
+      pattern.querySelector("path").setAttribute("d", `M ${this.gridSize} 0 L 0 0 0 ${this.gridSize}`);
+    }
+    if ("autoFit" in options) this.autoFit = Boolean(options.autoFit);
+    if ("history" in options && options.history !== false !== this.historyEnabled) {
+      this.historyEnabled = options.history !== false;
+      this.history = [];
+      this.historyIndex = -1;
+      this.seedHistory();
+    }
+    if ("historyLimit" in options) {
+      this.historyLimit = Math.max(1, Math.floor(toFiniteNumber(options.historyLimit, 100)));
+      if (this.history.length > this.historyLimit) {
+        const start = Math.max(0, this.historyIndex - this.historyLimit + 1);
+        this.history = this.history.slice(start, start + this.historyLimit);
+        this.historyIndex -= start;
+      }
+    }
+    this.render();
+    this.updateHistoryButtons();
+    return this;
+  }
   load(data, options = {}) {
+    const documentData = normalizeDocument(data);
+    if (options.silent && JSON.stringify(documentData) === JSON.stringify(this.documentData)) {
+      return this;
+    }
     this.stopTextEdit({ commit: false });
     this.activeTool = null;
     this.reconnectEdgeId = null;
     const previousSelection = this.selection;
-    this.documentData = normalizeDocument(data);
+    this.documentData = documentData;
     this.selection = this.resolvePreservedSelection(previousSelection, options.preserveSelection);
     this.render();
-    this.emitChange("load");
+    if (options.silent) {
+      if (this.historyEnabled) this.recordHistory("load");
+    } else {
+      this.emitChange("load");
+    }
     return this;
   }
   toJSON() {
     return deepClone({
-      version: VD_FLOWCHART_VERSION,
+      version: FLOWCHART_DOCUMENT_VERSION,
       viewport: this.documentData.viewport,
       nodes: this.documentData.nodes,
       edges: this.documentData.edges
@@ -3364,6 +3618,10 @@ var VdFlowchart = class {
     this.resizeObserver?.disconnect();
     this.resizeObserver = null;
     this.unbindEvents();
+    this.sceneNodeMap?.clear();
+    this.nodeElements?.clear();
+    this.edgeElements?.clear();
+    this.incidentEdges?.clear();
     this.element.innerHTML = "";
     this.element.classList.remove("vd-flowchart-host");
   }
@@ -3415,7 +3673,7 @@ var VdFlowchart2 = defineComponent({
       () => props.data,
       (next) => {
         if (instance && typeof instance.load === "function") {
-          instance.load(next, { preserveSelection: props.preserveSelection });
+          instance.load(next, { preserveSelection: props.preserveSelection, silent: true });
         }
       },
       { deep: true }
@@ -3424,8 +3682,13 @@ var VdFlowchart2 = defineComponent({
       () => [props.readonly, props.gridSize, props.autoFit, props.history, props.historyLimit],
       () => {
         if (!instance) return;
-        instance.destroy();
-        create();
+        instance.updateOptions({
+          readonly: props.readonly,
+          gridSize: props.gridSize,
+          autoFit: props.autoFit,
+          history: props.history,
+          historyLimit: props.historyLimit
+        });
       }
     );
     onBeforeUnmount(() => {
@@ -3446,6 +3709,7 @@ var VdFlowchart2 = defineComponent({
   }
 });
 export {
+  FLOWCHART_DOCUMENT_VERSION,
   FLOWCHART_EDGE_MARKERS,
   FLOWCHART_EDGE_ROUTES,
   FLOWCHART_NODE_TYPES,