flexdesk 0.17.11 → 0.17.12

package/dist/tiles.js

@@ -36,7 +36,7 @@ import {
   purge,
   resize,
   strideDownsampleShared
-} from "./chunk-2YTM3GJE.js";
+} from "./chunk-75FLVAUT.js";
 import "./chunk-NIJEJAZ7.js";
 import {
   isHexColor

package/docs/components/charts.md

@@ -4,6 +4,40 @@
 
 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).
 
+## An empty cell can name what is missing: `emptyMessage` as a function (0.17.12)
+
+[`renderPlotGrid`](#a-plot-config-in-any-container-renderplotgrid-0170),
+`PlotPopoutWindow` and `openPlotPopoutWindow` take `emptyMessage` as a string,
+as before, or as a function of the subplot:
+
+```js
+const grid = renderPlotGrid(el, plotConfig, results, {
+    emptyMessage: (subplot, results, index) => {
+        const name = subplot.yAxes[0].series[0]?.variable;
+        return results ? `${name} not in this run` : 'No data yet.';
+    },
+});
+await grid.update({ results: next });   // the empty cells say what is missing in `next`
+```
+
+The function is called each time a cell is drawn empty, with that cell's
+subplot, the grid's results at that moment (as the grid was given them, so null or undefined when there are none) and the
+cell's index in the layout: on the first draw, on every `update()` (new
+`results`, a new `plotConfig`, `overlays` or `hiddenSeries`), on a resize that
+draws a deferred cell, and when a subplot fails to draw. So the message follows
+results that stream in or change, without disposing and rebuilding the grid. A
+slot with no subplot still shows `noSubplotMessage`.
+
+The plot window hands its `emptyMessage` to its grid, so the function is called
+on the window's own redraws too: its refresh and stream events and
+`updateConfig()`. `openPlotPopoutWindow` forwards it with its other options.
+The Data tab's `tableEmptyMessage` stays a string.
+
+A string `emptyMessage` is shown exactly as before, and no option or export
+changed.
+
+`tests/plot_grid.test.mjs` §8 pins it.
+
 ## Interpolation `'auto'` is a listed choice (0.17.9)
 
 A subplot's `interpolation` is `'linear'`, `'step'`, `'cubic'` or `'auto'`.
@@ -197,7 +231,9 @@ subplot: its chart type, interpolation, data points and stack groups, every
 y-axis (left or right, linear or log, min, max, step), reference lines and
 shaded bands, the NaN strategy, the x-axis clipped to the results' time
 range, or an x variable instead of time (`xAxis: { useTime: false, variable }`).
-A subplot with nothing to draw shows `emptyMessage` (default `No data yet.`); a
+A subplot with nothing to draw shows `emptyMessage` (default `No data yet.`;
+[a function of the subplot](#an-empty-cell-can-name-what-is-missing-emptymessage-as-a-function-01712)
+since 0.17.12); a
 slot with no subplot shows `noSubplotMessage` (`No subplot configured.`); null
 results empty every subplot. A cell that is detached or has no size is not
 drawn: the grid's own ResizeObserver draws it once it has one. `dispose()`

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flexdesk",
-    "version": "0.17.11",
+    "version": "0.17.12",
     "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

@@ -72,6 +72,16 @@ function resolveSeriesData(series, results) {
     return series._resultTime ? { y, x: series._resultTime } : { y };
 }
 
+/**
+ * The text of an empty cell: `message` itself when it is a string, else what
+ * the function `message(subplot, results, index)` returns. PlotPopoutWindow
+ * hands its `emptyMessage` to the grid unchanged, so this is the one place the
+ * two forms are told apart.
+ */
+function emptyMessageFor(message, subplot, results, index) {
+    return typeof message === 'function' ? message(subplot, results, index) : message;
+}
+
 /**
  * Draw `plotConfig` into `container`.
  *
@@ -95,7 +105,10 @@ function resolveSeriesData(series, results) {
  * @param {Object} [options.theme] - Overrides for PLOT_GRID_THEME.
  * @param {boolean} [options.alwaysShowLegend=false] - Draw a 'hidden' legend at the top.
  * @param {Object} [options.layout] - Plotly layout fields merged over every figure's.
- * @param {string} [options.emptyMessage='No data yet.']
+ * @param {string|Function} [options.emptyMessage='No data yet.'] - What a subplot
+ *        with nothing to draw says: a string, or `(subplot, results, index) => string`,
+ *        called each time a cell is drawn empty (first draw, every `update()`, a
+ *        failed draw) with the grid's results at that moment (as the grid was given them, so null or undefined when there are none).
  * @param {string} [options.noSubplotMessage='No subplot configured.']
  * @param {Function} [options.onError] - `({ index, error })` when drawing a subplot
  *        throws — on an update or on a resize that draws a deferred one; that
@@ -170,6 +183,11 @@ function renderPlotGrid(container, plotConfig, results, options = {}) {
         deferred.clear();
     }
 
+    /** Show the empty message in cell `index`, for its subplot and the current results. */
+    function showEmpty(cell, index) {
+        showMessage(cell, emptyMessageFor(opts.emptyMessage, config?.subplots?.[index] ?? null, data, index));
+    }
+
     function showMessage(cell, text) {
         purgeCell(cell);
         const msg = document.createElement('div');
@@ -348,7 +366,7 @@ function renderPlotGrid(container, plotConfig, results, options = {}) {
 
         const figure = await buildFigure(sp, index);
         if (!current()) return false;
-        if (!figure) { showMessage(cell, opts.emptyMessage); deferred.delete(index); return false; }
+        if (!figure) { showEmpty(cell, index); deferred.delete(index); return false; }
 
         if (!hasSize(cell)) { deferred.add(index); return false; }
         deferred.delete(index);
@@ -381,7 +399,7 @@ function renderPlotGrid(container, plotConfig, results, options = {}) {
             if (disposed) return false;
             if (cells[index] === cell && tokens[index] === token) {
                 deferred.delete(index);
-                showMessage(cell, opts.emptyMessage);
+                showEmpty(cell, index);
             }
             opts.onError?.({ index, error });
             return false;

package/src/charts/plot_popout_window.js

@@ -62,6 +62,11 @@ export class PlotPopoutWindow {
      *        updates through `refreshEvent` and explicit calls only.
      * @param {Function} [options.resolveSeries] - `(series, results, subplot) => { y, x? } | null`
      *        (plot_grid.js); used by the chart and the data table. Default resolveSeriesData.
+     * @param {string|Function} [options.emptyMessage='No data yet.'] - What a chart
+     *        cell with nothing to draw says: a string, or `(subplot, results, index) =>
+     *        string`, called on every redraw that leaves the cell empty (renderPlotGrid).
+     * @param {string} [options.tableEmptyMessage='No data yet.'] - What the Data tab
+     *        says with no rows.
      */
     constructor({ id, title, plotConfig, getResults, services, host, onClose, actuals,
                   configRenderer, seriesTransforms, resolveSeries = resolveSeriesData,
@@ -1010,6 +1015,8 @@ const _openWindows = new Map();
  * @param {Function} options.getResults - Returns { time: number[], series: { [key]: number[] } }
  * @param {Object} options.services - { eventBus, logger }
  * @param {Object} [options.actuals] - ETL overlay data
+ * @param {string|Function} [options.emptyMessage] - As PlotPopoutWindow's: a string
+ *        or `(subplot, results, index) => string`. Every option is forwarded.
  * @returns {PlotPopoutWindow}
  */
 export async function openPlotPopoutWindow(options) {