flexdesk 0.17.7 → 0.17.8

package/docs/components/charts.md

@@ -4,6 +4,72 @@
 
 Plotly-backed charts: the wrapper, the chart types, subplot layouts, downsampling, the plot grid, the plot-config editor and the two plot windows. Plotly itself is not in the bundle; call `setPlotlySource()` with the path to your copy. The plot window's `streamEvents` option is described with the [other application-neutral options](../concepts/domain-neutrality.md#no-application-globals-the-gallery-picker-and-plot-window-events-0170).
 
+## A series transform knows its series, and takes a choice parameter (0.17.8)
+
+Two additions to [`seriesTransforms`](#derived-series-seriestransforms-0170).
+A transform written for `run(y, params)` with number parameters works exactly
+as before.
+
+**The series it runs on.** `run` gets a third argument:
+
+```js
+run(y, params, { series, subplot, results, resolveSeries })
+```
+
+`series` is the subplot's series entry the trace was drawn from (the same
+object, with its `variable` and whatever else you keep on it, such as a
+`scenario`), `subplot` the subplot config, `results` the results the figure was
+drawn from, and `resolveSeries` the `(series, results, subplot) => { y, x? }`
+the figure was drawn with (yours, or `resolveSeriesData`). `y` is still the
+drawn values, after the subplot's NaN handling and whatever your
+`resolveSeries` did to them (a rebase, say). So a transform can draw the same
+series from somewhere else, resolved the same way, instead of guessing which
+series `y` is:
+
+```js
+delta: {
+    label: 'Scenario delta',
+    params: { baseline: { label: 'Compare with', type: 'choice',
+                          options: () => scenarios.map((s) => ({ value: s.id, label: s.name })) } },
+    outputs: { difference: { label: 'Difference', suffix: ' (Δ)', lineStyle: 'dashed' } },
+    run: (y, { baseline }, { series, subplot, resolveSeries }) => {
+        const base = resolveSeries(series, resultsOf(baseline), subplot)?.y;
+        return base ? { difference: y.map((v, i) => v - base[i]) } : {};
+    },
+},
+```
+
+`renderPlotGrid`, and so `PlotPopoutWindow`, run transforms on the same
+traces as in 0.17.7, with the same derived traces: every line or scatter trace
+of the figure, overlays included, never a derived trace. A trace drawn from one
+of the subplot's series gets that series as `context.series`; any other trace,
+such as an overlay, gets `context.series` null (with `subplot`, `results` and
+`resolveSeries` still given), so a transform that needs a series, such as a
+scenario delta, skips it itself (`if (!series) return {};`).
+`deriveSeriesTraces(traces, subplot, seriesTransforms,
+{ onError, seriesOf, results, resolveSeries })` takes the same as options:
+`seriesOf(trace)` names the series a trace was drawn from (null for none); it
+only fills `context.series` and does not choose which traces are run on.
+Without these options `series`, `results` and `resolveSeries` are null.
+
+**A choice parameter.** A parameter declared `{ type: 'choice', options }` is
+a select instead of a number field. `options` is an array of
+`{ value, label }` (a bare value, a `disabled` option and a `{ group, options }`
+entry work as in the other FlexDesk selects), or a function
+`(subplot) => options`, called when the controls are drawn and also whenever
+the parameter needs its default (nothing saved, no `default`), which is on
+each redraw of the figure. It is drawn by
+`renderSeriesTransformControls` with the same select the settings view and
+the flow kit use (choice_controls' `selectBox`), so a value comes back as the
+option's own value (a number stays a number) and a saved value the list no
+longer offers stays chosen, shown as `<value> (not found)`. The pick is saved
+under `subplot.transforms.<id>.params` and passed to `run` like a number
+parameter. Without a `default` and with nothing saved, the parameter is its
+first enabled option (`{ group, options }` entries flattened in order, as the
+select draws them), in the select and in `run`.
+
+`tests/series_transforms.test.mjs` §7 to §10 pin all of it.
+
 ## A data series with no saved plot config opens (0.17.5)
 
 `openDataSeriesPlotWindow` (and `new DataSeriesPlotWindow`, the module's

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flexdesk",
-    "version": "0.17.7",
+    "version": "0.17.8",
     "description": "A tiling window manager and widget set for desktop-class web applications. Zero runtime dependencies.",
     "license": "MIT",
     "repository": {

package/src/charts/plot_grid.js

@@ -84,6 +84,10 @@ function resolveSeriesData(series, results) {
  * @param {Object} [options.overlays] - `{ [series.id]: { years, values } }`, drawn for
  *        every series with an `overlay` description.
  * @param {Object} [options.seriesTransforms] - `{ [id]: transform }` (series_transforms.js).
+ *        Each runs on every line/scatter trace (overlays included, derived traces
+ *        not) as `run(y, params, { series, subplot, results, resolveSeries })`,
+ *        `series` being the subplot's series entry the trace was drawn from, or
+ *        null for an overlay.
  * @param {Function} [options.onTransformError] - `({ transformId, traceName, error })`.
  * @param {Function} [options.derivedTraces] - `(traces, subplot, { results, index })
  *        => trace[] | Promise<trace[]>`: extra traces appended to a subplot's figure.
@@ -197,6 +201,8 @@ function renderPlotGrid(container, plotConfig, results, options = {}) {
         /** The subplot's own series (overlays and derived traces aside), and how many are hidden. */
         let ownCount = 0;
         let hiddenCount = 0;
+        /** Each trace drawn from one of the subplot's series, to that series (a transform's context.series). */
+        const seriesByTrace = new Map();
 
         const useX = sp.xAxis && sp.xAxis.useTime === false && sp.xAxis.variable;
         const xData = useX
@@ -237,7 +243,7 @@ function renderPlotGrid(container, plotConfig, results, options = {}) {
                 const y = Array.isArray(resolved.y)
                     ? applyNanHandling(resolved.y, sp.nanHandling ?? 'gap', x)
                     : resolved.y;
-                traces.push(buildTrace({
+                const trace = buildTrace({
                     chartType: sp.chartType || 'line',
                     x,
                     y,
@@ -249,7 +255,9 @@ function renderPlotGrid(container, plotConfig, results, options = {}) {
                     yAxisId: yRef,
                     showMarkers: sp.showDataPoints ?? false,
                     stackGroup: s.stackGroup ?? null,
-                }));
+                });
+                traces.push(trace);
+                seriesByTrace.set(trace, s);
 
                 const overlay = s.overlay ? opts.overlays?.[s.id] : null;
                 if (!overlay?.years?.length) continue;
@@ -280,8 +288,12 @@ function renderPlotGrid(container, plotConfig, results, options = {}) {
             }
         });
 
-        traces.push(...await deriveSeriesTraces(traces, sp, opts.seriesTransforms,
-                                                { onError: opts.onTransformError ?? undefined }));
+        traces.push(...await deriveSeriesTraces(traces, sp, opts.seriesTransforms, {
+            onError: opts.onTransformError ?? undefined,
+            seriesOf: (trace) => seriesByTrace.get(trace) ?? null,
+            results: data,
+            resolveSeries: opts.resolveSeries,
+        }));
         if (opts.derivedTraces) {
             const extra = await opts.derivedTraces(traces, sp, { results: data, index });
             if (Array.isArray(extra)) traces.push(...extra);

package/src/charts/plot_popout_window.js

@@ -50,7 +50,8 @@ export class PlotPopoutWindow {
      *        renders the Config tab. What it returns is disposed (`dispose()`) when the
      *        window closes, so an editor drawn there (renderPlotConfigEditor) goes with it.
      * @param {Object} [options.seriesTransforms] - `{ [id]: transform }` (series_transforms.js);
-     *        absent => no derived series are drawn
+     *        absent => no derived series are drawn. Each runs as
+     *        `run(y, params, { series, subplot, results, resolveSeries })` (renderPlotGrid).
      * @param {string} [options.refreshEvent='data:changed'] - Bus event after which the
      *        window re-reads `getResults()` and redraws.
      * @param {{delta?: string|null, complete?: string|null}} [options.streamEvents] - Bus

package/src/charts/series_transforms.js

@@ -15,11 +15,44 @@
  *         },
  *     };
  *
- * `run(y, params)` resolves `{ [output]: number[] }`. It is called ONCE per
- * eligible trace (a 2-D line/scatter trace) for each transform with at least one
- * output switched on, and every switched-on output it returns is drawn as an
- * extra trace in the source trace's colour, named `<source name><suffix>`, with
- * the output's `lineStyle` (solid | dashed | dotted) and `lineWidth`.
+ * `run(y, params, context)` resolves `{ [output]: number[] }`. It is called
+ * ONCE per eligible trace (a 2-D line/scatter trace) for each transform with at
+ * least one output switched on, and every switched-on output it returns is
+ * drawn as an extra trace in the source trace's colour, named
+ * `<source name><suffix>`, with the output's `lineStyle` (solid | dashed |
+ * dotted) and `lineWidth`.
+ *
+ * `y` is the drawn values (after the subplot's NaN handling and whatever the
+ * embedder's `resolveSeries` did, such as a rebase). `context` (0.17.8) says
+ * which series they are:
+ *
+ *     { series,          // the subplot's series entry the trace was drawn from
+ *                        //   (its variable, scenario, ...); null when unknown
+ *       subplot,         // the subplot config
+ *       results,         // the results the figure was drawn from, or null
+ *       resolveSeries }  // the `(series, results, subplot) => { y, x? }` the
+ *                        //   figure was drawn with, or null
+ *
+ * so a transform can look the same series up elsewhere (a baseline scenario)
+ * and resolve it the same way. renderPlotGrid (and so PlotPopoutWindow) runs
+ * transforms on the same traces as before 0.17.8 (overlays included, derived
+ * traces never); a trace drawn from one of the subplot's series gets that
+ * series, any other (an overlay) gets `series: null`. A transform written as
+ * `run(y, params)` ignores the third argument and works as before.
+ *
+ * A parameter is a number field by default:
+ *
+ *     window: { label: 'Window', default: 5, min: 1, step: 1 }
+ *
+ * or, declared `type: 'choice'` (0.17.8), a select over `options`: an array of
+ * `{ value, label }`, or a function `(subplot) => [{ value, label }]` called
+ * when the controls are drawn (and when the parameter needs its default):
+ *
+ *     baseline: { label: 'Compare with', type: 'choice',
+ *                 options: () => scenarios.map((s) => ({ value: s.id, label: s.name })) }
+ *
+ * The chosen value is saved and passed to `run` like a number. Without a
+ * `default` and with nothing saved, a choice is its first enabled option.
  *
  * What is switched on lives in the subplot, under `subplot.transforms`:
  *
@@ -30,14 +63,38 @@
  */
 
 import { buildTrace } from './chart_types.js';
+import { flatChoices, selectBox } from '../ui/components/choice_controls.js';
+
+/** Whether a parameter spec is a choice (a select) rather than a number. */
+const isChoice = (spec) => spec?.type === 'choice';
+
+/** A choice parameter's options for `subplot`: its array, or what its function returns. */
+function choiceOptions(spec, subplot) {
+    const options = typeof spec.options === 'function' ? spec.options(subplot) : spec.options;
+    return Array.isArray(options) ? options : [];
+}
+
+/**
+ * A choice parameter's value when none is declared or saved: the option
+ * selectBox selects for it, its first enabled one, `{ group, options }`
+ * entries flattened in order (the first of all when every one is disabled).
+ */
+function firstChoice(spec, subplot) {
+    const flat = flatChoices(choiceOptions(spec, subplot));
+    return (flat.find((o) => !o.disabled) ?? flat[0])?.value;
+}
 
 /** A transform's parameter values: its declared defaults under the subplot's own. */
-function resolveParams(transform, state) {
+function resolveParams(transform, state, subplot) {
+    const saved = state?.params ?? {};
     const params = {};
     for (const [name, spec] of Object.entries(transform.params ?? {})) {
         params[name] = spec?.default;
+        if (isChoice(spec) && spec.default === undefined && saved[name] === undefined) {
+            params[name] = firstChoice(spec, subplot);
+        }
     }
-    return { ...params, ...(state?.params ?? {}) };
+    return { ...params, ...saved };
 }
 
 /** The output names of `transform` that `state` switches on, in declared order. */
@@ -60,23 +117,34 @@ function isEligible(trace) {
  * @param {Object} [options]
  * @param {Function} [options.onError] - `({ transformId, traceName, error })`,
  *        called for each skipped run.
+ * @param {Function} [options.seriesOf] - `(trace) => series | null`: the series
+ *        config a trace was drawn from, passed as `context.series` (null for a
+ *        trace it names none for, and for every trace without it). It does not
+ *        choose the sources: every eligible trace is run on, as before.
+ * @param {Object} [options.results] - The results the figure was drawn from
+ *        (`context.results`).
+ * @param {Function} [options.resolveSeries] - The resolver the figure was drawn
+ *        with (`context.resolveSeries`).
  * @returns {Promise<Object[]>} The extra traces, in transform then trace order.
  */
-async function deriveSeriesTraces(traces, subplot, seriesTransforms, { onError } = {}) {
+async function deriveSeriesTraces(traces, subplot, seriesTransforms,
+                                  { onError, seriesOf, results, resolveSeries } = {}) {
     const derived = [];
     if (!seriesTransforms) return derived;
-    const sources = traces.filter(isEligible);
+    const sources = traces.filter(isEligible)
+        .map((trace) => ({ trace, series: typeof seriesOf === 'function' ? (seriesOf(trace) ?? null) : null }));
 
     for (const [transformId, transform] of Object.entries(seriesTransforms)) {
         const state = subplot?.transforms?.[transformId];
         const outputs = enabledOutputs(transform, state);
         if (!outputs.length || typeof transform?.run !== 'function') continue;
-        const params = resolveParams(transform, state);
+        const params = resolveParams(transform, state, subplot);
 
-        for (const source of sources) {
+        for (const { trace: source, series } of sources) {
+            const context = { series, subplot, results: results ?? null, resolveSeries: resolveSeries ?? null };
             let result;
             try {
-                result = await transform.run(source.y, params);
+                result = await transform.run(source.y, params, context);
             } catch (error) {
                 onError?.({ transformId, traceName: source.name, error });
                 continue;
@@ -112,7 +180,8 @@ async function deriveSeriesTraces(traces, subplot, seriesTransforms, { onError }
 
 /**
  * The controls for `seriesTransforms` in a subplot's config: per transform, a
- * toggle for each output and a number field for each parameter. They edit
+ * toggle for each output and, for each parameter, a number field or, for a
+ * `type: 'choice'` parameter, a select (choice_controls' selectBox). They edit
  * `subplot.transforms` in place and call `onChange()` after every edit. With no
  * transforms (null or `{}`) nothing is rendered.
  *
@@ -173,22 +242,47 @@ function renderSeriesTransformControls(container, subplot, seriesTransforms, { o
             row.className = 'twm-series-transforms__row';
             const text = document.createElement('span');
             text.textContent = spec?.label ?? name;
+            const writeParam = (value) => {
+                const state = stateOf(transformId);
+                const params = { ...(state.params ?? {}) };
+                if (value === undefined) delete params[name];
+                else params[name] = value;
+                state.params = params;
+                onChange?.();
+            };
+            const saved = subplot.transforms?.[transformId]?.params?.[name];
+
+            if (isChoice(spec)) {
+                const current = saved ?? spec.default ?? firstChoice(spec, subplot);
+                const choice = selectBox(choiceOptions(spec, subplot), current, {
+                    label: spec?.label ?? name,
+                    valueAttr: 'value',
+                    className: 'twm-series-transforms__param twm-series-transforms__select',
+                });
+                choice.box.addEventListener('change', () => {
+                    const value = choice.valueOf();
+                    // Redrawn with the chosen value, as settings do: a stale
+                    // '(not found)' entry goes once an offered option is picked.
+                    choice.setOptions(choiceOptions(spec, subplot), value);
+                    writeParam(value);
+                });
+                paramInputs.push(choice.box);
+                row.append(text, choice.box);
+                group.appendChild(row);
+                continue;
+            }
+
             const input = document.createElement('input');
             input.type = 'number';
             input.className = 'twm-series-transforms__param';
             for (const attr of ['min', 'max', 'step']) {
                 if (spec?.[attr] != null) input[attr] = String(spec[attr]);
             }
-            const current = subplot.transforms?.[transformId]?.params?.[name] ?? spec?.default;
+            const current = saved ?? spec?.default;
             input.value = current == null ? '' : String(current);
             input.addEventListener('change', () => {
                 const value = parseFloat(input.value);
-                const state = stateOf(transformId);
-                const params = { ...(state.params ?? {}) };
-                if (Number.isFinite(value)) params[name] = value;
-                else delete params[name];
-                state.params = params;
-                onChange?.();
+                writeParam(Number.isFinite(value) ? value : undefined);
             });
             paramInputs.push(input);
             row.append(text, input);