flexdesk 0.1.0

package/src/charts/downsample.js

@@ -0,0 +1,119 @@
+/**
+ * downsample.js
+ *
+ * Client-side time-series decimation for the render path. A long live run
+ * accumulates thousands of points per series; feeding all of them to
+ * Plotly.react() every refresh is what makes a running dashboard crawl.
+ * These helpers cap the points actually drawn while preserving the visual
+ * shape.
+ *
+ * Two strategies, mirroring EcoSim (App/downsampler.py = LTTB,
+ * streaming/server.py = stride decimation):
+ *
+ *   • strideDownsampleShared — one set of indices applied to the shared x
+ *     axis and EVERY series. Cheap, gap-safe (nulls keep their slot), and
+ *     alignment-safe (all series sample the same x), so it works for
+ *     stacked/area charts and multi-series subplots. This is the default
+ *     used by the dashboard tiles.
+ *
+ *   • lttb — Largest-Triangle-Three-Buckets for a single (x, y) line.
+ *     Higher visual fidelity (keeps peaks/troughs) but each series picks
+ *     its own x, so it's only safe for independent line/scatter traces
+ *     with finite y. Offered for callers that want it.
+ */
+
+/**
+ * Pick ~targetPoints evenly-spaced indices out of [0, n), always including
+ * the first and last. Returns an ascending Int array; returns null when no
+ * decimation is needed (n <= targetPoints) so callers can skip the copy.
+ *
+ * @param {number} n
+ * @param {number} targetPoints
+ * @returns {number[]|null}
+ */
+export function strideIndices(n, targetPoints) {
+    if (!Number.isFinite(n) || n <= 0) return null;
+    const target = Math.max(2, Math.floor(targetPoints) || 0);
+    if (n <= target) return null;
+    const step = (n - 1) / (target - 1);
+    const idx = new Array(target);
+    for (let i = 0; i < target; i++) idx[i] = Math.round(i * step);
+    idx[target - 1] = n - 1;           // pin the last point exactly
+    // Dedupe (rounding can collide on dense targets) while staying ascending.
+    let w = 0;
+    for (let r = 0; r < idx.length; r++) {
+        if (w === 0 || idx[r] > idx[w - 1]) idx[w++] = idx[r];
+    }
+    idx.length = w;
+    return idx;
+}
+
+/**
+ * Decimate a shared x axis plus a set of aligned series using one common
+ * set of indices, so every series stays sampled at the same x (alignment-
+ * and gap-safe). No-op (returns the inputs untouched) when under threshold.
+ *
+ * @param {Array<number>} time — shared x values
+ * @param {Object<string, Array>} series — name → aligned value array
+ * @param {number} targetPoints
+ * @returns {{ time: Array<number>, series: Object<string, Array> }}
+ */
+export function strideDownsampleShared(time, series, targetPoints) {
+    const idx = strideIndices(time?.length ?? 0, targetPoints);
+    if (!idx) return { time, series };
+    const dsTime = idx.map((i) => time[i]);
+    const dsSeries = {};
+    for (const [name, arr] of Object.entries(series || {})) {
+        if (!Array.isArray(arr)) { dsSeries[name] = arr; continue; }
+        dsSeries[name] = idx.map((i) => (i < arr.length ? arr[i] : null));
+    }
+    return { time: dsTime, series: dsSeries };
+}
+
+/**
+ * Largest-Triangle-Three-Buckets for one line. Preserves the first and
+ * last points and the most "feature-bearing" point per bucket. Assumes
+ * ascending, finite x; y entries that are null/NaN are treated as 0 for
+ * the area math (callers with gappy series should prefer the stride path).
+ *
+ * @param {Array<number>} x
+ * @param {Array<number>} y
+ * @param {number} threshold — target point count
+ * @returns {{ x: Array<number>, y: Array<number> }}
+ */
+export function lttb(x, y, threshold) {
+    const n = Math.min(x?.length ?? 0, y?.length ?? 0);
+    const target = Math.floor(threshold) || 0;
+    if (target <= 0 || target >= n) return { x: x.slice(0, n), y: y.slice(0, n) };
+    if (target < 3) return { x: [x[0], x[n - 1]], y: [y[0], y[n - 1]] };
+
+    const num = (v) => (Number.isFinite(v) ? v : 0);
+    const outX = [x[0]];
+    const outY = [y[0]];
+    const bucketSize = (n - 2) / (target - 2);
+    let a = 0;
+
+    for (let i = 0; i < target - 2; i++) {
+        let nextStart = Math.floor((i + 1) * bucketSize) + 1;
+        let nextEnd = Math.min(Math.floor((i + 2) * bucketSize) + 1, n);
+        if (nextEnd <= nextStart) nextEnd = Math.min(nextStart + 1, n);
+        let avgX = 0, avgY = 0;
+        const count = nextEnd - nextStart;
+        for (let j = nextStart; j < nextEnd; j++) { avgX += x[j]; avgY += num(y[j]); }
+        avgX /= count; avgY /= count;
+
+        const curStart = Math.floor(i * bucketSize) + 1;
+        const curEnd = Math.min(Math.floor((i + 1) * bucketSize) + 1, n);
+        const ax = x[a], ay = num(y[a]);
+        let maxArea = -1, chosen = curStart;
+        for (let j = curStart; j < curEnd; j++) {
+            const area = Math.abs((ax - avgX) * (num(y[j]) - ay) - (ax - x[j]) * (avgY - ay));
+            if (area > maxArea) { maxArea = area; chosen = j; }
+        }
+        outX.push(x[chosen]); outY.push(y[chosen]);
+        a = chosen;
+    }
+
+    outX.push(x[n - 1]); outY.push(y[n - 1]);
+    return { x: outX, y: outY };
+}

package/src/charts/plot_config.js

@@ -0,0 +1,176 @@
+/**
+ * plot_config.js — the shape of a plot, independent of what is being plotted.
+ *
+ * Subplot grid layouts, the default subplot, the legacy-format migration, and the
+ * NaN strategies (gap / zero / hold / interpolate). Not one line of it knows what
+ * an economy is.
+ *
+ * It lived in ui/js/notebook/cells/plot_cell.js — an EcoAgent notebook cell with
+ * 60 domain words in it — and that single import was the only thing keeping the
+ * plot windows out of @flexdesk/charts. Five modules imported these helpers THROUGH the
+ * cell, which is how you end up with a chart library that depends on a notebook.
+ *
+ * plot_cell.js re-exports everything here, so its existing importers are unchanged.
+ */
+
+import { getSeriesColor } from './plotly_wrapper.js';
+
+
+let _uid = 0;
+function uid(prefix = 'p') { return `${prefix}-${++_uid}-${Date.now().toString(36)}`; }
+
+/**
+ * Apply NaN handling strategy to a data array.
+ * @param {number[]} data
+ * @param {'gap'|'zero'|'hold'|'interpolate'} strategy
+ * @param {number[]} xData  — for interpolation
+ * @returns {Array}
+ */
+function applyNanHandling(data, strategy, xData) {
+    const isMissing = (v) => v === null || v === undefined || (typeof v === 'number' && !Number.isFinite(v));
+
+    if (strategy === 'zero') return data.map(v => isMissing(v) ? 0 : v);
+
+    if (strategy === 'hold') {
+        const result = [];
+        let last = null;
+        for (const v of data) {
+            if (isMissing(v)) result.push(last);
+            else { last = v; result.push(v); }
+        }
+        return result;
+    }
+
+    if (strategy === 'interpolate') {
+        const result = [...data];
+        for (let i = 0; i < result.length; i++) {
+            if (!isMissing(result[i])) continue;
+            let left = -1, right = -1;
+            for (let j = i - 1; j >= 0; j--) { if (!isMissing(result[j])) { left = j; break; } }
+            for (let j = i + 1; j < result.length; j++) { if (!isMissing(result[j])) { right = j; break; } }
+            if (left >= 0 && right >= 0 && xData) {
+                const frac = (xData[i] - xData[left]) / (xData[right] - xData[left]);
+                result[i] = result[left] + frac * (result[right] - result[left]);
+            } else if (left >= 0) {
+                result[i] = result[left];
+            } else if (right >= 0) {
+                result[i] = result[right];
+            } else {
+                result[i] = null;
+            }
+        }
+        return result;
+    }
+
+    // 'gap' (default) — replace with null for Plotly gap rendering
+    return data.map(v => isMissing(v) ? null : v);
+}
+
+// ─── Layout templates (matching figure_cell.js) ─────────────────────────────
+
+const PLOT_LAYOUTS = Object.freeze({
+    '1x1':         { label: 'Single',        slots: 1, grid: { columns: '1fr',       rows: '1fr'     }, areas: [{ slot: 0, gridArea: '1/1/2/2' }] },
+    '1x2':         { label: 'Side by side',   slots: 2, grid: { columns: '1fr 1fr',   rows: '1fr'     }, areas: [{ slot: 0, gridArea: '1/1/2/2' }, { slot: 1, gridArea: '1/2/2/3' }] },
+    '2x1':         { label: 'Stacked',        slots: 2, grid: { columns: '1fr',       rows: '1fr 1fr' }, areas: [{ slot: 0, gridArea: '1/1/2/2' }, { slot: 1, gridArea: '2/1/3/2' }] },
+    '2x2':         { label: '2\u00d72 Grid',  slots: 4, grid: { columns: '1fr 1fr',   rows: '1fr 1fr' }, areas: [{ slot: 0, gridArea: '1/1/2/2' }, { slot: 1, gridArea: '1/2/2/3' }, { slot: 2, gridArea: '2/1/3/2' }, { slot: 3, gridArea: '2/2/3/3' }] },
+    '1x3':         { label: 'Three columns',  slots: 3, grid: { columns: '1fr 1fr 1fr', rows: '1fr'   }, areas: [{ slot: 0, gridArea: '1/1/2/2' }, { slot: 1, gridArea: '1/2/2/3' }, { slot: 2, gridArea: '1/3/2/4' }] },
+    'wide-top':    { label: '1 + 2',          slots: 3, grid: { columns: '1fr 1fr',   rows: '1fr 1fr' }, areas: [{ slot: 0, gridArea: '1/1/2/3' }, { slot: 1, gridArea: '2/1/3/2' }, { slot: 2, gridArea: '2/2/3/3' }] },
+    'wide-bottom': { label: '2 + 1',          slots: 3, grid: { columns: '1fr 1fr',   rows: '1fr 1fr' }, areas: [{ slot: 0, gridArea: '1/1/2/2' }, { slot: 1, gridArea: '1/2/2/3' }, { slot: 2, gridArea: '2/1/3/3' }] },
+});
+
+function makeDefaultSubplot(index) {
+    return {
+        id: uid('sp'),
+        displayName: '',
+        chartType: 'line',
+        legendPosition: 'hidden',
+        interpolation: 'linear',
+        nanHandling: 'gap',
+        showDataPoints: false,
+        showHpTrend: false,
+        showHpCycle: false,
+        hpLambda: 1600,
+        xAxis: { useTime: true, variable: '' },
+        zAxis: null,
+        yAxes: [{
+            id: uid('y'),
+            label: '',
+            scale: 'linear',
+            position: 'left',
+            min: null,
+            max: null,
+            step: null,
+            series: [],
+        }],
+    };
+}
+
+function migrateData(data) {
+    // Already in multi-layout format
+    if (data?.layout && Array.isArray(data?.subplots)) {
+        // Migrate caption → description (old field name)
+        if ('caption' in data && !('description' in data)) {
+            data.description = data.caption;
+            data.caption = '';
+        }
+        return data;
+    }
+
+    // Migrate legacy single-chart format → multi-layout with one subplot
+    const legacySingle = migrateSingleChart(data);
+    return {
+        layout: '1x1',
+        subplots: [{ id: uid('sp'), ...legacySingle }],
+        caption: '',
+        description: data?.caption ?? data?.description ?? '',
+        doc: data?.doc ?? '',
+    };
+}
+
+/** Migrate legacy flat series[]/variables[] to yAxes[] single-chart format. */
+function migrateSingleChart(data) {
+    if (data?.yAxes) {
+        return {
+            displayName:    data.displayName ?? '',
+            chartType:      data.chartType ?? 'line',
+            legendPosition: data.legendPosition ?? 'hidden',
+            interpolation:  data.interpolation ?? 'linear',
+            nanHandling:    data.nanHandling ?? 'gap',
+            showDataPoints: data.showDataPoints ?? false,
+            yAxes: data.yAxes,
+        };
+    }
+
+    const series = data?.series ?? data?.variables?.map((v, i) => ({
+        variable: v, label: '', color: getSeriesColor(i),
+    })) ?? [];
+
+    return {
+        displayName:    data?.title ?? data?.displayName ?? '',
+        chartType:      data?.chartType ?? data?.widgetType ?? 'line',
+        legendPosition: data?.legendPosition ?? 'hidden',
+        interpolation:  data?.interpolation ?? 'linear',
+        nanHandling:    data?.nanHandling ?? 'gap',
+        showDataPoints: data?.showDataPoints ?? false,
+        yAxes: [{
+            id: uid('y'),
+            label: data?.yLabel ?? '',
+            scale: 'linear',
+            position: 'left',
+            min: null,
+            max: null,
+            series: series.map((s, i) => ({
+                id: s.id ?? uid('s'),
+                variable: s.variable ?? '',
+                label: s.label ?? '',
+                color: s.color ?? getSeriesColor(i),
+                lineWidth: s.lineWidth ?? 2,
+                lineStyle: s.lineStyle ?? 'solid',
+                stackGroup: s.stackGroup ?? null,
+                ...(s.overlay ? { overlay: s.overlay } : {}),
+            })),
+        }],
+    };
+}
+
+export { uid, applyNanHandling, PLOT_LAYOUTS, makeDefaultSubplot, migrateData, migrateSingleChart };