@kabel-project/kabel 1.0.7

package/controllers/base.ts

@@ -0,0 +1,186 @@
+import WorkspaceSvg from '../src/workspace-svg';
+import userState from '../util/user-state';
+
+interface Vec2 { x: number; y: number; }
+
+export default class WorkspaceController {
+    workspace: WorkspaceSvg;
+
+    keysDown: Set<string>;
+    mouseBtns: Set<number>;
+    mousePos: Vec2;
+    lastMousePos: Vec2;
+    isDragging: boolean;
+
+    wheelDelta: number;
+    movedListeners: (() => void)[];
+    _lastMoveFire = 0;
+    _moveThrottleMs = 100; // bump this to whatever doesn't lag you
+    _queuedMove = false;
+    _moveTimeout: any = null;
+    _updateInt: any;
+
+    constructor(workspace: WorkspaceSvg) {
+        this.workspace = workspace;
+
+        this.keysDown = new Set();
+        this.mouseBtns = new Set();
+        this.mousePos = { x: 0, y: 0 };
+        this.lastMousePos = { x: 0, y: 0 };
+        this.isDragging = false;
+        this.wheelDelta = 0;
+        this.movedListeners = [];
+
+        this._setupListeners();
+
+        this._updateInt = setInterval(() => this.update(), 16);
+    }
+    addMoveListener(cb: () => void) {
+        this.movedListeners.push(cb);
+    }
+
+    removeMoveListener(cb: () => void) {
+        const i = this.movedListeners.indexOf(cb);
+        if (i !== -1) this.movedListeners.splice(i, 1);
+    }
+
+    fireDidMove() {
+        if (typeof queueMicrotask !== 'undefined') {
+            queueMicrotask(() => {
+                for (let cb of this.movedListeners) {
+                    try { cb(); } catch (e) { console.error(e); }
+                }
+            });
+        } else {
+            Promise.resolve().then(() => {
+                for (let cb of this.movedListeners) {
+                    try { cb(); } catch (e) { console.error(e); }
+                }
+            });
+        }
+    }
+
+    _throttledFireDidMove() {
+        const now = performance.now();
+
+        // enough time passed → fire instantly
+        if (now - this._lastMoveFire >= this._moveThrottleMs) {
+            this._lastMoveFire = now;
+            this.fireDidMove();
+            return;
+        }
+
+        // otherwise queue ONE fire
+        if (!this._queuedMove) {
+            this._queuedMove = true;
+            const wait = this._moveThrottleMs - (now - this._lastMoveFire);
+
+            this._moveTimeout = setTimeout(() => {
+                this._queuedMove = false;
+                this._lastMoveFire = performance.now();
+                this.fireDidMove();
+            }, wait);
+        }
+    }
+    getZoom() {
+        return 1;
+    }
+    canMove() {
+        return true;
+    }
+    private _setupListeners() {
+        window.addEventListener('keydown', e => this.keysDown.add(e.key));
+        window.addEventListener('keyup', e => this.keysDown.delete(e.key));
+
+        window.addEventListener('mousedown', e => this.mouseBtns.add(e.button));
+        window.addEventListener('mouseup', e => this.mouseBtns.delete(e.button));
+
+        window.addEventListener('mousemove', e => {
+            this.lastMousePos = { ...this.mousePos };
+            this.mousePos = { x: e.clientX, y: e.clientY };
+        });
+
+        window.addEventListener('wheel', e => {
+            this.wheelDelta = e.deltaY;
+        });
+
+        window.addEventListener('mousedown', e => {
+            if (e.button === 0) this.isDragging = true;
+        });
+        window.addEventListener('mouseup', e => {
+            if (e.button === 0) this.isDragging = false;
+        });
+    }
+
+    update() {
+        // Can handle keyboard shortcuts or auto-pan here
+    }
+
+    // --- Camera methods ---
+    pan(dx: number, dy: number) {
+        const x = this.workspace._camera.x, y = this.workspace._camera.y;
+        this.workspace._camera.x += dx;
+        this.workspace._camera.y += dy;
+        if (x == this.workspace._camera.x && y == this.workspace._camera.y) {
+            return;
+        }
+        this._throttledFireDidMove();
+        this.workspace.didMove = true;
+        this.workspace.fireMoveListeners();
+        this.refreshPos();
+    }
+
+    setCamera(pos: Vec2) {
+        const x = this.workspace._camera.x, y = this.workspace._camera.y;
+        this.workspace._camera.x = pos.x;
+        this.workspace._camera.y = pos.y;
+        if (x == this.workspace._camera.x && y == this.workspace._camera.y) {
+            return;
+        }
+        this._throttledFireDidMove();
+        this.workspace.didMove = true;
+        this.workspace.fireMoveListeners();
+        this.refreshPos();
+    }
+
+    centerOn(pos: Vec2) {
+        const wsSize = this.workspace.getSize?.() ?? { width: 0, height: 0 };
+        this.setCamera({
+            x: pos.x - wsSize.width / 2,
+            y: pos.y - wsSize.height / 2
+        });
+    }
+
+
+
+    // --- Coordinate conversion ---
+    screenToWorkspace(x: number, y: number): Vec2 {
+        const cam = this.workspace._camera;
+        return {
+            x: x + cam.x,
+            y: y + cam.y
+        };
+    }
+
+    workspaceToScreen(x: number, y: number): Vec2 {
+        const cam = this.workspace._camera;
+        return {
+            x: (x - cam.x),
+            y: (y - cam.y)
+        };
+    }
+
+    // --- Refresh ---
+    refreshPos() {
+        this.workspace.refresh?.();
+    }
+
+    redraw() {
+        this.workspace.redraw?.();
+    }
+
+    // --- Cleanup ---
+    stop() {
+        clearInterval(this._updateInt);
+    }
+}

package/controllers/wasd.ts

@@ -0,0 +1,132 @@
+import WorkspaceController from './base';
+import WorkspaceSvg from '../src/workspace-svg';
+import userState from '../util/user-state';
+
+interface Vec2 { x: number; y: number; }
+
+export default class WASDController extends WorkspaceController {
+    moveSpeed: number;
+    doAccelerate?: boolean;
+    accelSpeed: number;
+    friction: number;
+    velocity: Vec2;
+    zoom: number = 1;
+    zoomSpeed: number;
+    minZoom: number;
+    maxZoom: number;
+    isFalloff: boolean;
+    constructor(workspace: WorkspaceSvg, moveSpeed?: number) {
+        super(workspace);
+        this.moveSpeed = workspace.options.moveSpeed || moveSpeed || 5;
+
+        this.doAccelerate = workspace.options?.controls?.wasdSmooth ?? false;
+        this.accelSpeed = workspace.options?.controls?.wasdAccelerate ?? 0.2;
+        this.friction = workspace.options?.controls?.wasdFriction ?? 0.85;
+
+        this.velocity = { x: 0, y: 0 };
+        this.isFalloff = false;
+
+        // Zoom settings
+        this.zoomSpeed = workspace.options?.controls?.zoomSpeed ?? 0.1;
+        this.minZoom = workspace.options?.controls?.minZoom ?? 0.1;
+        this.maxZoom = workspace.options?.controls?.maxZoom ?? 4;
+        this.zoom = 1;
+        // Bind wheel for zoom
+        workspace._wsTop.addEventListener('wheel', this.onWheel.bind(this), { passive: false });
+    }
+
+    canMove() {
+        return !userState.hasState('typing');
+    }
+
+    update() {
+        super.update();
+        if (!this.canMove()) return;
+
+        let inputX = 0;
+        let inputY = 0;
+
+        if (this.keysDown.has('w') || this.keysDown.has('ArrowUp')) inputY -= 1;
+        if (this.keysDown.has('s') || this.keysDown.has('ArrowDown')) inputY += 1;
+        if (this.keysDown.has('a') || this.keysDown.has('ArrowLeft')) inputX -= 1;
+        if (this.keysDown.has('d') || this.keysDown.has('ArrowRight')) inputX += 1;
+
+        if (this.doAccelerate) {
+            // Accelerate velocity towards input direction
+            this.velocity.x += inputX * this.accelSpeed;
+            this.velocity.y += inputY * this.accelSpeed;
+
+            // Apply friction
+            this.velocity.x *= this.friction;
+            this.velocity.y *= this.friction;
+            if (inputX == 0 && inputY == 0) {
+                this.isFalloff = true;
+            } else {
+                this.isFalloff = false;
+            }
+            // Only pan if velocity is noticeable
+            if (Math.abs(this.velocity.x) > 0.01 || Math.abs(this.velocity.y) > 0.01) {
+                this.pan(this.velocity.x, this.velocity.y);
+            }
+        } else {
+            // Instant movement
+            const dx = inputX * this.moveSpeed;
+            const dy = inputY * this.moveSpeed;
+            if (dx !== 0 || dy !== 0) this.pan(dx, dy);
+        }
+    }
+    pan(dx: number, dy: number) {
+        const x = this.workspace._camera.x, y = this.workspace._camera.y;
+        this.workspace._camera.x += dx;
+        this.workspace._camera.y += dy;
+        if (x == this.workspace._camera.x && y == this.workspace._camera.y) {
+            return;
+        }
+        if (!this.isFalloff) {
+            this._throttledFireDidMove();
+            this.workspace.didMove = true;
+            this.workspace.fireMoveListeners();
+            this.refreshPos();
+        }
+        this.refreshPos();
+    }
+    /**
+     * Handles wheel events for zooming.
+     * Zooms around the mouse position for intuitive zooming.
+     */
+    onWheel(e: WheelEvent) {
+        e.preventDefault();
+
+        const oldZoom = this.getZoom();
+        let delta = -e.deltaY * this.zoomSpeed * 0.01; // normalize wheel
+        let newZoom = oldZoom * (1 + delta);
+
+        // Clamp zoom
+        newZoom = Math.max(this.minZoom, Math.min(this.maxZoom, newZoom));
+
+        // Zoom around cursor
+        const mouseX = e.clientX;
+        const mouseY = e.clientY;
+
+        const wsMouse = this.workspace.screenToWorkspace(mouseX, mouseY);
+
+        // Apply new zoom
+        this.setZoom(newZoom);
+
+        // Adjust camera so the point under cursor stays stable
+        this.workspace._camera.x = wsMouse.x - mouseX / newZoom;
+        this.workspace._camera.y = wsMouse.y - mouseY / newZoom;
+
+        this.workspace.refresh();
+    }
+
+    /** Returns current zoom level */
+    getZoom() {
+        return this.zoom;
+    }
+
+    /** Sets zoom directly */
+    setZoom(zoom: number) {
+        this.zoom = zoom;
+    }
+}

package/docs/README.md

@@ -0,0 +1,98 @@
+**Kabel Project Docs v1.0.6**
+
+***
+
+# 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](_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](_media/index.html)
+
+---
+
+## Documentation
+
+Please refer to [Kabel Guide](_media/docs.md)
+
+---
+
+## License
+
+MIT

package/docs/_media/docs.md

@@ -0,0 +1,289 @@
+
+# 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, {
+	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: {}
+		}]
+	}]
+}
+```
+
+**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.
+
+---