@kabel-project/kabel 1.0.7

package/src/workspace.ts

@@ -0,0 +1,155 @@
+import NodePrototypes from "./prototypes";
+import newHeadlessNode from "./headless-node";
+import Widget from "./widget";
+import WidgetPrototypes from "./widget-prototypes";
+import CommentModel from "./comment";
+import UndoRedoHistory from "./undo-redo";
+import { ConnectableField } from "./field";
+
+/**
+ * Headless workspace that holds nodes, widgets, and comments without any rendering or camera.
+ */
+class Workspace {
+	_nodeDB: Map<string, any>; // Node storage
+	_widgetDB: Map<string, Widget>;
+	_commentDB: Set<CommentModel>;
+    isHeadless: boolean = true;
+	constructor() {
+		this._nodeDB = new Map();
+		this._widgetDB = new Map();
+		this._commentDB = new Set();
+	}
+
+	/** Node management */
+	addNode(node: any, nodeId?: string) {
+		const id = nodeId || node.id;
+		if (this._nodeDB.has(id)) {
+			console.warn(`Node with id ${id} already exists, overwriting.`);
+		}
+		if (node.workspace !== this) node.workspace = this;
+		this._nodeDB.set(id, node);
+	}
+
+	newNode(type: keyof typeof NodePrototypes, add: boolean = true) {
+		if (!NodePrototypes[type]) return;
+		const node = newHeadlessNode(type as string);
+		if (!node) return;
+		if (add) this.addNode(node);
+		return node;
+	}
+
+	spawnAt(type: keyof typeof NodePrototypes, x: number, y: number) {
+		const node = this.newNode(type, false);
+		if (!node) return;
+		node.relativeCoords.set(x, y);
+		this.addNode(node);
+		return node;
+	}
+
+	getNode(id: string | any) {
+		if (id instanceof Object && id.id) return id;
+		return this._nodeDB.get(id);
+	}
+
+	removeNodeById(id: string) {
+		const node = this._nodeDB.get(id);
+		if (!node) return;
+		this.derefNode(node);
+		this._nodeDB.delete(id);
+	}
+
+	removeNode(node: any) {
+		if (!node) return;
+		this.removeNodeById(node.id);
+	}
+
+	derefNode(node: any) {
+		const prev = node.previousConnection?.getFrom?.();
+		if (prev?.nextConnection) prev.nextConnection.disconnectTo?.();
+		const next = node.nextConnection?.getTo?.();
+		if (next?.previousConnection) next.previousConnection.disconnectFrom?.();
+
+		for (let field of node.allFields()) {
+			if ((field as ConnectableField).hasConnectable?.()) {
+				(field as ConnectableField).disconnect();
+			}
+		}
+	}
+
+	/** Widget management */
+	newWidget(type: string): Widget | void {
+		const opts = WidgetPrototypes[type];
+		if (!opts) return;
+		const wdgt = opts.cls ? new opts.cls(this, opts) : new Widget(this, opts);
+		this._widgetDB.set(wdgt.id, wdgt);
+		return wdgt;
+	}
+
+	getWidget(id: string): Widget | undefined {
+		return this._widgetDB.get(id);
+	}
+
+	/** Comment management */
+	addComment() {
+		const model = new CommentModel(this);
+		this._commentDB.add(model);
+		return model;
+	}
+
+	getComment(id: string) {
+		return Array.from(this._commentDB).find(e => e.id === id);
+	}
+
+	removeComment(commentOrId: CommentModel | string) {
+		let comment: CommentModel | undefined;
+		if (typeof commentOrId === "string") comment = this.getComment(commentOrId);
+		else comment = commentOrId;
+		if (!comment) return false;
+		this._commentDB.delete(comment);
+		return true;
+	}
+
+	getComments() {
+		return Array.from(this._commentDB);
+	}
+
+    /**
+     * Internal: Add widget to DB
+     * @param wdgt - The widget
+     */
+    _addWidgetToDB(wdgt: Widget) {
+        this._widgetDB.set(wdgt.id, wdgt);
+    }
+    /**
+     * Internal: Delete a widget from DB.
+     * @param wdgt - Widget to delete
+     */
+    _delWidgetFromDB(wdgt: Widget) {
+        this._widgetDB.delete(wdgt.id);
+    }
+    
+	/** Serialization */
+	fromJson(json: { nodes: any[]; circular: boolean }, recordBigEvent: boolean = false) {
+		for (let [, node] of this._nodeDB.entries()) this.removeNode(node);
+
+		if (json.circular) {
+			for (let node of json.nodes) {
+				(node.constructor as any).deserialize(node, this);
+			}
+		} else {
+			for (let node of json.nodes) {
+				(node.constructor as any).fromJson(node, this);
+			}
+		}
+	}
+
+	toJson(circular: boolean) {
+		const nodes = [];
+		for (let [, node] of this._nodeDB) {
+			if (node.topLevel) nodes.push(circular ? node.serialize() : node.toJson());
+		}
+		return { circular, nodes };
+	}
+}
+
+export default Workspace;

package/test-server.js

@@ -0,0 +1,61 @@
+const express = require('express');
+const path = require('path');
+const chokidar = require('chokidar');
+const livereload = require('livereload');
+const connectLivereload = require('connect-livereload');
+const { exec } = require('child_process');
+
+const app = express();
+const PORT = 3000;
+
+// Path to your dist folder
+const DIST_DIR = path.resolve(__dirname, 'dist');
+
+// ---- LiveReload server ----
+const liveReloadServer = livereload.createServer();
+liveReloadServer.watch(DIST_DIR);
+
+// Notify browser when files change
+liveReloadServer.server.once('connection', () => {
+    setTimeout(() => {
+        liveReloadServer.refresh('/');
+    }, 100);
+});
+
+// Middleware to inject livereload script
+app.use(connectLivereload());
+
+// Serve all files relative to project root
+app.use(express.static(DIST_DIR, { index: 'index.html' }));
+
+// Watch source files for changes and rebuild
+// Watch multiple source directories for changes
+const watcher = chokidar.watch([
+    path.resolve(__dirname, 'src'),
+    path.resolve(__dirname, 'themes'),
+    path.resolve(__dirname, 'renderers'),
+    path.resolve(__dirname, 'util'),
+    path.resolve(__dirname, 'events'),
+    path.resolve(__dirname, 'controllers'),
+    path.resolve(__dirname, 'media'),
+    path.resolve(__dirname, 'comment-renderer')
+], {
+    ignored: /(^|[\/\\])\../, // ignore dotfiles
+    persistent: true
+});
+
+
+watcher.on('change', (filePath) => {
+    console.log(`[watcher] File changed: ${filePath}`);
+    console.log('[watcher] Running build...');
+    exec('npm run build', (err, stdout, stderr) => {
+        if (err) console.error(err);
+        console.log(stdout);
+        console.error(stderr);
+        liveReloadServer.refresh('/');
+    });
+});
+
+app.listen(PORT, () => {
+    console.log(`Test server running: http://localhost:${PORT}`);
+});

package/themes/dark.ts

@@ -0,0 +1,32 @@
+import type { WSTheme } from '../src/workspace-svg';
+
+const KabelDarkTheme: WSTheme = {
+	UIStyles: {
+		workspaceBGColor: '#121412ff',
+		toolboxCategoriesBG: {
+			position: 'absolute',
+			left: '0',
+			top: '0',
+			width: '20%',
+			height: '100%',
+			background: '#1b1b1b',
+			color: '#e0e0e0',
+			overflowY: 'auto',
+			border: 'none',
+			outline: 'none',
+		},
+		toolboxFlyoutBG: {
+			display: 'block',
+			background: '#1e1e1e',
+			color: '#e0e0e0',
+			overflowY: 'auto',
+			padding: '4px', 
+			borderRadius: '4px',
+			boxShadow: '0 2px 6px rgba(0,0,0,0.5)',
+			border: 'none',
+			outline: 'none',
+		},
+	},
+};
+
+export default KabelDarkTheme;

package/themes/default.ts

@@ -0,0 +1,28 @@
+import type {WSTheme} from '../src/workspace-svg'
+
+
+
+const KabelWSTheme: WSTheme = {
+	UIStyles: {
+        workspaceBGColor: '#ffffff',
+		toolboxCategoriesBG: {
+			position: 'absolute',
+			left: '0',
+			top: '0',
+			width: '20%',
+			height: '100%',
+			background: 'rgba(240,240,240,0.9)',
+			overflowY: 'auto',
+		},
+		toolboxFlyoutBG: {
+			display: 'none',
+			background: 'rgba(240,240,240,0.9)', // reuse same neutral bg
+			overflowY: 'auto',
+			padding: '4px', // like nodes padding
+			borderRadius: '4px',
+			boxShadow: '0 2px 6px rgba(0,0,0,0.15)',
+		},
+	},
+};
+
+export default KabelWSTheme;

package/themes/themes.ts

@@ -0,0 +1,9 @@
+import KabelWSTheme from './default';
+import KabelDarkTheme from './dark';
+
+const Themes = {
+    Classic: KabelWSTheme,
+    Dark: KabelDarkTheme
+}
+
+export default Themes;

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+	"compilerOptions": {
+		// File Layout
+		"rootDir": "./",
+		"outDir": "./dist",
+
+		// Environment Settings
+		"module": "node20",
+		"target": "ES2022",
+		"types": ["node"],
+
+		// Outputs
+		"sourceMap": true,
+		"declaration": true,
+		"declarationMap": true,
+
+		// Type Safety
+		"strict": true,
+		"noUncheckedIndexedAccess": true,
+		"exactOptionalPropertyTypes": true,
+		"skipLibCheck": true
+	},
+	"include": ["src/**/*", "util", "controllers", "events", "comment-renderer", "renderers", "*.d.ts"],
+	"exclude": ["node_modules", "dist"]
+}

package/typedoc.json

@@ -0,0 +1,10 @@
+{
+  "entryPoints": ["src/index.ts", "src"],
+  "out": "_READ_ME_MEDIA_/internal-docs",
+  "exclude": ["**/node_modules/**", "**/dist/**"],
+  "excludePrivate": false,
+  "includeVersion": true,
+  "tsconfig": "tsconfig.json",       // your TS config
+  "plugin": ["typedoc-plugin-markdown"], // optional: markdown output
+  "name": "Kabel Project Docs"
+}

package/util/emitter.ts

@@ -0,0 +1,33 @@
+type EventHandler<T = any> = (payload: T) => void;
+
+class EventEmitter<Events extends Record<string, any>> {
+	private listeners: { [K in keyof Events]?: EventHandler<Events[K]>[] } = {};
+
+	on<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>) {
+		if (!this.listeners[event]) this.listeners[event] = [];
+		this.listeners[event]!.push(handler);
+		return this;
+	}
+
+	off<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>) {
+		if (!this.listeners[event]) return this;
+		this.listeners[event] = this.listeners[event]!.filter(h => h !== handler);
+		return this;
+	}
+
+	emit<K extends keyof Events>(event: K, payload: Events[K]) {
+		if (!this.listeners[event]) return false;
+		this.listeners[event]!.forEach(handler => handler(payload));
+		return true;
+	}
+
+	once<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>) {
+		const wrapper = (payload: Events[K]) => {
+			handler(payload);
+			this.off(event, wrapper);
+		};
+		this.on(event, wrapper);
+		return this;
+	}
+}
+export default EventEmitter;

package/util/env.ts

@@ -0,0 +1,11 @@
+const isNode = typeof process !== 'undefined' && !!process.versions?.node;
+const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined';
+const isWebWorker = typeof self !== 'undefined' && typeof self.importScripts === 'function';
+
+const env: {
+    isBrowser: boolean;
+    isNode: boolean;
+    isWebWorker: boolean;
+} = { isNode, isBrowser, isWebWorker };
+
+export default env;

package/util/escape-html.ts

@@ -0,0 +1,22 @@
+/**
+ * Escapes special characters in a string to their corresponding HTML entities.
+ *
+ * Specifically, it replaces:
+ * - `&` with `&`
+ * - `'` with `'`
+ * - `"` with `"`
+ * - `<` with `&lt;`
+ * - `>` with `&gt;`
+ *
+ * @param {string} s - The string to escape.
+ * @returns {string} The escaped string with special characters replaced by HTML entities.
+ */
+function escapeAttr(s: string): string {
+    return s.replace(/&/g, "&amp;")
+            .replace(/'/g, "&apos;")
+            .replace(/"/g, "&quot;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;");
+}
+
+export default escapeAttr;

package/util/eventer.ts

@@ -0,0 +1,108 @@
+import { Svg, Rect, Circle, G, Path, Element } from '@svgdotjs/svg.js';
+
+export type EventType = string;
+export type EventArgs = Record<string, any>;
+export type EventSetupFn = (el: Element, args?: EventArgs) => (() => void) | void;
+
+export interface RegisteredEl {
+    tags: string[],
+    el: Element;
+    type: EventType;
+    args?: EventArgs | undefined;      // allow undefined explicitly
+    destroyFn?: (() => void) | undefined; // allow undefined explicitly
+}
+
+/**
+ * Used by the Kabel renderer to tag svg.js elements as interactable with the kabel system.
+ */
+class Eventer {
+    private elements: RegisteredEl[] = [];
+    private eventRegistry: Map<EventType, EventSetupFn> = new Map();
+
+    // Register an event type with a setup function
+    registerEvent(type: EventType, setupFn: EventSetupFn) {
+        this.eventRegistry.set(type, setupFn);
+        return this; // allow chaining
+    }
+    tagElement(el: Element, tags?: string[] | string) {
+        if (!tags) return this;
+        const tagList = Array.isArray(tags) ? tags : [tags];
+
+        // Find the registered elements for this el
+        for (const reg of this.elements) {
+            if (reg.el === el) {
+                for (const t of tagList) {
+                    if (!reg.tags.includes(t)) reg.tags.push(t);
+                }
+            }
+        }
+        return this;
+    }
+
+    destroyByTag(tag: string) {
+        let destroyed = false;
+        this.elements = this.elements.filter(reg => {
+            if (reg.tags.includes(tag)) {
+                if (reg.destroyFn) {
+                    reg.destroyFn();
+                    destroyed = true;
+                }
+                return false; // remove this element
+            }
+            return true; // keep element
+        });
+        return destroyed ? 1 : 0;
+    }
+
+    // addElement
+    addElement(el: Element, types: EventType | EventType[], args?: EventArgs) {
+        const typeList = Array.isArray(types) ? types : [types];
+        for (const type of typeList) {
+            const destroyFn = this.setupElement(el, type, args) as (() => void) | undefined;
+            this.elements.push({
+                tags: [],
+                el,
+                type,
+                args,
+                destroyFn
+            });
+        }
+        return this;
+    }
+
+    // refresh
+    refresh() {
+        for (const reg of this.elements) {
+            if (reg.destroyFn) reg.destroyFn();
+            reg.destroyFn = this.setupElement(reg.el, reg.type, reg.args) as (() => void) | undefined;
+        }
+    }
+
+
+    // Destroy event(s) for an element
+    destroyElement(el: Element, type?: EventType) {
+        let destroyed = false;
+        for (const reg of this.elements) {
+            if (reg.el === el && (!type || reg.type === type)) {
+                if (reg.destroyFn) {
+                    reg.destroyFn();
+                    destroyed = true;
+                }
+                // Remove from elements array
+                this.elements = this.elements.filter(r => r !== reg);
+            }
+        }
+        return destroyed ? 1 : 0;
+    }
+
+    private setupElement(el: Element, type: EventType, args?: EventArgs): (() => void) | undefined {
+        const setupFn = this.eventRegistry.get(type);
+        if (!setupFn) return;
+        const destroyFn = setupFn(el, args);
+        return destroyFn instanceof Function ? destroyFn : undefined;
+    }
+}
+
+const eventer = new Eventer();
+export default eventer;
+export { Eventer };

package/util/has-prop.ts

@@ -0,0 +1,4 @@
+
+export default function hasProp(obj: object, name: string) {
+    return Object.prototype.hasOwnProperty.call(obj, name)
+}

package/util/parse-color.ts

@@ -0,0 +1,42 @@
+// color-utils.ts
+import type { Color, Hex } from '../src/visual-types';
+
+/**
+ * Parse any Color type into a hex string "#RRGGBB"
+ */
+export function parseColor(color: Color): Hex {
+	if (typeof color === 'string') {
+		if (color.startsWith('#')) {
+			// Already a hex string, normalize to full #RRGGBB
+			let hex = color.slice(1);
+			if (hex.length === 3) hex = hex.split('').map(c => c + c).join('');
+			return `#${hex}`;
+		} else {
+			// RGB string "r, g, b"
+			const parts = color.split(',').map(s => parseInt(s.trim(), 10));
+			if (parts.length !== 3) throw new Error(`Invalid RGB string: ${color}`);
+			const [r, g, b] = parts;
+            if ((!r && r!== 0) || (!g && g!== 0) || (!b && b !== 0)) {
+                console.warn(
+                    "Invalid RGB tuple"
+                );
+                return "#000";
+            }
+			return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b
+				.toString(16)
+				.padStart(2, '0')}`;
+		}
+	} else if (Array.isArray(color)) {
+		// RGBTuple [r,g,b]
+		const [r, g, b] = color;
+		return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b
+			.toString(16)
+			.padStart(2, '0')}`;
+	} else {
+		// RGBObject {r,g,b}
+		const { r, g, b } = color;
+		return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b
+			.toString(16)
+			.padStart(2, '0')}`;
+	}
+}

package/util/path.ts

@@ -0,0 +1,99 @@
+// path.ts
+/**
+ * Utility functions to generate SVG path strings or translate them.
+ */
+
+/** Rounded rectangle */
+export function roundedRect(width: number, height: number, radius: number): string {
+	radius = Math.min(radius, width / 2, height / 2);
+	return `
+		M${radius},0
+		H${width - radius}
+		A${radius},${radius} 0 0 1 ${width},${radius}
+		V${height - radius}
+		A${radius},${radius} 0 0 1 ${width - radius},${height}
+		H${radius}
+		A${radius},${radius} 0 0 1 0,${height - radius}
+		V${radius}
+		A${radius},${radius} 0 0 1 ${radius},0
+		Z
+	`.replace(/\s+/g, ' ').trim();
+}
+
+/** Rounded triangle pointing up */
+export function roundedTri(width: number, height: number, radius: number): string {
+	const halfW = width / 2;
+	radius = Math.min(radius, halfW, height / 2);
+	return `
+		M${halfW},0
+		L${width - radius},${height - radius}
+		A${radius},${radius} 0 0 1 ${width - radius*2},${height}
+		L${radius*2},${height}
+		A${radius},${radius} 0 0 1 ${radius},${height - radius}
+		Z
+	`.replace(/\s+/g, ' ').trim();
+}
+
+/** Circle */
+export function circle(radius: number): string {
+	return `
+		M${radius},0
+		A${radius},${radius} 0 1,0 ${-radius},0
+		A${radius},${radius} 0 1,0 ${radius},0
+		Z
+	`.replace(/\s+/g, ' ').trim();
+}
+
+/** Ellipse */
+export function ellipse(rx: number, ry: number): string {
+	return `
+		M${rx},0
+		A${rx},${ry} 0 1,0 ${-rx},0
+		A${rx},${ry} 0 1,0 ${rx},0
+		Z
+	`.replace(/\s+/g, ' ').trim();
+}
+
+/** Star with n points */
+export function star(radius: number, points: number = 5): string {
+	if (points < 2) throw new Error('Star must have at least 2 points');
+	let path = '';
+	const step = (Math.PI * 2) / (points * 2);
+	for (let i = 0; i < points * 2; i++) {
+		const r = i % 2 === 0 ? radius : radius / 2;
+		const x = r * Math.sin(i * step);
+		const y = -r * Math.cos(i * step);
+		path += i === 0 ? `M${x},${y}` : ` L${x},${y}`;
+	}
+	path += ' Z';
+	return path;
+}
+
+/** Regular polygon (triangle, pentagon, hexagon, etc) */
+export function polygon(radius: number, sides: number = 3): string {
+	if (sides < 3) throw new Error('Polygon must have at least 3 sides');
+	let path = '';
+	const step = (Math.PI * 2) / sides;
+	for (let i = 0; i < sides; i++) {
+		const x = radius * Math.cos(i * step - Math.PI / 2);
+		const y = radius * Math.sin(i * step - Math.PI / 2);
+		path += i === 0 ? `M${x},${y}` : ` L${x},${y}`;
+	}
+	path += ' Z';
+	return path;
+}
+import SvgPath from 'svgpath';
+
+/**
+ * Rotate an SVG path string around a given point
+ * @param path - SVG path string
+ * @param angle - rotation angle in degrees
+ * @param cx - x-coordinate of rotation center (default 0)
+ * @param cy - y-coordinate of rotation center (default 0)
+ * @returns new rotated SVG path string
+ */
+export function rotatePath(path: string, angle: number, cx = 0, cy = 0): string {
+	return new SvgPath(path)
+		.rotate(angle, cx, cy)
+		.toString();
+}

package/util/styler.ts

@@ -0,0 +1,41 @@
+class Styler {
+	private styles: Map<string, HTMLStyleElement>;
+
+	constructor() {
+		this.styles = new Map();
+	}
+
+	appendStyles(id: string, css: string): void {
+		if (this.styles.has(id)) return; // Do not append if id exists
+
+		const styleEl = document.createElement('style');
+		styleEl.id = id;
+		styleEl.textContent = css;
+		document.head.appendChild(styleEl);
+		this.styles.set(id, styleEl);
+	}
+
+	removeStyles(id: string): void {
+		const styleEl = this.styles.get(id);
+		if (!styleEl) return;
+
+		styleEl.remove();
+		this.styles.delete(id);
+	}
+
+	updateStyles(id: string, css: string): void {
+		const styleEl = this.styles.get(id);
+		if (!styleEl) return;
+
+		styleEl.textContent = css;
+	}
+
+	hasStyles(id: string): boolean {
+		return this.styles.has(id);
+	}
+}
+export {
+    Styler
+}
+const styler = new Styler();
+export default styler;