@kabel-project/kabel 1.0.7

package/(1.0.7)kabel.md

@@ -0,0 +1,18 @@
+**chore(release): Kabel 1.0.6 release**
+- Implemented the Apollo renderer, a renderer that tries to match the "sticky note" style of other blueprint interfaces.
+- Added shadow FX to default renderer.
+- Added background pattern system under wsSvg.grid, options in Kabel.inject for grid added as well.
+- Created new /themes folder, created dark and classic (Default) themes, added theme options to inject.
+- Fixed input boxes (comment, raw field) so that when you click at a specific point, the caret starts there.
+- Decided that where you click within a comment input is where it should start editing at.
+- Added wsSvg.dragState to store information about the current block being dragged.
+- Cleaned up the Flyout class to break up large methods into multiple. This makes extensions easier.
+- Implemented headless inject method along with the WorkspaceSVG's headless counterpart class. (Creating simulated workspaces)
+- Cleaned up renderer which was in preparation for the second default renderer.
+- Added full JSDoc comments to renderer for cleanliness and maintainability.
+- Cleaned up comment renderer for easier subclassing.
+- Removed two useless frame-waits in WorkspaceSVG class.
+
+
+**chore(release): Kabel 1.0.7 release**
+- Very minor documentation update.

package/README.md

@@ -0,0 +1,96 @@
+
+# Kabel
+[![npm version](https://img.shields.io/npm/v/@kabel-project/kabel)](https://www.npmjs.com/package/@kabel-project/kabel)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Node-based visual editor framework with an API inspired by Google’s Blockly project.  
+Fully extensible with custom nodes, fields, and renderers.  
+Written in TypeScript and ready to use out of the box.
+
+![Kabel workspace screenshot](./_READ_ME_MEDIA_/workspace.png)
+
+---
+
+## Installation
+
+You can install Kabel in two main ways:
+
+**Using npm (recommended):**
+```bash
+cd path/to/your/project
+npm install @kabel-project/kabel
+```
+
+**Cloning from GitHub (Experimental builds):**
+
+```bash
+git clone https://github.com/FentFentFent/Kabel.git --depth 1
+cd Kabel
+npm install
+npm run build
+```
+
+Then import Kabel from the build:
+
+```js
+import Kabel from './Kabel/dist/kabel.js';
+```
+
+##### Quick Starter HTML
+
+```html
+<div id="workspace-container" style="width:800px;height:600px;"></div>
+<script type="module">
+  import Kabel from 'kabel';
+  Kabel.inject('workspace-container', {
+    /* Your options here... */
+  });
+</script>
+```
+
+---
+
+## Features
+
+* ⚡ Extensible: create custom nodes, fields, and renderers.
+* 🛠️ TypeScript support out of the box.
+* 🎨 Renderer override system for custom visuals.
+* ⌨️ Built-in workspace controls (WASD movement, drag, etc.).
+
+---
+
+## Example
+
+```js
+import Kabel from 'kabel';
+
+const ws = Kabel.inject('workspace-container', {
+  controls: { wasd: true, wasdSmooth: true }
+});
+
+// Register a simple node
+Kabel.Nodes['example'] = {
+  init() {
+    this.jsonInit({
+      labelText: 'Hello Kabel',
+      type: 'example_node',
+      primaryColor: '#cc0c00'
+    });
+  }
+};
+```
+
+For another example refer to [Kabel Test](./dist/index.html)
+
+
+---
+
+## Documentation
+
+Please refer to [Kabel Guide](./_READ_ME_MEDIA_/documentation/docs.md)
+
+---
+
+## License
+
+MIT

package/_READ_ME_MEDIA_/documentation/docs.md

@@ -0,0 +1,293 @@
+
+# Kabel Documentation
+
+**Kabel** is a node-based visual programming editor for building interactive, logic-driven UIs in the browser. It’s built around JavaScript and uses SVG for rendering. Kabel supports node creation, custom fields, widgets, toolboxes, and smooth workspace controls.
+
+---
+
+## Table of Contents
+
+1. Getting Started
+2. Setting Up Your First Workspace
+3. Creating Your First Node Prototype
+4. Creating a Toolbox
+5. Manipulating Nodes
+6. Serializing & Deserializing Nodes
+7. Finishing Up
+
+## In-depth Docs
+[Kabel API Documentation](../../docs/globals.md)
+
+---
+
+## 1. Getting Started
+
+You can include Kabel either via a script tag or import it as a module:
+
+```html
+<script src="./kabel.js"></script>
+```
+
+Once loaded:
+
+```js
+if (typeof Kabel !== 'undefined') {
+	console.log('Kabel is ready!');
+}
+```
+
+That’s all you need to confirm it’s available before initializing a workspace.
+
+---
+
+## 2. Setting Up Your First Workspace
+
+The **workspace** is where nodes live and interact. Start by creating an HTML container:
+
+```js
+const el = document.createElement('div');
+Object.assign(el.style, {
+	width: '100vw',
+	height: '100vh',
+	background: '#f0f0f0'
+});
+document.body.appendChild(el);
+```
+
+Then inject Kabel into that container:
+
+```js
+const ws = Kabel.inject(el, {
+    theme: 'Dark',
+    renderer: 'atlas', // Or `Apollo`
+	moveSpeed: 6,
+	controls: {
+		wasd: true,
+		wasdSmooth: true,
+		wasdAccelerate: 1,
+		wasdFriction: 0.9
+	},
+	toolbox: { /* defined later */ }
+});
+```
+
+This gives you a fullscreen workspace with smooth WASD movement controls.
+
+---
+
+## 3. Creating Your First Node Prototype
+
+Nodes are defined once as **prototypes** under `Kabel.Nodes`. Here’s an example:
+
+```js
+Kabel.Nodes['my_node'] = {
+	init() {
+		this.jsonInit({
+			previousConnection: true,
+			nextConnection: true,
+			labelText: 'TopbarText',
+			type: 'my_node',
+			primaryColor: '#cc0c00',
+			tertiaryColor: '#660500',
+			arguments: [
+				{ name: 'FLD', type: 'field_str', label: 'LabelText: ', value: 'ValueText' },
+				{ name: 'Dummy', type: 'field_dummy', label: 'Label with no input!' },
+				{ name: 'Conn', type: 'connection', label: 'Label!' },
+				{ name: 'Conn2', type: 'field_both', label: 'lowk: ', value: 'lowk' },
+				{
+					name: 'Dropdown',
+					type: 'dropdown',
+					label: 'lowk dropdown?: ',
+					options: ['Oooo option', { text: 'Opt', value: 'opt' }]
+				}
+			]
+		});
+	}
+};
+```
+
+**Key options:**
+
+* `previousConnection` / `nextConnection` → Whether the node can chain with others.
+* `arguments` → Defines fields, inputs, and connection points.
+* `jsonInit()` → Initializes node configuration.
+
+---
+
+## 4. Creating a Toolbox
+
+Toolboxes organize your available nodes:
+
+```js
+toolbox: {
+	type: 'category',
+	contents: [{
+		name: 'Cat',
+		color: '#cc0c00',
+		contents: [{
+			type: 'my_node',
+			arguments: {
+                //FIELD_NAME: FIELD_VALUE
+            }
+		}]
+	}]
+}
+```
+
+**Toolbox types:**
+
+* `'category'` → Groups nodes visually into collapsible sections.
+* `'flyout'` → Displays all nodes in one scrollable list.
+
+**Category JSON fields:**
+
+* `name`: The category name.
+* `color`: The display color.
+* `contents`: Array of node definitions.
+
+> Currently, categories and flyouts can only contain nodes. Support for buttons or UI elements may be added later.
+
+---
+
+## 5. Manipulating Node Properties
+
+Once a node is created, you can move, modify, or connect it programmatically:
+
+```js
+const node = new Kabel.NodeSvg(Kabel.Nodes['my_node'], ws);
+node.init();
+
+const node2 = new Kabel.NodeSvg(Kabel.Nodes['my_node'], ws);
+node2.init();
+node2.relativeCoords.set(20, 0);
+```
+
+Connect them:
+
+```js
+node.nextConnection.to = node2;
+node2.previousConnection.from = node;
+ws.redraw();
+```
+
+You can also manipulate the SVG directly (temporary, not saved across rerenders):
+
+```js
+node.svg.highlight('#ff0');
+node.svg.setScale(1);
+node.svg.moveTo(0, 1);
+node.svg.applyTransform('translate(0, 1)');
+node.svg.getRaw(); // Returns the svg.js G element
+```
+
+---
+
+### Optional: Widgets
+
+**Widgets** are custom UI overlays within the workspace:
+
+```js
+Kabel.Widgets['testWidget'] = {
+	name: 'Test Widget',
+	width: 150,
+	height: 100,
+	coords: new Kabel.Coordinates(50, 50),
+	html: '<button id="counterBtn">Count: 0</button>',
+	init(widget, container) {
+		let count = 0;
+		const btn = container.querySelector('#counterBtn');
+		if (btn) {
+			btn.addEventListener('click', () => {
+				count++;
+				btn.textContent = 'Count: ' + count;
+			});
+		}
+	}
+};
+
+const myWidget = ws.newWidget('testWidget');
+if (myWidget) myWidget.show();
+```
+
+Widgets let you add custom interactivity or information panels.
+
+---
+
+## 6. Serializing Nodes
+
+Kabel supports both **circular** and **non-circular** JSON serialization.
+
+### Circular Serialization
+
+Contains live object references (not exportable as plain JSON, but usable within JS).
+
+```js
+const circular = node.serialize();
+```
+
+Example (simplified):
+
+```json
+{
+	"id": "sisDG24Gp6lc7*S#m#I9c",
+	"type": "my_node",
+	"nextConnection": {
+		"node": "[CircularNodeRef]"
+	},
+	"fields": [...]
+}
+```
+
+---
+
+### Non-Circular Serialization
+
+Safe for exporting or saving to files:
+
+```js
+const nonCircular = node.toJson();
+```
+
+Example:
+
+```json
+{
+	"7f7#2Rrt16uFuH^2f2^ad": {
+		"id": "7f7#2Rrt16uFuH^2f2^ad",
+		"type": "my_node",
+		"colors": { "primary": "#cc0c00", "tertiary": "#660500" },
+		"label": "TopbarText",
+		"nextConnection": { "node": "jX^$kh)yHW5p^bx98vD#s" },
+		"fields": [...]
+	}
+}
+```
+
+---
+
+### Workspace Serialization
+
+```js
+// Serialize
+const data = workspace.toJson(false); // false = non-circular
+
+// Deserialize
+workspace.fromJson(data);
+```
+
+The serialization format automatically includes the circular/non-circular flag internally.
+
+---
+
+## 7. Finishing Up
+
+You can expose internals for quick debugging:
+
+```js
+window.ws = ws;
+window.nodes = [node, node2];
+```
+
+That’s it — you now have a working Kabel workspace with nodes, a toolbox, and serialization support.
+
+---

package/comment-renderer/renderer.ts

@@ -0,0 +1,228 @@
+import Renderer from '../renderers/renderer';
+import WorkspaceSvg from '../src/workspace-svg';
+import NodeSvg from '../src/nodesvg';
+import CommentModel from '../src/comment';
+import { Element, SVG, Svg } from '@svgdotjs/svg.js';
+import eventer from '../util/eventer';
+
+class CommentRenderer {
+	static get NAME() { return 'cr_atlas'; }
+	static get COMMENT_G_TAG() { return 'KabelCommentGroup'; }
+	static get COMMENT_LINE_TAG() { return 'KabelCommentLine'; }
+	static get COMMENT_TEXT_EL() { return 'KabelCommentText'; }
+	static get COMMENT_DRAG_EL() { return 'KabelCommentDragHandle'; }
+	static get RENDERER_TAG_EL() { return 'KabelCommentElTag'; }
+
+	workspace: WorkspaceSvg;
+
+	constructor(workspace: WorkspaceSvg) {
+		this.workspace = workspace;
+	}
+
+	encodeForSvg(s: string) {
+		return s.replace(/ /g, "\u00A0");
+	}
+
+	ensureTspansPreserve(node: HTMLElement) {
+		Array.from(node.childNodes).forEach((child) => {
+			if (child.nodeType === 1) {
+				(child as HTMLElement).setAttribute("xml:space", "preserve");
+			}
+		});
+	}
+
+	measureTextBbox(textEl: Element) {
+		return textEl.bbox();
+	}
+
+	drawComment(comment: CommentModel) {
+		const svg = this.getSvg();
+		this._removeExistingElements(comment);
+
+		const g = svg.group().addClass(CommentRenderer.COMMENT_G_TAG);
+		g.attr({
+			'comment-data': JSON.stringify({
+				id: comment.id,
+				isws: comment.isWorkspaceComment()
+			})
+		});
+		comment.svgGroup = g;
+
+		const padding = 4;
+		const handleRadius = 6;
+		const textOffsetX = padding + handleRadius * 2 + 4;
+
+		const displayEncoded = this.encodeForSvg(comment.getText());
+		const textEl = this._createTextElement(g, displayEncoded, textOffsetX, padding);
+
+		const bbox = this.measureTextBbox(textEl);
+
+		const rect = this._createBackgroundRect(g, bbox, padding, handleRadius);
+		const dragHandle = this._createDragHandle(g, bbox, padding, handleRadius);
+
+		this._addEventer(rect, dragHandle, comment, textEl);
+
+		const { screenPos, zoom } = this._computeScreenPosition(comment);
+		g.attr({ transform: `translate(${screenPos.x}, ${screenPos.y}) scale(${zoom})` });
+
+		if (comment._parent instanceof NodeSvg && comment._parent.svgGroup) {
+			this._drawLineToNode(comment, padding);
+		}
+	}
+
+	refreshCommentTransforms() {
+		for (const comment of [
+			...this.workspace.getComments(),
+			...Array.from(this.workspace._nodeDB.values())
+				.map(n => n.getComment())
+				.filter(c => !!c) as CommentModel[]
+		]) {
+			if (!comment.svgGroup) continue;
+
+			const { screenPos, zoom } = this._computeScreenPosition(comment);
+			comment.svgGroup.attr({ transform: `translate(${screenPos.x}, ${screenPos.y}) scale(${zoom})` });
+
+			if (comment.svgLine) {
+				comment.svgLine.remove();
+				comment.svgLine = undefined;
+			}
+
+			if (comment._parent instanceof NodeSvg) {
+				this._drawLineToNode(comment, 4);
+			}
+		}
+	}
+
+	private _removeExistingElements(comment: CommentModel) {
+		if (comment.svgGroup) comment.svgGroup.remove();
+		if (comment.svgLine) comment.svgLine.remove();
+	}
+
+	private _createTextElement(parent: Element, text: string, x: number, y: number) {
+        //@ts-ignore
+		const textEl = parent.text(text)
+			.font({ family: 'Arial', size: 12 })
+			.fill('#000')
+			.move(x, y)
+			.addClass(CommentRenderer.COMMENT_TEXT_EL);
+
+		textEl.node.style.userSelect = 'none';
+		// @ts-ignore
+		textEl.node.style!.webkitUserSelect = 'none';
+		// @ts-ignore
+		textEl.node.style!.msUserSelect = 'none';
+		// @ts-ignore
+		textEl.node.style!.MozUserSelect = 'none';
+		return textEl;
+	}
+
+	private _createBackgroundRect(parent: Element, bbox: any, padding: number, handleRadius: number) {
+        //@ts-ignore
+		return parent.rect(bbox.width + padding * 2 + handleRadius * 2 + 4, bbox.height + padding * 2)
+			.fill('#ffffcc')
+			.stroke({ color: '#cccc99', width: 1 })
+			.radius(4)
+			.back();
+	}
+
+	private _createDragHandle(parent: Element, bbox: any, padding: number, handleRadius: number) {
+        //@ts-ignore
+		return parent.circle(handleRadius * 2)
+			.fill('#adad7d')
+			.move(padding, padding + (bbox.height / 2) - handleRadius)
+			.addClass(CommentRenderer.COMMENT_DRAG_EL);
+	}
+
+	private _addEventer(rect: Element, dragHandle: Element, comment: CommentModel, textEl: Element) {
+		eventer.addElement(dragHandle, 'k_draghandle', { comment })
+			.tagElement(dragHandle, CommentRenderer.RENDERER_TAG_EL);
+		eventer.addElement(rect, "k_commentinp", { comment, text: textEl, renderer: this })
+			.tagElement(rect, CommentRenderer.RENDERER_TAG_EL);
+	}
+
+	private _computeScreenPosition(comment: CommentModel) {
+		let workspaceX = comment.relativeCoords.x;
+		let workspaceY = comment.relativeCoords.y;
+
+		if (comment._parent instanceof NodeSvg) {
+			const nodePos = comment._parent.relativeCoords;
+			workspaceX += nodePos.x;
+			workspaceY += nodePos.y;
+		}
+
+		const screenPos = this.workspace.workspaceToScreen(workspaceX, workspaceY);
+		const zoom = this.workspace.getZoom();
+		return { screenPos, zoom };
+	}
+
+	private _drawLineToNode(comment: CommentModel, padding: number) {
+		if (!comment || !(comment._parent instanceof NodeSvg) || !comment.svgGroup) return;
+		const svg = this.getSvg();
+		const ws = this.workspace;
+
+		if (comment.svgLine) comment.svgLine.remove();
+
+		const nodeWSPos = comment._parent.relativeCoords;
+		const nodeBBox = comment._parent.svgGroup!.bbox();
+		const nodeTopCenter = ws.workspaceToScreen(
+			nodeWSPos.x + nodeBBox.width / 2,
+			nodeWSPos.y
+		);
+
+		const parentWSPos = comment._parent.relativeCoords;
+		const commentRelPos = comment.relativeCoords;
+		const commentAbsX = parentWSPos.x + commentRelPos.x;
+		const commentAbsY = parentWSPos.y + commentRelPos.y;
+		const commentBBox = comment.svgGroup!.bbox();
+		const commentTopCenter = ws.workspaceToScreen(
+			commentAbsX + (commentBBox.width + padding * 2) / 2,
+			commentAbsY
+		);
+
+		comment.svgLine = svg.line(
+			nodeTopCenter.x, nodeTopCenter.y,
+			commentTopCenter.x, commentTopCenter.y
+		)
+			.stroke({ color: '#888', width: 1, dasharray: '3,2' })
+			.addClass(CommentRenderer.COMMENT_LINE_TAG)
+			.back();
+	}
+
+	clearAllComments() {
+		const svg = this.getSvg();
+		svg.find(`.${CommentRenderer.COMMENT_G_TAG}`).forEach(el => el.remove());
+		svg.find(`.${CommentRenderer.COMMENT_LINE_TAG}`).forEach(el => el.remove());
+		eventer.destroyByTag(CommentRenderer.RENDERER_TAG_EL);
+
+		for (let [_, node] of this.workspace._nodeDB) {
+			const comment = node.getComment();
+			if (comment) comment.svgGroup = undefined;
+		}
+
+		for (const comment of this.workspace.getComments()) {
+			comment.svgGroup = undefined;
+		}
+	}
+
+	clearCommentLines() {
+		const svg = this.getSvg();
+		svg.find(`.${CommentRenderer.COMMENT_LINE_TAG}`).forEach(el => el.remove());
+	}
+
+	drawAllComments() {
+		for (const comment of this.workspace.getComments()) this.drawComment(comment);
+		for (let [_, node] of this.workspace._nodeDB) {
+			const comment = node.getComment();
+			if (comment) this.drawComment(comment);
+		}
+	}
+
+	getSvg(): Svg {
+		return this.workspace.svg;
+	}
+    getWs(): WorkspaceSvg {
+        return this.workspace;
+    }
+}
+
+export default CommentRenderer;