html-overlay-node 0.1.0

package/src/core/Graph.js

@@ -0,0 +1,267 @@
+import { Node } from "./Node.js";
+import { Edge } from "./Edge.js";
+import { GroupManager } from "../groups/GroupManager.js";
+
+/**
+ * Graph manages the collection of nodes and edges
+ */
+export class Graph {
+  /**
+   * Create a new Graph
+   * @param {Object} options - Graph configuration
+   * @param {Object} options.hooks - Event hooks system
+   * @param {Object} options.registry - Node type registry
+   */
+  constructor({ hooks, registry }) {
+    if (!registry) {
+      throw new Error("Graph requires a registry");
+    }
+    this.nodes = new Map();
+    this.edges = new Map();
+    this.hooks = hooks;
+    this.registry = registry;
+    // double buffer for deterministic cycles
+    this._valuesA = new Map(); // current
+    this._valuesB = new Map(); // next
+    this._useAasCurrent = true;
+
+    this.groupManager = new GroupManager({
+      graph: this,
+      hooks: this.hooks,
+    });
+  }
+  /**
+   * Get a node by its ID
+   * @param {string} id - Node ID
+   * @returns {Node|null} The node or null if not found
+   */
+  getNodeById(id) {
+    return this.nodes.get(id) || null;
+  }
+  /**
+   * Add a node to the graph
+   * @param {string} type - Node type identifier
+   * @param {Object} [opts={}] - Additional node options (x, y, width, height, etc.)
+   * @returns {Node} The created node
+   * @throws {Error} If node type is not registered
+   */
+  addNode(type, opts = {}) {
+    const def = this.registry.types.get(type);
+    if (!def) {
+      const available = Array.from(this.registry.types.keys()).join(", ") || "none";
+      throw new Error(`Unknown node type: "${type}". Available types: ${available}`);
+    }
+    const node = new Node({
+      type,
+      title: def.title,
+      width: def.size?.w,
+      height: def.size?.h,
+      ...opts,
+    });
+    for (const i of def.inputs || []) node.addInput(i.name, i.datatype, i.portType || "data");
+    for (const o of def.outputs || []) node.addOutput(o.name, o.datatype, o.portType || "data");
+    def.onCreate?.(node);
+    this.nodes.set(node.id, node);
+    this.hooks?.emit("node:create", node);
+    return node;
+  }
+  /**
+   * Remove a node and its connected edges from the graph
+   * @param {string} nodeId - ID of the node to remove
+   */
+  removeNode(nodeId) {
+    // Remove all edges connected to this node
+    for (const [eid, e] of this.edges) {
+      if (e.fromNode === nodeId || e.toNode === nodeId) {
+        this.edges.delete(eid);
+      }
+    }
+    this.nodes.delete(nodeId);
+  }
+  /**
+   * Add an edge connecting two node ports
+   * @param {string} fromNode - Source node ID
+   * @param {string} fromPort - Source port ID
+   * @param {string} toNode - Target node ID
+   * @param {string} toPort - Target port ID
+   * @returns {Edge} The created edge
+   * @throws {Error} If nodes don't exist
+   */
+  addEdge(fromNode, fromPort, toNode, toPort) {
+    // Validate nodes exist
+    if (!this.nodes.has(fromNode)) {
+      throw new Error(`Cannot create edge: source node "${fromNode}" not found`);
+    }
+    if (!this.nodes.has(toNode)) {
+      throw new Error(`Cannot create edge: target node "${toNode}" not found`);
+    }
+
+    const e = new Edge({ fromNode, fromPort, toNode, toPort });
+    this.edges.set(e.id, e);
+    this.hooks?.emit("edge:create", e);
+    return e;
+  }
+
+  /**
+   * Clear all nodes and edges from the graph
+   */
+  clear() {
+    this.nodes.clear();
+    this.edges.clear();
+  }
+
+  updateWorldTransforms() {
+    // 1. Find roots
+    const roots = [];
+    for (const n of this.nodes.values()) {
+      if (!n.parent) roots.push(n);
+    }
+
+    // 2. Traverse
+    const stack = roots.map((n) => ({ node: n, px: 0, py: 0 }));
+    while (stack.length > 0) {
+      const { node, px, py } = stack.pop();
+      node.computed.x = px + node.pos.x;
+      node.computed.y = py + node.pos.y;
+      node.computed.w = node.size.width;
+      node.computed.h = node.size.height;
+
+      for (const child of node.children) {
+        stack.push({ node: child, px: node.computed.x, py: node.computed.y });
+      }
+    }
+  }
+
+  reparent(node, newParent) {
+    if (node.parent === newParent) return;
+
+    // 1. Calculate current world pos
+    const wx = node.computed.x;
+    const wy = node.computed.y;
+
+    // 2. Remove from old parent
+    if (node.parent) {
+      node.parent.children.delete(node);
+    }
+
+    // 3. Add to new parent
+    node.parent = newParent;
+    if (newParent) {
+      newParent.children.add(node);
+      // 4. Calculate new local pos
+      // world = parentWorld + local => local = world - parentWorld
+      node.pos.x = wx - newParent.computed.x;
+      node.pos.y = wy - newParent.computed.y;
+    } else {
+      // Root
+      node.pos.x = wx;
+      node.pos.y = wy;
+    }
+
+    this.updateWorldTransforms();
+  }
+
+  // buffer helpers
+  _curBuf() {
+    return this._useAasCurrent ? this._valuesA : this._valuesB;
+  }
+  _nextBuf() {
+    return this._useAasCurrent ? this._valuesB : this._valuesA;
+  }
+  swapBuffers() {
+    // when moving to next cycle, promote next->current and clear next
+    this._useAasCurrent = !this._useAasCurrent;
+    this._nextBuf().clear();
+  }
+  // data helpers
+  setOutput(nodeId, portId, value) {
+    console.log(`[Graph.setOutput] nodeId: ${nodeId}, portId: ${portId}, value:`, value);
+    const key = `${nodeId}:${portId}`;
+    this._nextBuf().set(key, value);
+  }
+  getInput(nodeId, portId) {
+    // Find incoming edge to this port
+    for (const edge of this.edges.values()) {
+      if (edge.toNode === nodeId && edge.toPort === portId) {
+        const key = `${edge.fromNode}:${edge.fromPort}`;
+        const value = this._curBuf().get(key);
+        console.log(`[Graph.getInput] nodeId: ${nodeId}, portId: ${portId}, reading from ${edge.fromNode}:${edge.fromPort}, value:`, value);
+        return value;
+      }
+    }
+    console.log(`[Graph.getInput] nodeId: ${nodeId}, portId: ${portId}, no edge found, returning undefined`);
+    return undefined;
+  }
+  toJSON() {
+    const json = {
+      nodes: [...this.nodes.values()].map((n) => ({
+        id: n.id,
+        type: n.type,
+        title: n.title,
+        x: n.pos.x,
+        y: n.pos.y,
+        w: n.size.width,
+        h: n.size.height,
+        inputs: n.inputs,
+        outputs: n.outputs,
+        state: n.state,
+        parentId: n.parent?.id || null, // Save parent relationship
+      })),
+      edges: [...this.edges.values()],
+    };
+    this.hooks?.emit("graph:serialize", json);
+    return json;
+  }
+  fromJSON(json) {
+    this.clear();
+
+    // Restore nodes first
+    for (const nd of json.nodes) {
+      const node = new Node({
+        id: nd.id,
+        type: nd.type,
+        title: nd.title,
+        x: nd.x,
+        y: nd.y,
+        width: nd.w,
+        height: nd.h,
+      });
+      // Call onCreate to initialize node with defaults first
+      const def = this.registry?.types?.get(nd.type);
+      if (def?.onCreate) {
+        def.onCreate(node);
+      }
+
+      node.inputs = nd.inputs;
+      node.outputs = nd.outputs;
+      // Merge loaded state over defaults
+      node.state = { ...node.state, ...(nd.state || {}) };
+
+      this.nodes.set(node.id, node);
+    }
+
+    // Restore parent-child relationships
+    for (const nd of json.nodes) {
+      if (nd.parentId) {
+        const node = this.nodes.get(nd.id);
+        const parent = this.nodes.get(nd.parentId);
+        if (node && parent) {
+          node.parent = parent;
+          parent.children.add(node);
+        }
+      }
+    }
+
+    // Restore edges
+    for (const ed of json.edges) {
+      this.edges.set(ed.id, new Edge(ed));
+    }
+
+    // Update world transforms to calculate proper positions
+    this.updateWorldTransforms();
+
+    this.hooks?.emit("graph:deserialize", json);
+
+    return this;
+  }
+}

package/src/core/Graph.test.js

@@ -0,0 +1,256 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { Graph } from "./Graph.js";
+import { Registry } from "./Registry.js";
+import { createHooks } from "./Hooks.js";
+
+describe("Graph", () => {
+  let graph;
+  let registry;
+  let hooks;
+
+  beforeEach(() => {
+    registry = new Registry();
+    hooks = createHooks(["node:create", "edge:create"]);
+    graph = new Graph({ hooks, registry });
+
+    // Register a test node type
+    registry.register("test/node", {
+      title: "Test Node",
+      size: { w: 100, h: 50 },
+      inputs: [{ name: "in", datatype: "any" }],
+      outputs: [{ name: "out", datatype: "any" }],
+    });
+  });
+
+  describe("constructor", () => {
+    it("should create a graph with empty nodes and edges", () => {
+      expect(graph.nodes).toBeInstanceOf(Map);
+      expect(graph.edges).toBeInstanceOf(Map);
+      expect(graph.nodes.size).toBe(0);
+      expect(graph.edges.size).toBe(0);
+    });
+
+    it("should throw error when registry is missing", () => {
+      expect(() => {
+        new Graph({ hooks });
+      }).toThrow(/requires a registry/);
+    });
+
+    it("should initialize GroupManager", () => {
+      expect(graph.groupManager).toBeDefined();
+    });
+  });
+
+  describe("addNode", () => {
+    it("should add a node to the graph", () => {
+      const node = graph.addNode("test/node", { x: 100, y: 200 });
+      expect(node).toBeDefined();
+      expect(node.type).toBe("test/node");
+      expect(node.title).toBe("Test Node");
+      expect(node.pos.x).toBe(100);
+      expect(node.pos.y).toBe(200);
+      expect(graph.nodes.has(node.id)).toBe(true);
+    });
+
+    it("should add inputs and outputs from definition", () => {
+      const node = graph.addNode("test/node");
+      expect(node.inputs.length).toBe(1);
+      expect(node.inputs[0].name).toBe("in");
+      expect(node.outputs.length).toBe(1);
+      expect(node.outputs[0].name).toBe("out");
+    });
+
+    it("should throw error for unknown node type with available types", () => {
+      expect(() => {
+        graph.addNode("unknown/type");
+      }).toThrow(/Available types: test\/node/);
+    });
+
+    it("should emit node:create event", () => {
+      let emittedNode = null;
+      hooks.on("node:create", (node) => {
+        emittedNode = node;
+      });
+
+      const node = graph.addNode("test/node");
+      expect(emittedNode).toBe(node);
+    });
+
+    it("should call onCreate callback if defined", () => {
+      let onCreateCalled = false;
+      registry.register("test/with-oncreate", {
+        title: "Test",
+        onCreate: (node) => {
+          onCreateCalled = true;
+          node.state.initialized = true;
+        },
+      });
+
+      const node = graph.addNode("test/with-oncreate");
+      expect(onCreateCalled).toBe(true);
+      expect(node.state.initialized).toBe(true);
+    });
+  });
+
+  describe("getNodeById", () => {
+    it("should return node by ID", () => {
+      const node = graph.addNode("test/node");
+      const found = graph.getNodeById(node.id);
+      expect(found).toBe(node);
+    });
+
+    it("should return null for non-existent ID", () => {
+      const found = graph.getNodeById("non-existent");
+      expect(found).toBe(null);
+    });
+  });
+
+  describe("removeNode", () => {
+    it("should remove a node from the graph", () => {
+      const node = graph.addNode("test/node");
+      graph.removeNode(node.id);
+      expect(graph.nodes.has(node.id)).toBe(false);
+    });
+
+    it("should remove edges connected to the node", () => {
+      const node1 = graph.addNode("test/node");
+      const node2 = graph.addNode("test/node");
+
+      const edge = graph.addEdge(
+        node1.id,
+        node1.outputs[0].id,
+        node2.id,
+        node2.inputs[0].id
+      );
+
+      graph.removeNode(node1.id);
+      expect(graph.edges.has(edge.id)).toBe(false);
+    });
+  });
+
+  describe("addEdge", () => {
+    it("should add an edge between two nodes", () => {
+      const node1 = graph.addNode("test/node");
+      const node2 = graph.addNode("test/node");
+
+      const edge = graph.addEdge(
+        node1.id,
+        node1.outputs[0].id,
+        node2.id,
+        node2.inputs[0].id
+      );
+
+      expect(edge).toBeDefined();
+      expect(edge.fromNode).toBe(node1.id);
+      expect(edge.toNode).toBe(node2.id);
+      expect(graph.edges.has(edge.id)).toBe(true);
+    });
+
+    it("should throw error when source node doesn't exist", () => {
+      const node = graph.addNode("test/node");
+      expect(() => {
+        graph.addEdge("non-existent", "port", node.id, "port");
+      }).toThrow(/source node "non-existent" not found/);
+    });
+
+    it("should throw error when target node doesn't exist", () => {
+      const node = graph.addNode("test/node");
+      expect(() => {
+        graph.addEdge(node.id, "port", "non-existent", "port");
+      }).toThrow(/target node "non-existent" not found/);
+    });
+
+    it("should emit edge:create event", () => {
+      let emittedEdge = null;
+      hooks.on("edge:create", (edge) => {
+        emittedEdge = edge;
+      });
+
+      const node1 = graph.addNode("test/node");
+      const node2 = graph.addNode("test/node");
+      const edge = graph.addEdge(
+        node1.id,
+        node1.outputs[0].id,
+        node2.id,
+        node2.inputs[0].id
+      );
+
+      expect(emittedEdge).toBe(edge);
+    });
+  });
+
+  describe("clear", () => {
+    it("should remove all nodes and edges", () => {
+      const node1 = graph.addNode("test/node");
+      const node2 = graph.addNode("test/node");
+      graph.addEdge(node1.id, node1.outputs[0].id, node2.id, node2.inputs[0].id);
+
+      expect(graph.nodes.size).toBe(2);
+      expect(graph.edges.size).toBe(1);
+
+      graph.clear();
+
+      expect(graph.nodes.size).toBe(0);
+      expect(graph.edges.size).toBe(0);
+    });
+  });
+
+  describe("data flow", () => {
+    it("should set and get output values", () => {
+      const node = graph.addNode("test/node");
+      graph.setOutput(node.id, node.outputs[0].id, "test-value");
+
+      graph.swapBuffers();
+
+      const value = graph.getInput(node.id, "any-port");
+      expect(value).toBeUndefined(); // No edge connected
+    });
+
+    it("should retrieve input value from connected edge", () => {
+      const node1 = graph.addNode("test/node");
+      const node2 = graph.addNode("test/node");
+      graph.addEdge(node1.id, node1.outputs[0].id, node2.id, node2.inputs[0].id);
+
+      graph.setOutput(node1.id, node1.outputs[0].id, "test-value");
+      graph.swapBuffers();
+
+      const value = graph.getInput(node2.id, node2.inputs[0].id);
+      expect(value).toBe("test-value");
+    });
+  });
+
+  describe("serialization", () => {
+    it("should serialize graph to JSON", () => {
+      const node = graph.addNode("test/node", { x: 100, y: 200 });
+      const json = graph.toJSON();
+
+      expect(json.nodes).toBeInstanceOf(Array);
+      expect(json.nodes.length).toBe(1);
+      expect(json.nodes[0].type).toBe("test/node");
+      expect(json.nodes[0].x).toBe(100);
+      expect(json.nodes[0].y).toBe(200);
+      expect(json.edges).toBeInstanceOf(Array);
+    });
+
+    it("should deserialize graph from JSON", () => {
+      const node1 = graph.addNode("test/node", { x: 100, y: 200 });
+      const node2 = graph.addNode("test/node", { x: 300, y: 400 });
+      const edge = graph.addEdge(
+        node1.id,
+        node1.outputs[0].id,
+        node2.id,
+        node2.inputs[0].id
+      );
+
+      const json = graph.toJSON();
+      graph.clear();
+
+      graph.fromJSON(json);
+
+      expect(graph.nodes.size).toBe(2);
+      expect(graph.edges.size).toBe(1);
+      expect(graph.getNodeById(node1.id)).toBeDefined();
+      expect(graph.getNodeById(node2.id)).toBeDefined();
+    });
+  });
+});

package/src/core/Group.js

@@ -0,0 +1,77 @@
+import { randomUUID } from "../utils/utils";
+
+export class Group {
+  constructor({
+    id,
+    title = "",
+    x = 0,
+    y = 0,
+    width = 120,
+    height = 80,
+    color = "#888",
+    state = {},
+  } = {}) {
+    // ← 인수 미전달 방지
+    this.id = id ?? randomUUID();
+    this.title = title;
+    this.pos = { x, y };
+    this.size = { width, height };
+    this.color = color;
+    this.state = state;
+  }
+
+  // status
+  getStatus() {
+    return this.state;
+  }
+  setStatus(state = {}) {
+    this.state = state;
+  }
+
+  // position
+  getPosition() {
+    return this.pos;
+  }
+  setPosition(a, b) {
+    // 객체/튜플/숫자 2개 모두 허용하면서 '교체'가 아니라 '변경'만
+    if (typeof a === "object" && a !== null) {
+      const { x, y } = a;
+      if (Number.isFinite(x)) this.pos.x = x;
+      if (Number.isFinite(y)) this.pos.y = y;
+    } else {
+      if (Number.isFinite(a)) this.pos.x = a;
+      if (Number.isFinite(b)) this.pos.y = b;
+    }
+  }
+
+  // size
+  getSize() {
+    return this.size;
+  }
+  setSize(a, b) {
+    if (typeof a === "object" && a !== null) {
+      const { width, height } = a;
+      if (Number.isFinite(width)) this.size.width = width;
+      if (Number.isFinite(height)) this.size.height = height;
+    } else {
+      if (Number.isFinite(a)) this.size.width = a;
+      if (Number.isFinite(b)) this.size.height = b;
+    }
+  }
+
+  // color
+  getColor() {
+    return this.color;
+  }
+  setColor(color) {
+    this.color = color;
+  }
+
+  // title
+  getTitle() {
+    return this.title;
+  }
+  setTitle(title) {
+    this.title = title;
+  }
+}

package/src/core/Hooks.js

@@ -0,0 +1,12 @@
+export function createHooks(names) {
+  const map = Object.fromEntries(names.map((n) => [n, new Set()]));
+  return {
+    on(name, fn) {
+      map[name].add(fn);
+      return () => map[name].delete(fn);
+    },
+    async emit(name, ...args) {
+      for (const fn of map[name]) await fn(...args);
+    },
+  };
+}