flexdesk 0.17.6 → 0.17.8

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);