@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/charting/CheckboxTreeSelector.js

@@ -0,0 +1,304 @@
+/**
+ * CheckboxTreeSelector — generic tree with checkboxes and tri-state cascading logic.
+ *
+ * Reusable across any domain: build a tree of { id, label, children? } nodes and get back a
+ * DOM container + methods to track checked/unchecked ids. Tri-state: checking a branch checks
+ * all descendants; parent shows indeterminate when some (but not all) children are checked.
+ *
+ * Usage:
+ *   const selector = new CheckboxTreeSelector({ doc: document, nodes: [...], checkedIds: new Set(['id1']) });
+ *   const container = selector.build();
+ *   parent.appendChild(container);
+ *   selector.onChange(ids => { ... });  // fires on any checkbox click
+ *
+ * Node shape:
+ *   { id: string, label: string, children?: Node[] }
+ */
+
+export class CheckboxTreeSelector {
+    constructor({ doc, nodes = [], checkedIds = null } = {}) {
+        this.doc = doc;
+        this.nodes = nodes;
+        this._checkedIds = checkedIds || new Set(); // null (default) = everything checked
+        this._listeners = [];
+        this._checkboxesByNodeId = new Map(); // nodeId -> input[type=checkbox]
+    }
+
+    build() {
+        const container = this.doc.createElement('div');
+        container.style.cssText = 'font-family: sans-serif; font-size: 13px; padding: 4px 0;';
+
+        for (const node of this.nodes) {
+            this._buildNode(node, container, 0);
+        }
+
+        return container;
+    }
+
+    /**
+     * Recursively build DOM for a node and its children.
+     * @private
+     */
+    _buildNode(node, parent, depth = 0) {
+        if (!node.children || node.children.length === 0) {
+            // Leaf: checkbox + label
+            this._buildLeaf(node, parent, depth);
+        } else {
+            // Branch: <details>/<summary> + checkbox
+            this._buildBranch(node, parent, depth);
+        }
+    }
+
+    /**
+     * Build a leaf node (no children).
+     * @private
+     */
+    _buildLeaf(node, parent, depth) {
+        const row = this.doc.createElement('div');
+        row.style.cssText = `display: flex; align-items: center; gap: 6px; margin-bottom: 4px; padding-left: ${depth * 16}px;`;
+
+        const checkbox = this.doc.createElement('input');
+        checkbox.type = 'checkbox';
+        checkbox.id = `checkbox-${node.id}`;
+        checkbox.checked = this._checkedIds.size === 0 || this._checkedIds.has(node.id);
+        checkbox.style.cssText = 'flex-shrink: 0; cursor: pointer;';
+
+        checkbox.addEventListener('change', () => {
+            this._updateChecked(node.id, checkbox.checked, true);
+        });
+
+        this._checkboxesByNodeId.set(node.id, checkbox);
+
+        const label = this.doc.createElement('label');
+        label.htmlFor = checkbox.id;
+        label.textContent = node.label;
+        label.style.cssText = 'flex: 1; cursor: pointer; user-select: none;';
+
+        row.appendChild(checkbox);
+        row.appendChild(label);
+        parent.appendChild(row);
+    }
+
+    /**
+     * Build a branch node (has children, collapsible).
+     * @private
+     */
+    _buildBranch(node, parent, depth) {
+        const details = this.doc.createElement('details');
+        details.style.cssText = `margin-bottom: 4px; padding-left: ${depth * 16}px;`;
+        details.open = true;
+
+        const summary = this.doc.createElement('summary');
+        summary.style.cssText = 'display: flex; align-items: center; gap: 6px; cursor: pointer; user-select: none; padding: 2px 0;';
+
+        const checkbox = this.doc.createElement('input');
+        checkbox.type = 'checkbox';
+        checkbox.id = `checkbox-${node.id}`;
+        const isChecked = this._checkedIds.size === 0 || this._checkedIds.has(node.id);
+        const allChildrenChecked = this._allChildrenChecked(node);
+        const someChildrenChecked = this._someChildrenChecked(node);
+
+        checkbox.checked = isChecked && allChildrenChecked;
+        checkbox.indeterminate = isChecked && someChildrenChecked && !allChildrenChecked;
+        checkbox.style.cssText = 'flex-shrink: 0; cursor: pointer;';
+
+        checkbox.addEventListener('change', () => {
+            this._updateBranch(node, checkbox.checked);
+        });
+
+        this._checkboxesByNodeId.set(node.id, checkbox);
+
+        const label = this.doc.createElement('span');
+        label.textContent = node.label;
+        label.style.cssText = 'flex: 1; cursor: pointer; font-weight: 500;';
+
+        summary.appendChild(checkbox);
+        summary.appendChild(label);
+        details.appendChild(summary);
+
+        const childrenContainer = this.doc.createElement('div');
+        for (const child of node.children) {
+            this._buildNode(child, childrenContainer, depth + 1);
+        }
+        details.appendChild(childrenContainer);
+
+        parent.appendChild(details);
+    }
+
+    /**
+     * Check/uncheck a single leaf node and notify.
+     * @private
+     */
+    _updateChecked(nodeId, checked, notify = true) {
+        if (checked) {
+            this._checkedIds.add(nodeId);
+        } else {
+            this._checkedIds.delete(nodeId);
+        }
+
+        // Update parent indeterminate state (walk up tree — not used for flat leaves, but cleaner)
+        this._updateBranchStates();
+
+        if (notify) {
+            this._notifyListeners();
+        }
+    }
+
+    /**
+     * Check/uncheck a branch and all its descendants.
+     * @private
+     */
+    _updateBranch(node, checked) {
+        const allIds = this._getAllNodeIds(node);
+        if (checked) {
+            allIds.forEach(id => this._checkedIds.add(id));
+        } else {
+            allIds.forEach(id => this._checkedIds.delete(id));
+        }
+
+        // Update DOM state for all affected checkboxes
+        this._updateAllCheckboxes();
+        this._updateBranchStates();
+        this._notifyListeners();
+    }
+
+    /**
+     * Collect all descendant node ids (including the node itself).
+     * @private
+     */
+    _getAllNodeIds(node) {
+        const ids = [node.id];
+        if (node.children) {
+            for (const child of node.children) {
+                ids.push(...this._getAllNodeIds(child));
+            }
+        }
+        return ids;
+    }
+
+    /**
+     * Check if all children (direct and nested) are checked.
+     * @private
+     */
+    _allChildrenChecked(node) {
+        if (!node.children || node.children.length === 0) return true;
+        return node.children.every(child => {
+            const childId = child.id;
+            const hasDescendants = child.children && child.children.length > 0;
+            if (hasDescendants) {
+                return this._allChildrenChecked(child);
+            } else {
+                return this._checkedIds.size === 0 || this._checkedIds.has(childId);
+            }
+        });
+    }
+
+    /**
+     * Check if at least one child (direct or nested) is checked.
+     * @private
+     */
+    _someChildrenChecked(node) {
+        if (!node.children || node.children.length === 0) return false;
+        return node.children.some(child => {
+            const childId = child.id;
+            const hasDescendants = child.children && child.children.length > 0;
+            if (hasDescendants) {
+                return this._someChildrenChecked(child) || (this._checkedIds.size === 0 || this._checkedIds.has(childId));
+            } else {
+                return this._checkedIds.size === 0 || this._checkedIds.has(childId);
+            }
+        });
+    }
+
+    /**
+     * Update checkbox states (indeterminate flags) for all branches.
+     * @private
+     */
+    _updateBranchStates() {
+        for (const [nodeId, checkbox] of this._checkboxesByNodeId) {
+            const node = this._findNode(nodeId);
+            if (node && node.children && node.children.length > 0) {
+                const allChecked = this._allChildrenChecked(node);
+                const someChecked = this._someChildrenChecked(node);
+                checkbox.checked = allChecked;
+                checkbox.indeterminate = someChecked && !allChecked;
+            }
+        }
+    }
+
+    /**
+     * Find a node by id in the tree.
+     * @private
+     */
+    _findNode(id, nodes = this.nodes) {
+        for (const node of nodes) {
+            if (node.id === id) return node;
+            if (node.children) {
+                const found = this._findNode(id, node.children);
+                if (found) return found;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Get the set of currently-checked node ids.
+     */
+    getCheckedIds() {
+        return new Set(this._checkedIds);
+    }
+
+    /**
+     * Set which nodes are checked (Set<string> | null = everything checked).
+     */
+    setCheckedIds(ids) {
+        this._checkedIds = ids ? new Set(ids) : new Set();
+        // Update all checkbox states (checked + indeterminate) to reflect new state
+        this._updateAllCheckboxes();
+        this._updateBranchStates();
+    }
+
+    /**
+     * Update all checkboxes to match current _checkedIds state.
+     * @private
+     */
+    _updateAllCheckboxes() {
+        for (const [nodeId, checkbox] of this._checkboxesByNodeId) {
+            const node = this._findNode(nodeId);
+            if (!node) continue;
+            if (node.children && node.children.length > 0) {
+                // Branch: set checked if all children checked, indeterminate if some checked
+                const allChecked = this._allChildrenChecked(node);
+                const someChecked = this._someChildrenChecked(node);
+                checkbox.checked = allChecked;
+                checkbox.indeterminate = someChecked && !allChecked;
+            } else {
+                // Leaf: set checked if in _checkedIds
+                checkbox.checked = this._checkedIds.size === 0 || this._checkedIds.has(nodeId);
+                checkbox.indeterminate = false;
+            }
+        }
+    }
+
+    /**
+     * Register a change listener. Called with Set<string> of checked ids.
+     */
+    onChange(callback) {
+        this._listeners.push(callback);
+    }
+
+    /**
+     * Notify all listeners of the current checked state.
+     * @private
+     */
+    _notifyListeners() {
+        const ids = this.getCheckedIds();
+        for (const cb of this._listeners) {
+            try {
+                cb(ids);
+            } catch (err) {
+                console.warn('CheckboxTreeSelector listener error:', err);
+            }
+        }
+    }
+}

package/src/charting/ColorField.js

@@ -0,0 +1,107 @@
+/**
+ * ColorField — the control a FormDialog shows for a `color` field: the value
+ * as text (`#rrggbb`, or `none` for no colour, which a native colour input
+ * cannot hold), the browser's colour picker, and a row of preset swatches.
+ * The text box is the field's control (FormDialog `controls[key]`), so its
+ * `value` is what the field reads.
+ *
+ * Presets come from the field (`presets`) or ColorField.PRESETS; `allowNone:
+ * false` leaves out "No colour" (e.g. for text).
+ */
+export class ColorField {
+    /** The value that means no colour (transparent). */
+    static NONE = 'none';
+
+    /** The swatches every colour field offers unless it names its own. */
+    static PRESETS = Object.freeze([
+        { value: 'none', name: 'No colour' },
+        { value: '#000000', name: 'Black' },
+        { value: '#ffffff', name: 'White' },
+        { value: '#ff0000', name: 'Red' },
+        { value: '#00b050', name: 'Green' },
+        { value: '#0070c0', name: 'Blue' },
+        { value: '#ffff00', name: 'Yellow' },
+        { value: '#ffa500', name: 'Orange' },
+        { value: '#7030a0', name: 'Purple' },
+        { value: '#808080', name: 'Grey' },
+        { value: '#d9d9d9', name: 'Light grey' },
+    ]);
+
+    /** Whether `value` is a colour the picker can show (#rrggbb). */
+    static isHex(value) {
+        return /^#[0-9a-f]{6}$/i.test(String(value ?? ''));
+    }
+
+    /**
+     * The presets a field offers.
+     * @param {{presets?: Array<{value, name}>, allowNone?: boolean}} field
+     */
+    static presetsFor({ presets = ColorField.PRESETS, allowNone = true } = {}) {
+        return presets.filter(p => allowNone || p.value !== ColorField.NONE);
+    }
+
+    /**
+     * The el() spec of the control.
+     * @param {Object} field - The FormDialog field (value, presets, allowNone, readOnly)
+     * @param {Object} options
+     * @param {string} options.id - The text box's id
+     * @param {(input) => void} options.ref - Receives the text box (the field's control)
+     * @param {Object} [options.style] - Extra style for the text box (read-only look)
+     */
+    static spec(field, { id, ref, style = {} }) {
+        let text, picker;
+        const disabled = () => !!field.readOnly || !!text?.disabled;
+        const notify = (node) => {
+            for (const type of ['input', 'change']) {
+                const EventClass = node.ownerDocument?.defaultView?.Event ?? globalThis.Event;
+                if (EventClass && node.dispatchEvent) node.dispatchEvent(new EventClass(type, { bubbles: true }));
+            }
+        };
+        const show = (value) => {
+            if (picker && ColorField.isHex(value)) picker.value = value.toLowerCase();
+            if (picker) picker.title = value === ColorField.NONE ? 'No colour' : 'Pick a colour';
+        };
+        const choose = (value) => {
+            if (disabled()) return;
+            text.value = value;
+            show(value);
+            notify(text);
+        };
+        const value = field.value == null ? '' : String(field.value);
+        return {
+            style: { display: 'flex', alignItems: 'center', gap: '6px', flexWrap: 'wrap' },
+            children: [
+                {
+                    tag: 'input',
+                    attrs: { id, type: 'text', value, placeholder: '#rrggbb', readonly: !!field.readOnly, 'aria-label': field.label ?? 'Colour' },
+                    style: { width: '74px', fontFamily: 'monospace', ...style },
+                    on: { input: (e) => show(e.target.value.trim()) },
+                    ref: (n) => { text = n; ref(n); },
+                },
+                {
+                    tag: 'input',
+                    attrs: { type: 'color', value: ColorField.isHex(value) ? value.toLowerCase() : '#cccccc', disabled: !!field.readOnly, 'aria-label': 'Pick a colour' },
+                    style: { width: '32px', height: '22px', padding: '0', border: '1px solid #bbb' },
+                    on: { input: (e) => choose(e.target.value) },
+                    ref: (n) => { picker = n; },
+                },
+                {
+                    style: { display: 'flex', gap: '3px', flexWrap: 'wrap' },
+                    attrs: { role: 'group', 'aria-label': 'Preset colours' },
+                    children: ColorField.presetsFor(field).map(preset => ({
+                        tag: 'button',
+                        attrs: { type: 'button', title: preset.name, 'aria-label': preset.name, 'data-color': preset.value, disabled: !!field.readOnly },
+                        style: {
+                            width: '16px', height: '16px', padding: '0', border: '1px solid #999', borderRadius: '2px', cursor: 'pointer',
+                            // No colour: white, struck through in red.
+                            background: preset.value === ColorField.NONE
+                                ? 'linear-gradient(to top right, #fff 45%, #d00 45%, #d00 55%, #fff 55%)'
+                                : preset.value,
+                        },
+                        on: { click: () => choose(preset.value) },
+                    })),
+                },
+            ],
+        };
+    }
+}

package/src/charting/ColorPalette.js

@@ -0,0 +1,88 @@
+/**
+ * ColorPalette — reusable palette rotation and color utilities for charts.
+ *
+ * Pure color math lives on static methods so it can be used without
+ * instantiating anything. Instance methods delegate to those static helpers
+ * and add the palette-index convenience used by most chart methods.
+ */
+export class ColorPalette {
+    /** The default palette used by line/area/pipe and multiline legends. */
+    static DEFAULT = ['#5470c6', '#91cc75', '#fac858', '#ee6666', '#73c0de', '#3ba272', '#fc8452'];
+
+    constructor(colors = ColorPalette.DEFAULT) {
+        this.colors = colors;
+    }
+
+    /** Return the palette color at `index`, wrapping around. */
+    colorAt(index) {
+        return this.colors[index % this.colors.length];
+    }
+
+    /**
+     * Lighten or darken a hex color by `amount` in [-1, 1].
+     * Positive values lighten; negative values darken.
+     */
+    static lighten(color, amount) {
+        const hex = color.replace('#', '');
+        const num = parseInt(hex, 16);
+        const r = Math.max(0, Math.min(255, (num >> 16) + Math.round(255 * amount)));
+        const g = Math.max(0, Math.min(255, (num >> 8 & 0x00FF) + Math.round(255 * amount)));
+        const b = Math.max(0, Math.min(255, (num & 0x0000FF) + Math.round(255 * amount)));
+        return `#${(0x1000000 + r * 0x10000 + g * 0x100 + b).toString(16).slice(1)}`;
+    }
+
+    lighten(color, amount) {
+        return ColorPalette.lighten(color, amount);
+    }
+
+    /** Parse "#rrggbb" into {r, g, b}. */
+    static hexToRgb(hex) {
+        const num = parseInt(hex.replace('#', ''), 16);
+        return { r: (num >> 16) & 0xFF, g: (num >> 8) & 0xFF, b: num & 0xFF };
+    }
+
+    hexToRgb(hex) {
+        return ColorPalette.hexToRgb(hex);
+    }
+
+    /** Linearly interpolate between two hex colors at t in [0, 1]. */
+    static interpolate(c1, c2, t) {
+        const a = ColorPalette.hexToRgb(c1);
+        const b = ColorPalette.hexToRgb(c2);
+        const r = Math.round(a.r + (b.r - a.r) * t);
+        const g = Math.round(a.g + (b.g - a.g) * t);
+        const bl = Math.round(a.b + (b.b - a.b) * t);
+        return `#${((1 << 24) + (r << 16) + (g << 8) + bl).toString(16).slice(1)}`;
+    }
+
+    interpolate(c1, c2, t) {
+        return ColorPalette.interpolate(c1, c2, t);
+    }
+
+    /** Maps a value within [vMin, vMax] to a color along an N-stop scale
+     *  (linear interpolation between adjacent stops). */
+    static scaleColor(stops, vMin, vMax, v) {
+        if (stops.length === 1) return stops[0];
+        const range = (vMax - vMin) || 1;
+        const t = Math.min(1, Math.max(0, (v - vMin) / range));
+        const segCount = stops.length - 1;
+        const segT = t * segCount;
+        const segIndex = Math.min(segCount - 1, Math.floor(segT));
+        const localT = segT - segIndex;
+        return ColorPalette.interpolate(stops[segIndex], stops[segIndex + 1], localT);
+    }
+
+    scaleColor(stops, vMin, vMax, v) {
+        return ColorPalette.scaleColor(stops, vMin, vMax, v);
+    }
+
+    /** Perceptual-ish luma check for choosing readable text on a color. */
+    static isDark(hex) {
+        const { r, g, b } = ColorPalette.hexToRgb(hex);
+        return (0.299 * r + 0.587 * g + 0.114 * b) < 140;
+    }
+
+    isDark(hex) {
+        return ColorPalette.isDark(hex);
+    }
+}

package/src/charting/CommandHistory.js

@@ -0,0 +1,176 @@
+/**
+ * Command — abstract base class for one reversible edit.
+ *
+ * Subclasses implement `execute()` and `undo()` to mutate and restore some
+ * piece of state. They may also implement `merge(other)` so the history can
+ * coalesce a rapid sequence of edits (e.g. a drag) into a single undoable
+ * entry.
+ */
+export class Command {
+    constructor(label = '') {
+        if (new.target === Command) {
+            throw new TypeError('Command is abstract — subclass it');
+        }
+        this.label = label;
+    }
+
+    /** Apply the edit. Called once when the command is executed. */
+    execute() {
+        throw new Error(`${this.constructor.name} must implement execute()`);
+    }
+
+    /** Reverse the edit. Called when the user presses undo. */
+    undo() {
+        throw new Error(`${this.constructor.name} must implement undo()`);
+    }
+
+    /**
+     * Optional: return a merged command if `other` should be coalesced with
+     * this one, or undefined/null to keep them separate. Used by
+     * CommandHistory for drag/resize coalescing.
+     * @param {Command} other
+     * @returns {Command|undefined}
+     */
+    merge(other) {
+        return undefined;
+    }
+}
+
+/**
+ * CompositeCommand — groups several commands into one undoable unit.
+ */
+export class CompositeCommand extends Command {
+    constructor(label = '', commands = []) {
+        super(label);
+        /** @type {Command[]} */
+        this.commands = commands.slice();
+    }
+
+    add(cmd) {
+        this.commands.push(cmd);
+        return this;
+    }
+
+    execute() {
+        for (const cmd of this.commands) cmd.execute();
+    }
+
+    undo() {
+        for (let i = this.commands.length - 1; i >= 0; i--) {
+            this.commands[i].undo();
+        }
+    }
+}
+
+/**
+ * CommandHistory — bounded undo/redo stack for reversible edits.
+ *
+ * Commands are executed as they are pushed. Undo pops the last executed
+ * command and calls its `undo()`; redo replays it with `execute()`.
+ */
+export class CommandHistory {
+    constructor(options = {}) {
+        this._undoStack = [];
+        this._redoStack = [];
+        this._maxSize = options.maxSize ?? 200;
+        this._onChange = options.onChange ?? null;
+        this._listeners = [];
+        // A token per state: the undo stack's top one (0 at the start), so undoing back to a
+        // state gives its token again and a model can tell it is back where it was saved.
+        this._tokens = [];
+        this._redoTokens = [];
+        this._stamp = 0;
+    }
+
+    /** Which state the history is in: the same token whenever it is back in that state. */
+    get stateToken() {
+        return this._tokens[this._tokens.length - 1] ?? 0;
+    }
+
+    /** Call `fn()` after every execute, undo, redo or clear. Returns an unsubscribe function. */
+    onChange(fn) {
+        this._listeners.push(fn);
+        return () => { this._listeners = this._listeners.filter(l => l !== fn); };
+    }
+
+    get canUndo() { return this._undoStack.length > 0; }
+    get canRedo() { return this._redoStack.length > 0; }
+    get undoLabel() { return this._undoStack[this._undoStack.length - 1]?.label ?? ''; }
+    get redoLabel() { return this._redoStack[this._redoStack.length - 1]?.label ?? ''; }
+
+    /**
+     * Execute a command and push it onto the undo stack. Clears redo.
+     * Checked by shape (execute + undo), not instanceof: a page can load two
+     * copies of this library (the engine and workspace bundles each carry one),
+     * and a Command from either copy must work in either history.
+     */
+    execute(cmd) {
+        if (typeof cmd?.execute !== 'function' || typeof cmd.undo !== 'function') {
+            throw new TypeError('CommandHistory.execute expects a command with execute() and undo()');
+        }
+
+        // Try to merge with the most recent command of the same constructor.
+        const last = this._undoStack[this._undoStack.length - 1];
+        if (last && last.constructor === cmd.constructor && typeof last.merge === 'function') {
+            const merged = last.merge(cmd);
+            if (merged) {
+                merged.execute();
+                this._undoStack[this._undoStack.length - 1] = merged;
+                this._tokens[this._tokens.length - 1] = ++this._stamp;
+                this._notifyChange();
+                return merged;
+            }
+        }
+
+        cmd.execute();
+        this._undoStack.push(cmd);
+        this._tokens.push(++this._stamp);
+        this._redoStack = [];
+        this._redoTokens = [];
+        if (this._undoStack.length > this._maxSize) {
+            this._undoStack.shift();
+            this._tokens.shift();
+        }
+        this._notifyChange();
+        return cmd;
+    }
+
+    undo() {
+        if (!this.canUndo) return null;
+        const cmd = this._undoStack.pop();
+        console.log(`[CommandHistory] UNDO: ${cmd.label}`);
+        cmd.undo();
+        this._redoStack.push(cmd);
+        this._redoTokens.push(this._tokens.pop());
+        this._notifyChange();
+        return cmd;
+    }
+
+    redo() {
+        if (!this.canRedo) return null;
+        const cmd = this._redoStack.pop();
+        console.log(`[CommandHistory] REDO: ${cmd.label}`);
+        cmd.execute();
+        this._undoStack.push(cmd);
+        this._tokens.push(this._redoTokens.pop());
+        this._notifyChange();
+        return cmd;
+    }
+
+    clear() {
+        this._undoStack = [];
+        this._redoStack = [];
+        this._tokens = [];
+        this._redoTokens = [];
+        this._notifyChange();
+    }
+
+    _notifyChange() {
+        if (this._onChange) {
+            try { this._onChange(this.canUndo, this.canRedo); } catch (err) { console.error(err); }
+        }
+        for (const fn of this._listeners) {
+            try { fn(this); } catch (err) { console.error(err); }
+        }
+    }
+}