multi-gauge 0.1.0

package/src/layout/GridLayout.js

@@ -0,0 +1,405 @@
+import { MultiGaugeError } from '../errors.js';
+
+function positiveInteger(value, fallback) {
+    return Number.isInteger(value) && value > 0 ? value : fallback;
+}
+
+function cloneEntries(entries) {
+    return new Map([...entries].map(([id, item]) => [id, { ...item }]));
+}
+
+function overlaps(a, b) {
+    return a.row < b.row + b.rowSpan
+        && a.row + a.rowSpan > b.row
+        && a.col < b.col + b.colSpan
+        && a.col + a.colSpan > b.col;
+}
+
+function sortItems(entries) {
+    return [...entries].sort(([idA, a], [idB, b]) => a.row - b.row
+        || a.col - b.col
+        || idA.localeCompare(idB));
+}
+
+/** A non-mutating drag/resize transaction over a committed GridLayout. */
+export class GridDragSession {
+    #layout;
+    #id;
+    #mode;
+    #snapshot;
+    #preview;
+    #valid = true;
+    #active = true;
+
+    constructor(layout, id, mode = 'move') {
+        if (mode !== 'move' && mode !== 'resize') {
+            throw new MultiGaugeError(`Unknown grid transaction mode: ${mode}.`);
+        }
+        if (!layout.has(id)) {
+            throw new MultiGaugeError(`Unknown gauge: ${id}.`);
+        }
+        this.#layout = layout;
+        this.#id = id;
+        this.#mode = mode;
+        this.#snapshot = layout.snapshot();
+        this.#preview = cloneEntries(this.#snapshot);
+    }
+
+    get entries() {
+        return cloneEntries(this.#preview);
+    }
+
+    get placement() {
+        return { ...this.#preview.get(this.#id) };
+    }
+
+    get valid() {
+        return this.#valid;
+    }
+
+    preview(change) {
+        if (!this.#active) {
+            throw new MultiGaugeError('This grid transaction is no longer active.');
+        }
+        const current = this.#snapshot.get(this.#id);
+        const candidate = this.#mode === 'resize'
+            ? {
+                ...current,
+                row: Number.isInteger(change.row) ? change.row : current.row,
+                col: Number.isInteger(change.col) ? change.col : current.col,
+                rowSpan: positiveInteger(change.rowSpan, current.rowSpan),
+                colSpan: positiveInteger(change.colSpan, current.colSpan)
+            }
+            : {
+                ...current,
+                row: change.row,
+                col: change.col
+            };
+        const next = this.#layout.previewPlacement(this.#id, candidate, this.#snapshot);
+        this.#valid = Boolean(next);
+        this.#preview = next ?? cloneEntries(this.#snapshot);
+        return {
+            valid: this.#valid,
+            entries: this.entries,
+            placement: this.placement
+        };
+    }
+
+    commit() {
+        if (!this.#active) {
+            return false;
+        }
+        this.#active = false;
+        if (!this.#valid) {
+            return false;
+        }
+        return this.#layout.commit(this.#preview);
+    }
+
+    cancel() {
+        if (!this.#active) {
+            return false;
+        }
+        this.#active = false;
+        this.#preview = cloneEntries(this.#snapshot);
+        return true;
+    }
+}
+
+/** Grid placement and geometry, independent from DOM and WebGPU. */
+export class GridLayout {
+    #columns;
+    #rows;
+    #gap;
+    #items = new Map();
+    #saved = new Map();
+
+    constructor({ rows = 1, columns = 1, gap = 8 } = {}) {
+        this.#rows = positiveInteger(rows, 1);
+        this.#columns = positiveInteger(columns, 1);
+        this.#gap = Math.max(0, Number(gap) || 0);
+    }
+
+    get config() {
+        return { rows: this.#rows, columns: this.#columns, gap: this.#gap };
+    }
+
+    get size() {
+        return this.#items.size;
+    }
+
+    has(id) {
+        return this.#items.has(id);
+    }
+
+    get(id) {
+        const item = this.#items.get(id);
+        return item ? { ...item } : undefined;
+    }
+
+    entries() {
+        return [...this.#items.entries()].map(([id, item]) => [id, { ...item }]);
+    }
+
+    snapshot() {
+        return cloneEntries(this.#items);
+    }
+
+    beginDrag(id, mode = 'move') {
+        return new GridDragSession(this, id, mode);
+    }
+
+    add(id, requested = {}) {
+        if (this.#items.has(id)) {
+            throw new MultiGaugeError(`Gauge id already exists: ${id}.`);
+        }
+        const rowSpan = positiveInteger(requested.rowSpan, 1);
+        const colSpan = positiveInteger(requested.colSpan, 1);
+        const explicit = Number.isInteger(requested.row) && Number.isInteger(requested.col);
+        const position = explicit
+            ? { row: requested.row, col: requested.col, rowSpan, colSpan }
+            : this.#find(rowSpan, colSpan, this.#items);
+        if (!position || !this.#fits(position, this.#items)) {
+            throw new MultiGaugeError(`Gauge "${id}" does not fit in the grid.`);
+        }
+        this.#items.set(id, position);
+        return { ...position };
+    }
+
+    remove(id) {
+        this.#saved.delete(id);
+        return this.#items.delete(id);
+    }
+
+    move(id, row, col) {
+        const session = this.beginDrag(id, 'move');
+        const result = session.preview({ row, col });
+        if (!result.valid || !session.commit()) {
+            return false;
+        }
+        return this.get(id);
+    }
+
+    resize(id, rowSpan, colSpan) {
+        const session = this.beginDrag(id, 'resize');
+        const result = session.preview({ rowSpan, colSpan });
+        if (!result.valid || !session.commit()) {
+            return false;
+        }
+        return this.get(id);
+    }
+
+    /** Resolve a candidate from a stable snapshot without changing committed state. */
+    previewPlacement(id, candidate, source = this.#items) {
+        const initial = source.get(id);
+        if (!initial || !this.#inBounds(candidate)) {
+            return null;
+        }
+        const base = cloneEntries(source);
+        const collisions = sortItems(new Map([...base].filter(([otherId, item]) => otherId !== id
+            && !item.maximized && overlaps(candidate, item))));
+
+        if (collisions.length === 0) {
+            base.set(id, { ...candidate });
+            return base;
+        }
+
+        if (collisions.length === 1) {
+            const [otherId, other] = collisions[0];
+            const exactFootprint = candidate.row === other.row && candidate.col === other.col
+                && candidate.rowSpan === other.rowSpan && candidate.colSpan === other.colSpan
+                && initial.rowSpan === other.rowSpan && initial.colSpan === other.colSpan;
+            if (exactFootprint) {
+                base.set(id, { ...candidate });
+                base.set(otherId, { ...other, row: initial.row, col: initial.col });
+                if (this.#valid(base)) {
+                    return base;
+                }
+            }
+        }
+
+        const partial = cloneEntries(base);
+        partial.delete(id);
+        for (const [otherId] of collisions) {
+            partial.delete(otherId);
+        }
+        partial.set(id, { ...candidate });
+        const rowDirection = Math.sign(candidate.row - initial.row);
+        const colDirection = Math.sign(candidate.col - initial.col);
+        let resolved = true;
+        for (const [otherId, item] of collisions) {
+            const position = this.#nearestPosition(item, partial, {
+                row: item.row + rowDirection * candidate.rowSpan,
+                col: item.col + colDirection * candidate.colSpan
+            });
+            if (!position) {
+                resolved = false;
+                break;
+            }
+            partial.set(otherId, { ...item, ...position });
+        }
+        if (resolved && this.#valid(partial)) {
+            return partial;
+        }
+
+        const compacted = new Map([[id, { ...candidate }]]);
+        for (const [otherId, item] of sortItems(new Map([...base].filter(([otherId]) => otherId !== id)))) {
+            const position = this.#find(item.rowSpan, item.colSpan, compacted);
+            if (!position) {
+                return null;
+            }
+            compacted.set(otherId, { ...item, ...position });
+        }
+        return this.#valid(compacted) ? compacted : null;
+    }
+
+    /** Atomically replace committed placements with a validated preview. */
+    commit(entries) {
+        if (!(entries instanceof Map) || entries.size !== this.#items.size
+            || [...this.#items.keys()].some((id) => !entries.has(id))
+            || !this.#valid(entries)) {
+            return false;
+        }
+        this.#items = cloneEntries(entries);
+        this.#saved.clear();
+        return true;
+    }
+
+    maximize(id) {
+        this.#remember(id);
+        const current = this.#require(id);
+        this.#items.set(id, { ...current, row: 0, col: 0, rowSpan: this.#rows, colSpan: this.#columns, maximized: true });
+        return this.get(id);
+    }
+
+    minimize(id) {
+        this.#remember(id);
+        const current = this.#require(id);
+        const position = this.#find(1, 1, this.#items, id);
+        if (!position) {
+            return false;
+        }
+        this.#items.set(id, { ...current, ...position, rowSpan: 1, colSpan: 1, minimized: true });
+        return this.get(id);
+    }
+
+    restore(id) {
+        const saved = this.#saved.get(id);
+        if (!saved || !this.#fits(saved, this.#items, id)) {
+            return false;
+        }
+        this.#items.set(id, saved);
+        this.#saved.delete(id);
+        return this.get(id);
+    }
+
+    occupancy(ignoreId, entries = this.#items) {
+        const cells = Array.from({ length: this.#rows }, () => Array(this.#columns).fill(null));
+        for (const [id, item] of entries) {
+            if (id === ignoreId || item.maximized) {
+                continue;
+            }
+            for (let row = item.row; row < item.row + item.rowSpan; row += 1) {
+                for (let col = item.col; col < item.col + item.colSpan; col += 1) {
+                    if (cells[row]) {
+                        cells[row][col] = id;
+                    }
+                }
+            }
+        }
+        return cells;
+    }
+
+    rectangles(gridRect, entries = this.#items) {
+        const width = Math.max(0, Number(gridRect?.width) || 0);
+        const height = Math.max(0, Number(gridRect?.height) || 0);
+        const originX = Number(gridRect?.x) || 0;
+        const originY = Number(gridRect?.y) || 0;
+        const cellWidth = Math.max(0, (width - this.#gap * (this.#columns - 1)) / this.#columns);
+        const cellHeight = Math.max(0, (height - this.#gap * (this.#rows - 1)) / this.#rows);
+        const result = new Map();
+        for (const [id, item] of entries) {
+            result.set(id, {
+                x: originX + item.col * (cellWidth + this.#gap),
+                y: originY + item.row * (cellHeight + this.#gap),
+                width: item.colSpan * cellWidth + (item.colSpan - 1) * this.#gap,
+                height: item.rowSpan * cellHeight + (item.rowSpan - 1) * this.#gap
+            });
+        }
+        return result;
+    }
+
+    #require(id) {
+        const item = this.#items.get(id);
+        if (!item) {
+            throw new MultiGaugeError(`Unknown gauge: ${id}.`);
+        }
+        return item;
+    }
+
+    #remember(id) {
+        if (!this.#saved.has(id)) {
+            const current = this.#require(id);
+            const { maximized, minimized, ...plain } = current;
+            this.#saved.set(id, plain);
+        }
+    }
+
+    #find(rowSpan, colSpan, entries, ignoreId) {
+        for (let row = 0; row <= this.#rows - rowSpan; row += 1) {
+            for (let col = 0; col <= this.#columns - colSpan; col += 1) {
+                const candidate = { row, col, rowSpan, colSpan };
+                if (this.#fits(candidate, entries, ignoreId)) {
+                    return candidate;
+                }
+            }
+        }
+        return null;
+    }
+
+    #nearestPosition(item, entries, anchor) {
+        const candidates = [];
+        for (let row = 0; row <= this.#rows - item.rowSpan; row += 1) {
+            for (let col = 0; col <= this.#columns - item.colSpan; col += 1) {
+                const candidate = { row, col, rowSpan: item.rowSpan, colSpan: item.colSpan };
+                if (this.#fits(candidate, entries)) {
+                    candidates.push(candidate);
+                }
+            }
+        }
+        candidates.sort((a, b) => (Math.abs(a.row - anchor.row) + Math.abs(a.col - anchor.col))
+            - (Math.abs(b.row - anchor.row) + Math.abs(b.col - anchor.col))
+            || a.row - b.row || a.col - b.col);
+        return candidates[0] ?? null;
+    }
+
+    #inBounds(item) {
+        return Number.isInteger(item.row) && Number.isInteger(item.col)
+            && positiveInteger(item.rowSpan, 0) === item.rowSpan
+            && positiveInteger(item.colSpan, 0) === item.colSpan
+            && item.row >= 0 && item.col >= 0
+            && item.row + item.rowSpan <= this.#rows
+            && item.col + item.colSpan <= this.#columns;
+    }
+
+    #fits(item, entries, ignoreId) {
+        return this.#inBounds(item) && ![...entries].some(([id, placed]) => id !== ignoreId
+            && !placed.maximized && overlaps(item, placed));
+    }
+
+    #valid(entries) {
+        const items = [...entries];
+        for (let index = 0; index < items.length; index += 1) {
+            const [, item] = items[index];
+            if (!this.#inBounds(item)) {
+                return false;
+            }
+            for (let other = index + 1; other < items.length; other += 1) {
+                if (!item.maximized && !items[other][1].maximized && overlaps(item, items[other][1])) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+}

package/src/layout/PanelLayout.js

@@ -0,0 +1,70 @@
+const HEADER_GAP = 8;
+
+function dimension(value) {
+    return Math.max(0, Number(value) || 0);
+}
+
+/**
+ * Split a panel into mutually exclusive header and grid regions.
+ * Every value is expressed in CSS pixels local to the canvas content box.
+ */
+export function layoutPanel({ width, height, hasHeader = false } = {}) {
+    const panelWidth = dimension(width);
+    const panelHeight = dimension(height);
+    const preferredHeaderHeight = panelWidth < 300 ? 52 : 64;
+    const headerHeight = hasHeader
+        ? Math.min(preferredHeaderHeight, Math.max(0, panelHeight - HEADER_GAP))
+        : 0;
+    const gap = headerHeight > 0 ? Math.min(HEADER_GAP, panelHeight - headerHeight) : 0;
+    const gridY = headerHeight + gap;
+
+    return Object.freeze({
+        panelRect: Object.freeze({ x: 0, y: 0, width: panelWidth, height: panelHeight }),
+        headerRect: Object.freeze({ x: 0, y: 0, width: panelWidth, height: headerHeight }),
+        gridRect: Object.freeze({
+            x: 0,
+            y: gridY,
+            width: panelWidth,
+            height: Math.max(0, panelHeight - gridY)
+        }),
+        gap
+    });
+}
+
+/** Convert a panel-local rectangle to coordinates local to a containing rect. */
+export function localRect(rect, container) {
+    return {
+        x: rect.x - container.x,
+        y: rect.y - container.y,
+        width: rect.width,
+        height: rect.height
+    };
+}
+
+/** Header content geometry, also in panel-local CSS pixels. */
+export function layoutHeader(headerRect, { hasIcon = false } = {}) {
+    const compact = headerRect.width < 300;
+    const paddingX = compact ? 14 : 18;
+    const paddingY = compact ? 9 : 10;
+    const iconSize = hasIcon ? (compact ? 18 : 20) : 0;
+    const textX = headerRect.x + paddingX + (hasIcon ? iconSize + 10 : 0);
+    const badgeWidth = Math.min(110, Math.max(0, headerRect.width * 0.24));
+
+    return {
+        compact,
+        iconRect: hasIcon ? {
+            x: headerRect.x + paddingX,
+            y: headerRect.y + (headerRect.height - iconSize) / 2,
+            width: iconSize,
+            height: iconSize
+        } : null,
+        title: { x: textX, y: headerRect.y + paddingY, size: compact ? 14 : 16 },
+        subtitle: { x: textX, y: headerRect.y + paddingY + (compact ? 20 : 23), size: compact ? 10 : 11 },
+        badgeRect: {
+            x: headerRect.x + headerRect.width - paddingX - badgeWidth,
+            y: headerRect.y + (headerRect.height - 26) / 2,
+            width: badgeWidth,
+            height: 26
+        }
+    };
+}

package/src/model/GaugeModel.js

@@ -0,0 +1,196 @@
+import { MultiGaugeError } from '../errors.js';
+
+export const GAUGE_TYPES = new Set(['arc', 'linear', 'compass', 'status']);
+export const LINEAR_MODES = new Set(['fill', 'marker', 'fill-marker']);
+export const ORIENTATIONS = new Set(['horizontal', 'vertical']);
+
+const DEFAULT_STATUS_STATES = [
+    { value: false, label: 'OFF', kind: 'inactive' },
+    { value: true, label: 'ON', kind: 'normal' }
+];
+
+function finite(value, fallback) {
+    return Number.isFinite(value) ? value : fallback;
+}
+
+function cloneItems(items = []) {
+    return items.map((item) => ({ ...item }));
+}
+
+/** Clamp a number to an inclusive range. */
+export function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+
+/** Normalize a scalar to 0..1. Compass values wrap instead of clamping. */
+export function normalizeValue(gauge, value) {
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        return 0;
+    }
+    if (gauge.type === 'compass') {
+        const range = gauge.max - gauge.min;
+        return range > 0 ? (((number - gauge.min) % range) + range) % range / range : 0;
+    }
+    return (clamp(number, gauge.min, gauge.max) - gauge.min) / (gauge.max - gauge.min);
+}
+
+/** Split a possibly wrapping band into monotonically increasing intervals. */
+export function projectBand(band, min, max, cyclic = false) {
+    const from = clamp(finite(Number(band.from), min), min, max);
+    const to = clamp(finite(Number(band.to), max), min, max);
+    if (cyclic && from > to) {
+        return [[from, max], [min, to]];
+    }
+    return [[Math.min(from, to), Math.max(from, to)]];
+}
+
+/** Resolve the active band, giving later declarations precedence when bands overlap. */
+export function resolveBand(gauge, value = gauge.value) {
+    if (gauge.type === 'status') {
+        return null;
+    }
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        return null;
+    }
+    const current = gauge.type === 'compass'
+        ? gauge.min + normalizeValue(gauge, number) * (gauge.max - gauge.min)
+        : clamp(number, gauge.min, gauge.max);
+    for (let index = gauge.bands.length - 1; index >= 0; index -= 1) {
+        const band = gauge.bands[index];
+        const segments = projectBand(band, gauge.min, gauge.max, gauge.type === 'compass');
+        if (segments.some(([from, to]) => current >= from && current <= to)) {
+            return band;
+        }
+    }
+    return null;
+}
+
+/** Resolve a public status value to its configured state. */
+export function resolveStatus(gauge, value) {
+    const direct = gauge.states.find((state) => Object.is(state.value, value));
+    if (direct) {
+        return direct;
+    }
+    if (typeof value === 'boolean') {
+        const numeric = gauge.states.find((state) => state.value === Number(value));
+        if (numeric) {
+            return numeric;
+        }
+    }
+    if (typeof value === 'number') {
+        const boolean = gauge.states.find((state) => typeof state.value === 'boolean'
+            && Number(state.value) === value);
+        if (boolean) {
+            return boolean;
+        }
+    }
+    return gauge.states[0];
+}
+
+/** Convert public gauge configuration to the stable internal CPU model. */
+export function normalizeGauge(input) {
+    if (!input || typeof input !== 'object') {
+        throw new MultiGaugeError('Gauge configuration must be an object.');
+    }
+    if (typeof input.id !== 'string' || input.id.length === 0) {
+        throw new MultiGaugeError('Every gauge needs a non-empty string id.');
+    }
+    const type = input.type ?? 'arc';
+    if (!GAUGE_TYPES.has(type)) {
+        throw new MultiGaugeError(`Unknown gauge type: ${type}.`);
+    }
+
+    const min = finite(Number(input.min), type === 'compass' ? 0 : 0);
+    const max = finite(Number(input.max), type === 'compass' ? 360 : 100);
+    if (max <= min) {
+        throw new MultiGaugeError(`Gauge "${input.id}" requires max greater than min.`);
+    }
+    const orientation = ORIENTATIONS.has(input.orientation) ? input.orientation : 'horizontal';
+    const mode = LINEAR_MODES.has(input.mode) ? input.mode : 'fill';
+    const states = cloneItems(input.states?.length ? input.states : DEFAULT_STATUS_STATES);
+    const gauge = {
+        id: input.id,
+        type,
+        label: String(input.label ?? input.id),
+        info: String(input.info ?? ''),
+        unit: String(input.unit ?? ''),
+        min,
+        max,
+        value: input.value ?? (type === 'status' ? states[0].value : min),
+        orientation,
+        mode,
+        startAngle: finite(Number(input.startAngle), -135),
+        endAngle: finite(Number(input.endAngle), 135),
+        bands: cloneItems(input.bands),
+        markers: cloneItems(input.markers),
+        states,
+        row: Number.isInteger(input.row) ? input.row : undefined,
+        col: Number.isInteger(input.col) ? input.col : undefined,
+        rowSpan: Math.max(1, Math.trunc(finite(Number(input.rowSpan), 1))),
+        colSpan: Math.max(1, Math.trunc(finite(Number(input.colSpan), 1)))
+    };
+    gauge.value = coerceValue(gauge, gauge.value);
+    return gauge;
+}
+
+/** Coerce a runtime value without changing the gauge definition. */
+export function coerceValue(gauge, value) {
+    if (gauge.type === 'status') {
+        return resolveStatus(gauge, value).value;
+    }
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        return gauge.value ?? gauge.min;
+    }
+    if (gauge.type === 'compass') {
+        const range = gauge.max - gauge.min;
+        return (((number - gauge.min) % range) + range) % range + gauge.min;
+    }
+    return clamp(number, gauge.min, gauge.max);
+}
+
+/** Add or update a marker while retaining a serializable plain object. */
+export function setGaugeMarker(gauge, id, value, patch = {}) {
+    const index = gauge.markers.findIndex((marker) => marker.id === id);
+    const marker = { ...(index >= 0 ? gauge.markers[index] : {}), ...patch, id, value };
+    if (index >= 0) {
+        gauge.markers[index] = marker;
+    } else {
+        gauge.markers.push(marker);
+    }
+    return marker;
+}
+
+/** Strip internal state and undefined values from a gauge. */
+export function serializeGauge(gauge, placement) {
+    const result = {
+        id: gauge.id,
+        type: gauge.type,
+        label: gauge.label,
+        info: gauge.info,
+        unit: gauge.unit,
+        min: gauge.min,
+        max: gauge.max,
+        value: gauge.value,
+        row: placement.row,
+        col: placement.col,
+        rowSpan: placement.rowSpan,
+        colSpan: placement.colSpan,
+        bands: cloneItems(gauge.bands),
+        markers: cloneItems(gauge.markers)
+    };
+    if (gauge.type === 'linear') {
+        result.orientation = gauge.orientation;
+        result.mode = gauge.mode;
+    }
+    if (gauge.type === 'arc') {
+        result.startAngle = gauge.startAngle;
+        result.endAngle = gauge.endAngle;
+    }
+    if (gauge.type === 'status') {
+        result.states = cloneItems(gauge.states);
+    }
+    return result;
+}