html-overlay-node 0.1.9 → 0.1.11

package/readme.md

@@ -1,440 +1,143 @@
-# HTML-overlay-Node
-
-[![npm version](https://img.shields.io/npm/v/html-overlay-node.svg)](https://www.npmjs.com/package/html-overlay-node)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-
-**HTML-overlay-Node** is a customizable, LiteGraph-style node editor library for building visual programming interfaces. It uses **Canvas rendering** for fast performance and supports node type registration, execution cycle control, custom drawing, HTML overlays, and group management.
-
----
-
-## ✨ Features
-
-- 🎨 **Production-quality design** - Professional dark theme with refined aesthetics
-- 🔧 **Type registration system** - Easily create custom node types
-- 🔌 **Dual port system** - Exec ports (flow control) and data ports (values)
-- ⚡ **Flexible execution** - Automatic or manual execution modes with trigger nodes
-- 🔗 **Multiple edge styles** - Curved, orthogonal, or straight connections
-- 💾 **Serialization** - Save and load graphs with `toJSON`/`fromJSON`
-- 🖱️ **Rich interactions** - Zoom, pan, drag, box select, and snap-to-grid
-- ⌨️ **Keyboard shortcuts** - Undo/redo, align, group, and more
-- 🎯 **Custom drawing** - Per-node custom rendering with `onDraw`
-- 🌐 **HTML overlays** - Embed interactive HTML UIs with proper port layering
-- 📦 **Group nodes** - Organize nodes in hierarchical groups
-- 🪝 **Event hooks** - Subscribe to graph events for extensibility
-- 🎥 **Visual feedback** - Smooth animations and hover states
-
----
-
-## Demo
-
-- 🏠 [Demo](https://cheonghakim.github.io/HTML-overlay-node/)
-
-## 🚀 Quick Start
-
-```javascript
-import { createGraphEditor } from "html-overlay-node";
-
-// One-liner Initialization!
-// Pass a selector or HTMLElement. Canvas and overlays are created automatically.
-const editor = createGraphEditor("#editor-container", {
-  autorun: true,
-  enablePropertyPanel: true, // Integrated property panel (default: true)
-});
-
-const { graph, registry, addGroup, start } = editor;
-```
-
-### 💅 Styles (Required)
-
-Make sure to import the necessary CSS files for the editor and Property Panel to look correctly:
-
-```javascript
-import "html-overlay-node/index.css";
-import "html-overlay-node/src/ui/PropertyPanel.css";
-```
-
-// Register and add nodes
-registry.register("math/Add", {
-title: "Add",
-size: { w: 180, h: 80 },
-inputs: [
-{ name: "a", datatype: "number" },
-{ name: "b", datatype: "number" },
-],
-outputs: [{ name: "result", datatype: "number" }],
-onCreate(node) {
-node.state.a = 0;
-node.state.b = 0;
-},
-onExecute(node, { getInput, setOutput }) {
-const a = getInput("a") ?? node.state.a;
-const b = getInput("b") ?? node.state.b;
-setOutput("result", a + b);
-},
-});
-
-// Add nodes
-const node1 = graph.addNode("math/Add", { x: 100, y: 100 });
-const node2 = graph.addNode("math/Add", { x: 100, y: 200 });
-
-// Create a group
-addGroup({
-title: "Math Operations",
-x: 50,
-y: 50,
-width: 300,
-height: 300,
-color: "#4a5568",
-members: [node1.id, node2.id],
-});
-
-start();
-
-````
-
----
-
-## 📦 Group Management
-
-HTML-overlay-Node supports organizing nodes into hierarchical groups for better organization.
-
-### Creating Groups
-
-```javascript
-const { addGroup } = editor;
-
-// Create a group
-const group = addGroup({
-  title: "My Group", // Group name
-  x: 0, // X position
-  y: 0, // Y position
-  width: 400, // Width (min: 100)
-  height: 300, // Height (min: 60)
-  color: "#2d3748", // Background color
-  members: [node1.id, node2.id], // Nodes to include
-});
-````
-
-### Group Features
-
-- **Hierarchical Structure**: Groups can contain multiple nodes
-- **Automatic Movement**: Nodes inside the group move with the group
-- **Resizable**: Resize groups using the handle in the bottom-right corner
-- **Custom Colors**: Set group colors for visual organization
-- **Local Coordinates**: World and local coordinates automatically managed
-
-### Advanced Group Operations
-
-```javascript
-// Access GroupManager
-const groupManager = graph.groupManager;
-
-// Reparent a node to a group
-graph.reparent(node, group);
-
-// Remove node from group (reparent to root)
-graph.reparent(node, null);
-
-// Resize a group
-groupManager.resizeGroup(group.id, 50, 50); // add 50px to width and height
-
-// Remove a group (children are un-grouped)
-groupManager.removeGroup(group.id);
-
-// Listen to group events
-hooks.on("group:change", () => {
-  console.log("Group structure changed");
-});
-```
-
----
-
-## 🌐 HTML Overlays
-
-Create interactive HTML UIs inside nodes.
-
-### Basic Example
-
-```javascript
-registry.register("ui/TextInput", {
-  title: "Text Input",
-  size: { w: 220, h: 100 },
-  outputs: [{ name: "text", datatype: "string" }],
-
-  html: {
-    init(node, el, { header, body }) {
-      el.style.backgroundColor = "#1a1a1a";
-      el.style.borderRadius = "8px";
-
-      const input = document.createElement("input");
-      input.type = "text";
-      input.placeholder = "Enter text...";
-      Object.assign(input.style, {
-        width: "100%",
-        padding: "8px",
-        background: "#111",
-        border: "1px solid #444",
-        color: "#fff",
-        pointerEvents: "auto", // IMPORTANT: Enable interaction
-      });
-
-      input.addEventListener("input", (e) => {
-        node.state.text = e.target.value;
-        hooks.emit("node:updated", node);
-      });
-
-      input.addEventListener("mousedown", (e) => e.stopPropagation()); // Prevent drag
-
-      body.appendChild(input);
-      el._input = input;
-    },
-
-    update(node, el, { selected }) {
-      el.style.borderColor = selected ? "#3b82f6" : "#333";
-      if (el._input.value !== (node.state.text || "")) {
-        el._input.value = node.state.text || "";
-      }
-    },
-  },
-
-  onCreate(node) {
-    node.state.text = "";
-  },
-
-  onExecute(node, { setOutput }) {
-    setOutput("text", node.state.text || "");
-  },
-});
-```
-
-### Best Practices
-
-1. **Enable Interaction**: Set `pointerEvents: "auto"` on interactive elements
-2. **Stop Propagation**: Prevent canvas drag with `e.stopPropagation()` on `mousedown`
-3. **Update State**: Emit `"node:updated"` when state changes
-4. **Store References**: Cache DOM elements in `el._refs` for performance
-5. **Port Visibility**: HTML overlays are rendered below ports for proper visibility
-
----
-
-## 🔌 Port Types
-
-HTML-overlay-Node supports two types of ports for different purposes:
-
-### Exec Ports (Flow Control)
-
-Exec ports control the execution flow between nodes.
-
-```javascript
-registry.register("util/Print", {
-  title: "Print",
-  inputs: [
-    { name: "exec", portType: "exec" }, // Execution input
-    { name: "value", portType: "data", datatype: "any" },
-  ],
-  outputs: [
-    { name: "exec", portType: "exec" }, // Execution output
-  ],
-  onExecute(node, { getInput }) {
-    console.log("[Print]", getInput("value"));
-  },
-});
-```
-
-### Data Ports (Values)
-
-Data ports transfer values between nodes.
-
-```javascript
-registry.register("math/Add", {
-  title: "Add",
-  inputs: [
-    { name: "exec", portType: "exec" },
-    { name: "a", portType: "data", datatype: "number" },
-    { name: "b", portType: "data", datatype: "number" },
-  ],
-  outputs: [
-    { name: "exec", portType: "exec" },
-    { name: "result", portType: "data", datatype: "number" },
-  ],
-  onExecute(node, { getInput, setOutput }) {
-    const result = (getInput("a") ?? 0) + (getInput("b") ?? 0);
-    setOutput("result", result);
-  },
-});
-```
-
-### Visual Style
-
-- **Exec ports**: Emerald green rounded squares (8×8px)
-- **Data ports**: Indigo blue circles (10px diameter)
-- Both have subtle outlines for depth
-
----
-
-## ⌨️ Keyboard Shortcuts
-
-| Shortcut                        | Action                      |
-| ------------------------------- | --------------------------- |
-| **Selection**                   |                             |
-| `Click`                         | Select node                 |
-| `Shift + Click`                 | Add to selection            |
-| `Ctrl + Drag`                   | Box select                  |
-| **Editing**                     |                             |
-| `Delete`                        | Delete selected nodes       |
-| `Ctrl + Z`                      | Undo                        |
-| `Ctrl + Y` / `Ctrl + Shift + Z` | Redo                        |
-| **Grouping**                    |                             |
-| `Ctrl + G`                      | Create group from selection |
-| **Alignment**                   |                             |
-| `A`                             | Align nodes horizontally    |
-| `Shift + A`                     | Align nodes vertically      |
-| **Tools**                       |                             |
-| `G`                             | Toggle snap-to-grid         |
-| `?`                             | Toggle shortcuts help       |
-| **Navigation**                  |                             |
-| `Middle Click + Drag`           | Pan canvas                  |
-| `Mouse Wheel`                   | Zoom in/out                 |
-| `Right Click`                   | Context menu                |
-
----
-
-## 📚 Complete API
-
-For full API documentation, see the comments in [src/index.js](src/index.js).
-
-### Editor API
-
-| Property            | Description           |
-| ------------------- | --------------------- |
-| `graph`             | Graph instance        |
-| `registry`          | Node type registry    |
-| `hooks`             | Event system          |
-| `render()`          | Trigger manual render |
-| `start()`           | Start execution loop  |
-| `stop()`            | Stop execution loop   |
-| `addGroup(options)` | Create a group        |
-| `destroy()`         | Cleanup               |
-
-### Key Methods
-
-- `registry.register(type, definition)` - Register node type
-- `graph.addNode(type, options)` - Create node
-- `graph.addEdge(from, fromPort, to, toPort)` - Connect nodes
-- `graph.toJSON()` / `graph.fromJSON(json)` - Serialize/deserialize
-- `hooks.on(event, callback)` - Subscribe to events
-
-### Available Events
-
-- `node:create` | `node:move` | `node:resize` | `node:updated`
-- `edge:create` | `edge:delete`
-- `group:change`
-- `runner:start` | `runner:stop` | `runner:tick`
-- `error`
-
----
-
-## 🎨 Customization
-
-### Theme Colors
-
-```javascript
-const editor = createGraphEditor(canvas, {
-  theme: {
-    bg: "#0d0d0f", // Canvas background
-    grid: "#1a1a1d", // Grid lines
-    node: "#16161a", // Node background
-    nodeBorder: "#2a2a2f", // Node border
-    title: "#1f1f24", // Node header
-    text: "#e4e4e7", // Primary text
-    textMuted: "#a1a1aa", // Secondary text
-    port: "#6366f1", // Data port color (indigo)
-    portExec: "#10b981", // Exec port color (emerald)
-    edge: "#52525b", // Edge color
-    edgeActive: "#8b5cf6", // Active edge (purple)
-    accent: "#6366f1", // Accent color
-    accentBright: "#818cf8", // Bright accent
-  },
-});
-```
-
-### Edge Styles
-
-```javascript
-// Set edge style
-editor.renderer.setEdgeStyle("orthogonal"); // or "curved", "line"
-```
-
-### Custom Node Drawing
-
-```javascript
-registry.register("visual/Circle", {
-  title: "Circle",
-  size: { w: 120, h: 120 },
-  onDraw(node, { ctx, theme }) {
-    const { x, y, width, height } = node.computed;
-    const centerX = x + width / 2;
-    const centerY = y + height / 2;
-    const radius = Math.min(width, height) / 3;
-
-    ctx.beginPath();
-    ctx.arc(centerX, centerY, radius, 0, Math.PI * 2);
-    ctx.fillStyle = theme.wire;
-    ctx.fill();
-  },
-});
-```
-
----
-
-## 💾 Serialization
-
-```javascript
-// Save
-const json = graph.toJSON();
-localStorage.setItem("myGraph", JSON.stringify(json));
-
-// Load
-const saved = JSON.parse(localStorage.getItem("myGraph"));
-graph.fromJSON(saved);
-```
-
----
-
-## 🐛 Troubleshooting
-
-| Issue                        | Solution                                            |
-| ---------------------------- | --------------------------------------------------- |
-| Canvas not rendering         | Ensure canvas has explicit width/height             |
-| Nodes not executing          | Call `start()` or set `autorun: true`               |
-| Type errors                  | Register node types before using them               |
-| HTML overlay not interactive | Set `pointerEvents: "auto"` on elements             |
-| Performance issues           | Limit to <1000 nodes, optimize `onExecute`/`onDraw` |
-
----
-
-## 🤝 Contributing
-
-Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
-
-```bash
-npm install   # Install dependencies
-npm run dev   # Start dev server
-npm test      # Run tests
-npm run lint  # Check code quality
-npm run build # Build library
-```
-
----
-
-## 📄 License
-
-[MIT](LICENSE) © cheonghakim
-
----
-
-## 🔗 Links
-
-- [GitHub Repository](https://github.com/cheonghakim/html-overlay-node)
-- [Issue Tracker](https://github.com/cheonghakim/html-overlay-node/issues)
-- [Changelog](CHANGELOG.md)
+# HTML-overlay-Node
+
+[![npm version](https://img.shields.io/npm/v/html-overlay-node.svg)](https://www.npmjs.com/package/html-overlay-node)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**HTML-overlay-Node**는 Canvas의 고성능 렌더링과 HTML의 유연한 UI 인터페이스를 결합한 전문가용 노드 에디터 엔진입니다. 단순한 시각화를 넘어, 복잡한 로직 설계와 실시간 실행 환경에 최적화된 날카롭고 세련된 엔지니어링 경험을 제공합니다.
+
+---
+
+## ✨ 핵심 기능 (Key Features)
+
+- **하이브리드 렌더링**: 노드 본체와 복잡한 위젯은 HTML로, 연결선(Edge)과 고주파 애니메이션은 Canvas로 처리하여 성능과 커스터마이징의 균형을 잡았습니다.
+- **실시간 실행 흐름 시각화**: 노드 실행 상태와 데이터 흐름을 'Marching Ants' 테두리 및 흐르는 점 애니메이션으로 가시화하여 로직의 흐름을 직관적으로 파악할 수 있습니다.
+- **전문가급 디자인 시스템**: 2px의 정밀한 라운딩, 깊이감 있는 다크 테마, 카테고리별 컬러 코딩으로 대규모 그래프에서도 높은 가독성을 유지합니다.
+- **강력한 듀얼 포트 시스템**: 실행 제어(Execution Flow)와 데이터 전용(Data Flow) 포트를 분리 지원하여 함수형/이벤트 기반 로직 설계를 완벽히 지원합니다.
+- **생산성 도구**: Undo/Redo, 그룹화(Group), 자동 정렬(Aligning), 그리드 스냅, 다중 선택 등 실제 작업 효율을 극대화하는 파워 유저 기능을 내장하고 있습니다.
+
+---
+
+## 🚀 빠른 시작 (Quick Start)
+
+Vite나 Webpack 환경에서 다음과 같이 손쉽게 에디터를 구축할 수 있습니다.
+
+```javascript
+import { createGraphEditor } from "html-overlay-node";
+import "html-overlay-node/index.css";
+
+const editor = createGraphEditor("#editor-container", {
+  theme: {
+    accent: "#6366f1", // 주요 강조 색상 (Indigo)
+    flowSpeed: 150     // 애니메이션 흐름 속도 (px/sec)
+  }
+});
+
+const { graph, registry, start } = editor;
+
+// 노드 등록 및 시작
+registry.register("math/Add", { ... });
+start();
+```
+
+---
+
+## 🧩 플러그인 시스템 (Plugins & Node Registration)
+
+`registry`를 통해 새로운 기능을 동적으로 확장할 수 있습니다.
+
+```javascript
+registry.register("math/Multiply", {
+  title: "Multiply",
+  color: "#f43f5e", // 카테고리 컬러
+  inputs: [
+    { name: "a", portType: "data" },
+    { name: "b", portType: "data" }
+  ],
+  outputs: [{ name: "result", portType: "data" }],
+  // 실행 로직 정의
+  onExecute(node, { getInput, setOutput }) {
+    const a = getInput("a") ?? 1;
+    const b = getInput("b") ?? 1;
+    setOutput("result", a * b);
+  }
+});
+```
+
+---
+
+## 🖼️ UI & 위젯 (HTML Overlays & Widgets)
+
+HTML의 강점을 살려 노드 내부에 복잡한 UI를 직접 구현할 수 있습니다. `renderHtml` 함수를 통해 DOM 요소를 직접 제어하거나 내장 위젯을 사용할 수 있습니다.
+
+```javascript
+registry.register("ui/Slider", {
+  html: true, // HTML 오버레이 활성화
+  renderHtml(node, container) {
+    container.innerHTML = `<input type="range" class="hon-slider" />`;
+    const input = container.querySelector("input");
+    input.oninput = (e) => {
+      node.state.value = e.target.value;
+      // 상태 변경 시 그래프 갱신 알림
+    };
+  }
+});
+```
+
+---
+
+## 🎨 CSS 디자인 토큰 (Design Tokens)
+
+`index.css`에 정의된 CSS 변수를 덮어쓰는 것만으로도 전체 에디터의 룩앤필을 브랜드에 맞게 조정할 수 있습니다.
+
+| 변수명 | 설명 | 기본값 |
+| :--- | :--- | :--- |
+| `--hon-bg` | 캔버스 배경색 | `#0d0d0f` |
+| `--hon-node-bg` | 노드 내부 배경색 | `#16161a` |
+| `--hon-node-border` | 노드 테두리 색상 | `rgba(255,255,255,0.08)` |
+| `--hon-accent` | 강조 포인트 컬러 | `#4f46e5` |
+| `--hon-text` | 기본 텍스트 색상 | `#e2e8f0` |
+| `--hon-grid` | 그리드 점 색상 | `rgba(255,255,255,0.03)` |
+
+---
+
+## ⌨️ 생산성 단축키
+
+| 기능 | 단축키 |
+| :--- | :--- |
+| **노드 삭제** | `Delete` |
+| **수평/수직 정렬** | `A` / `Shift + A` |
+| **그룹 생성** | `Ctrl + G` |
+| **그리드 스냅 토글**| `G` |
+| **실행 취소/재실행** | `Ctrl + Z` / `Ctrl + Y` |
+| **미니맵 토글** | `M` |
+
+---
+
+## 💾 데이터 직렬화 (Serialization)
+
+그래프의 모든 상태는 JSON 형식으로 저장하고 불러올 수 있습니다.
+
+```javascript
+// 현재 캔버스 상태 저장
+const snapshot = graph.toJSON();
+
+// 데이터 복원 (트랜지션 애니메이션 포함)
+graph.fromJSON(snapshot);
+```
+
+---
+
+## 🛠️ 개발 가이드 (Development)
+
+```bash
+npm install   # 의존성 설치
+npm run dev   # 개발 서버 시작
+npm test      # 테스트 실행
+npm run build # 프로덕션 빌드
+```
+
+---
+
+## 📄 라이선스
+
+[MIT](LICENSE) © cheonghakim

package/src/core/Graph.js

@@ -51,11 +51,13 @@ export class Graph {
       const available = Array.from(this.registry.types.keys()).join(", ") || "none";
       throw new Error(`Unknown node type: "${type}". Available types: ${available}`);
     }
+    const height = opts.height || def.size?.h || this._calculateDefaultNodeHeight(def);
+    
     const node = new Node({
       type,
       title: def.title,
-      width: def.size?.w,
-      height: def.size?.h,
+      width: opts.width || def.size?.w || 140,
+      height,
       ...opts,
     });
     for (const i of def.inputs || []) node.addInput(i.name, i.datatype, i.portType || "data");
@@ -212,11 +214,17 @@ export class Graph {
     this.hooks?.emit("graph:serialize", json);
     return json;
   }
+
   fromJSON(json) {
-    this.clear();
+    this.nodes.clear();
+    this.edges.clear();
 
     // Restore nodes first
     for (const nd of json.nodes) {
+      const def = this.registry?.types?.get(nd.type);
+      const minH = def ? this._calculateDefaultNodeHeight(def) : 60;
+      const height = nd.h !== undefined ? nd.h : minH;
+
       const node = new Node({
         id: nd.id,
         type: nd.type,
@@ -224,10 +232,10 @@ export class Graph {
         x: nd.x,
         y: nd.y,
         width: nd.w,
-        height: nd.h,
+        height: height,
       });
+
       // Call onCreate to initialize node with defaults first
-      const def = this.registry?.types?.get(nd.type);
       if (def?.onCreate) {
         def.onCreate(node);
       }
@@ -264,4 +272,25 @@ export class Graph {
 
     return this;
   }
+
+  _calculateDefaultNodeHeight(def) {
+    const inCount = def.inputs?.length || 0;
+    const outCount = def.outputs?.length || 0;
+    const maxPorts = Math.max(inCount, outCount);
+    const headerHeight = 26;
+    const portSpacing = 20;
+
+    if (def.html) {
+      // For HTML overlay nodes: reserve space for content BELOW all port rows.
+      // Port idx N bottom: headerHeight + 8 + N*portSpacing + portSpacing/2 + 6
+      //                  = 50 + N*portSpacing (for N=0: 50, N=1: 70, ...)
+      // Add ~50px for HTML content + bottom padding.
+      const lastPortBottom = maxPorts > 0 ? 50 + (maxPorts - 1) * portSpacing : 26;
+      return Math.max(lastPortBottom + 50, 90);
+    }
+
+    const padding = 8;
+    let h = headerHeight + padding + (maxPorts * portSpacing) + padding;
+    return Math.max(h, 40);
+  }
 }