flexdesk 0.17.14 → 0.17.16

package/src/charts/plot_config_editor.js

@@ -11,8 +11,9 @@
  * It draws a layout picker, a tab per subplot slot (when the layout has more
  * than one) and, for the subplot in front: its title; its chart type, legend,
  * interpolation, NaN handling and data points; its x axis (time, or a series);
- * its y axes (label, scale, position, min, max, step) and their series (a
- * picker, label, colour, width, dash, stack group, the embedder's own fields
+ * its y axes (label, scale, position, min, max, step) and their series (each a
+ * block: a header line of picker, label and remove over one label column of
+ * colour, width, dash, stack group, the embedder's own fields
  * and, with `overlaySources`, an overlay source); its z axis while the chart
  * type is 3D; its reference lines and shaded bands; and the toggles of any
  * injected `seriesTransforms` (series_transforms.js).
@@ -101,15 +102,37 @@ function removeButton(title, onClick) {
     return b;
 }
 
+let hintCount = 0;
+
 /**
- * A labelled control. A single input or select is wrapped in a `<label>`; a
- * compound one (a picker, a colour field) is not, so a click on its text does
- * not land on whichever of its inputs comes first.
+ * A labelled control on the editor's label column. A single input or select
+ * is wrapped in a `<label>`; a compound one (a picker, a colour field) is not,
+ * so a click on its text does not land on whichever of its inputs comes
+ * first. A `hint` is drawn under the control, in the control's column, and
+ * outside any `<label>`: the row is then a `<div>` whose label text is the
+ * `<label for>` of a single control, and the hint describes the control
+ * (`aria-describedby`) without being part of its name.
  */
-function field(label, control) {
+function field(label, control, { hint = null } = {}) {
     const single = control.matches('input, select, textarea');
-    const row = el(single ? 'label' : 'div', 'twm-plot-config__field');
-    row.append(el('span', 'twm-plot-config__label', label), control);
+    const hinted = hint != null && hint !== '';
+    if (!hinted) {
+        const row = el(single ? 'label' : 'div', 'twm-plot-config__field');
+        row.append(el('span', 'twm-plot-config__label', label), control);
+        return row;
+    }
+    const row = el('div', 'twm-plot-config__field twm-plot-config__field--hinted');
+    const text = el(single ? 'label' : 'span', 'twm-plot-config__label', label);
+    const note = el('span', 'twm-plot-config__hint', hint);
+    note.id = `twm-plot-config-hint-${++hintCount}`;
+    if (single) {
+        if (!control.id) control.id = `${note.id}-control`;
+        text.htmlFor = control.id;
+    }
+    const target = single ? control : (control.querySelector('input, select, textarea') ?? control);
+    const describedBy = target.getAttribute('aria-describedby');
+    target.setAttribute('aria-describedby', describedBy ? `${describedBy} ${note.id}` : note.id);
+    row.append(text, control, note);
     return row;
 }
 
@@ -170,8 +193,13 @@ let editorCount = 0;
  *        source, written to `series.overlay.source`. Absent: no overlay controls.
  * @param {Object} [options.seriesTransforms] - `{ [id]: transform }` (series_transforms.js);
  *        their toggles are drawn per subplot.
- * @param {Function} [options.extraSeriesFields] - `(el, series, { subplot, axis, onChange })
- *        => { dispose? } | void`: fields of the embedder's own in each series row.
+ * @param {Function} [options.extraSeriesFields] - `(el, series, { subplot, axis, onChange, field })
+ *        => { dispose? } | specs[] | void`: fields of the embedder's own in each series
+ *        block, on the series' label column. It may draw into `el` (with
+ *        `field(label, control, { hint })` for rows that line up) and return a handle,
+ *        or return an ARRAY of field specs `{ label: string, control: HTMLElement,
+ *        hint? }` / `{ label: string, render(slot) => { dispose? } | void, hint? }`,
+ *        laid out after anything drawn into `el`. A bad spec is skipped with a warning.
  * @param {Object} [options.logger] - Given to every AutocompleteField (provider errors);
  *   its `warn` also hears a part (an `extraSeriesFields` handle, say) that throws on dispose.
  * @returns {{ dispose: Function, refresh: Function, selectSubplot: Function,
@@ -309,13 +337,14 @@ function renderPlotConfigEditor(container, config, options = {}) {
         return node;
     }
 
-    function colorField(value, onSet, label) {
+    /** `keep` takes its teardown: the body's (track), or a narrower redraw's. */
+    function colorField(value, onSet, label, keep = track) {
         const f = new ColorField({
             value: value ?? '',
             label,
             onChange: (v) => { if (v !== null) { onSet(v || null); notify(); } },
         });
-        track(() => f.dispose());
+        keep(() => f.dispose());
         return f.render();
     }
 
@@ -489,18 +518,17 @@ function renderPlotConfigEditor(container, config, options = {}) {
         return group;
     }
 
+    /**
+     * One series as a block: a header line (series picker, legend label,
+     * remove) over its fields on the editor's label column (colour, width,
+     * dash, stack group, the embedder's fields, overlay).
+     */
     function seriesRow(sp, axis, s, overlaySources) {
         const row = el('div', 'twm-plot-config__series');
-        const main = el('div', 'twm-plot-config__series-main');
-        main.append(
+        const head = el('div', 'twm-plot-config__series-head');
+        head.append(
             seriesPicker(s, 'variable', 'series', sp, 'Series'),
             textInput(s.label, (v) => { s.label = v; notify(); }, { placeholder: 'Legend label', label: 'Legend label' }),
-            colorField(s.color, (v) => { if (v) s.color = v; else delete s.color; }, 'Colour'),
-            numberInput(s.lineWidth ?? 2, (v) => { s.lineWidth = v ?? 2; notify(); },
-                        { placeholder: '2', label: 'Line width', min: 1, max: 10, step: 1 }),
-            select(DASHES, s.lineStyle ?? 'solid', (v) => { s.lineStyle = v; notify(); }, { label: 'Dash' }),
-            textInput(s.stackGroup, (v) => { s.stackGroup = v || null; notify(); },
-                      { placeholder: 'Stack group', label: 'Stack group' }),
             removeButton('Remove series', () => {
                 const i = axis.series.indexOf(s);
                 if (i >= 0) axis.series.splice(i, 1);
@@ -508,32 +536,100 @@ function renderPlotConfigEditor(container, config, options = {}) {
                 notify();
             }),
         );
-        row.appendChild(main);
 
-        if (opts.extraSeriesFields) {
-            const extra = el('div', 'twm-plot-config__series-extra');
-            row.appendChild(extra);
-            const handle = opts.extraSeriesFields(extra, s, { subplot: sp, axis, onChange: notify });
-            if (typeof handle?.dispose === 'function') track(() => handle.dispose());
-        }
-        if (opts.overlaySources) row.appendChild(overlayEditor(s, overlaySources));
+        const fields = el('div', 'twm-plot-config__series-fields');
+        fields.append(
+            field('Colour', colorField(s.color, (v) => { if (v) s.color = v; else delete s.color; }, 'Colour')),
+            field('Width', numberInput(s.lineWidth ?? 2, (v) => { s.lineWidth = v ?? 2; notify(); },
+                                       { placeholder: '2', label: 'Line width', min: 1, max: 10, step: 1 })),
+            field('Dash', select(DASHES, s.lineStyle ?? 'solid', (v) => { s.lineStyle = v; notify(); }, { label: 'Dash' })),
+            field('Stack group', textInput(s.stackGroup, (v) => { s.stackGroup = v || null; notify(); },
+                                           { placeholder: 'None', label: 'Stack group' })),
+        );
+        if (opts.extraSeriesFields) fields.appendChild(extraFields(sp, axis, s));
+        if (opts.overlaySources) fields.appendChild(overlayEditor(s, overlaySources));
+        row.append(head, fields);
         return row;
     }
 
+    const warn = (...args) => (opts.logger?.warn ? opts.logger.warn(...args) : console.warn(...args));
+
+    /**
+     * The embedder's fields of a series: whatever `extraSeriesFields` draws
+     * into the box (which sits in the series' field column), then, when it
+     * returns an ARRAY, those field specs laid out by `field()`. Anything
+     * else it returns is a handle, disposed when the row goes (`{ dispose }`).
+     * A spec that is not `{ label, control: Element }` or
+     * `{ label, render(slot) }` is skipped with a warning, as is a `render`
+     * that throws: one bad field never leaves half a body.
+     */
+    function extraFields(sp, axis, s) {
+        const extra = el('div', 'twm-plot-config__series-extra');
+        const result = opts.extraSeriesFields(extra, s, { subplot: sp, axis, onChange: notify, field });
+        if (!Array.isArray(result)) {
+            if (typeof result?.dispose === 'function') track(() => result.dispose());
+            return extra;
+        }
+        for (const spec of result) {
+            const label = spec?.label;
+            let control = null;
+            if (typeof label !== 'string') {
+                warn('[plot config editor] an extraSeriesFields spec has no label; skipped', spec);
+                continue;
+            }
+            if (spec.control != null) {
+                if (!(spec.control instanceof Element)) {
+                    warn('[plot config editor] an extraSeriesFields spec control is not an Element; skipped', spec);
+                    continue;
+                }
+                control = spec.control;
+            } else if (typeof spec.render === 'function') {
+                control = el('div', 'twm-plot-config__slot');
+                try {
+                    const handle = spec.render(control);
+                    if (typeof handle?.dispose === 'function') track(() => handle.dispose());
+                } catch (error) {
+                    warn('[plot config editor] an extraSeriesFields spec failed to render; skipped', error);
+                    continue;
+                }
+            } else {
+                warn('[plot config editor] an extraSeriesFields spec has neither control nor render; skipped', spec);
+                continue;
+            }
+            extra.appendChild(field(label, control, { hint: spec.hint }));
+        }
+        return extra;
+    }
+
     function overlayEditor(s, overlaySources) {
         const wrap = el('div', 'twm-plot-config__overlay');
         const head = el('div', 'twm-plot-config__overlay-source', 'Loading overlay sources…');
         const details = el('div', 'twm-plot-config__overlay-fields');
         wrap.append(head, details);
 
+        // The details' colour field is torn down on each redraw of the
+        // details, not left for the body's next redraw.
+        let detailDisposers = [];
+        const disposeDetails = () => {
+            const fns = detailDisposers;
+            detailDisposers = [];
+            for (const fn of fns) {
+                try { fn(); } catch (error) {
+                    opts.logger?.warn?.('[plot config editor] a field failed to dispose', error);
+                }
+            }
+        };
+        track(disposeDetails);
+        const keep = (fn) => { detailDisposers.push(fn); };
         const drawDetails = () => {
+            disposeDetails();
             details.replaceChildren();
             const ov = s.overlay;
             if (!ov) return;
             details.append(
                 field('Label', textInput(ov.label, (v) => { ov.label = v; notify(); },
                                          { placeholder: `${s.label || s.variable || 'Series'} (actual)` })),
-                field('Colour', colorField(ov.color, (v) => { if (v) ov.color = v; else delete ov.color; }, 'Overlay colour')),
+                field('Colour', colorField(ov.color, (v) => { if (v) ov.color = v; else delete ov.color; }, 'Overlay colour', keep)),
                 field('Dash', select(DASHES, ov.lineStyle ?? 'dashed', (v) => { ov.lineStyle = v; notify(); })),
                 field('Width', numberInput(ov.lineWidth ?? 2, (v) => { ov.lineWidth = v ?? 2; notify(); },
                                            { placeholder: '2', min: 1, max: 10, step: 1 })),

package/src/tiles/tile_base.js

@@ -47,10 +47,13 @@ export class TileBase {
      * @param {{resolve: Function}} [options.dataSource] - Where this tile asks for its
      *        own rows. Handed down by `TileGrid`; absent for a grid whose data is
      *        broadcast with `setData()`, and then nothing ever calls `loadData()`.
+     * @param {boolean} [options.configOnDoubleClick=true] - A double-click on the
+     *        title strip (not on its buttons or an editable field in it) does what
+     *        the cogwheel does. False leaves the cogwheel as the only way in.
      */
     constructor({ id, grid, eventBus = null, config = {}, readonly = false,
                   headless = false, host = null, stateGuard = null,
-                  dataSource = null }) {
+                  dataSource = null, configOnDoubleClick = true }) {
         this.host = host;
         // THE TILE PULLS; THE GRID DOES NOT PUSH.
         //
@@ -74,6 +77,9 @@ export class TileBase {
         this.config = { ...this.getDefaultConfig(), ...config };
         this.readonly = readonly;
         this.headless = headless;
+        this.configOnDoubleClick = configOnDoubleClick;
+        /** STORY-0128. See `setConfiguring`. */
+        this._configuring = false;
         this.element = null;
         this.contentElement = null;
         this.chartInstance = null;
@@ -288,7 +294,8 @@ export class TileBase {
         if (this._disposed) return;
 
         this.element = document.createElement('div');
-        this.element.className = `tile${this.readonly ? ' tile--readonly' : ''}`;
+        this.element.className = `tile${this.readonly ? ' tile--readonly' : ''}`
+            + `${this._configuring ? ' tile--configuring' : ''}`;
 
         // Use StateGuard bypass if available to set dataset properties
         const stateGuard = this.stateGuard;
@@ -595,6 +602,17 @@ export class TileBase {
                 this._onConfigClick();
             });
 
+            // STORY-0128. The title strip's double-click is a second door to
+            // the cogwheel, through the same `_onConfigClick`. Not on a button
+            // in the strip (each has its own verb) and not on an editable
+            // field, where a double-click selects a word.
+            header.addEventListener('dblclick', (e) => {
+                if (!this.configOnDoubleClick || !configBtn) return;
+                if (e.target.closest?.('button, input, textarea, select, [contenteditable=""], [contenteditable="true"], .tile-menu-dropdown')) return;
+                e.stopPropagation();
+                this._onConfigClick();
+            });
+
             // "..." menu button + dropdown
             const menuBtn = header.querySelector('.tile-menu-btn');
             const menuDropdown = header.querySelector('.tile-menu-dropdown');
@@ -705,6 +723,34 @@ export class TileBase {
         if (this._menuHome && menu.parentNode !== this._menuHome) this._menuHome.appendChild(menu);
     }
 
+    /**
+     * Mark this tile as being configured, or clear the mark (STORY-0128).
+     * A convenience for `grid.setConfiguring(tile.id, on)`, which is the API:
+     * the grid holds the mark by tile id, so it outlives this tile instance
+     * (`setLayout` disposes and rebuilds every tile). A tile with no grid
+     * holds the mark itself.
+     *
+     * @param {boolean} [on=true]
+     */
+    setConfiguring(on = true) {
+        if (typeof this.grid?.setConfiguring === 'function') {
+            this.grid.setConfiguring(this.id, on);
+            return;
+        }
+        this._applyConfiguring(on);
+    }
+
+    /** Draw (or clear) the configuring mark. Called by the grid.
+     *  @param {boolean} on
+     *  @private */
+    _applyConfiguring(on) {
+        this._configuring = !!on;
+        this.element?.classList.toggle('tile--configuring', this._configuring);
+    }
+
+    /** True while this tile is marked as being configured. */
+    get isConfiguring() { return this._configuring; }
+
     /**
      * Handle config button click — highlight tile and emit config request.
      * @private

package/src/tiles/tile_grid.js

@@ -27,6 +27,8 @@ export class TileGrid {
      * @param {*} [options.scope=null] - The board's scope, a filter every tile
      *        follows (0.16.1); see `setScope`.
      * @param {Function} [options.onScopeChange] - `(scope)` after `setScope` changed it.
+     * @param {boolean} [options.configOnDoubleClick=true] - Whether a double-click
+     *        on a tile's title strip opens its config, as its cogwheel does (0.17.16).
      */
     constructor({ container, columns = 12, rowHeight = 80, gap = 16, eventBus = null,
                   showToolbar = true, readonly = false, onLayoutChange, onBeforeLayoutChange,
@@ -38,12 +40,19 @@ export class TileGrid {
                   host = null, stateGuard = null,
                   // Injected, never constructed here: the grid does not know what
                   // a binding is, only that a tile may have somewhere to ask.
-                  dataSource = null, scope = null, onScopeChange = null }) {
+                  dataSource = null, scope = null, onScopeChange = null,
+                  // STORY-0128. Handed to every tile: false turns off the
+                  // title strip's double-click to configure.
+                  configOnDoubleClick = true }) {
         this.host = host;
         this.scope = scope;
         this._onScopeChangeCallback = onScopeChange;
         this.stateGuard = stateGuard;
         this.dataSource = dataSource;
+        this.configOnDoubleClick = configOnDoubleClick;
+        /** STORY-0128. Ids of the tiles marked as being configured; see
+         *  `setConfiguring`. Kept by id so a rebuilt tile is marked again. */
+        this._configuringIds = new Set();
         this.container = container;
         this.columns = columns;
         this.rowHeight = rowHeight;
@@ -194,11 +203,14 @@ export class TileGrid {
             host: this.host,
             stateGuard: this.stateGuard,
             dataSource: this.dataSource,
+            configOnDoubleClick: this.configOnDoubleClick,
         });
 
         if (!tile) return null;
         // Before mount, so a tile's first render and first load already follow it.
         tile.scope = this.scope;
+        // STORY-0128. A tile rebuilt under a marked id (setLayout) is marked.
+        if (this._configuringIds.has(tileId)) tile._applyConfiguring(true);
 
         // Add to layout
         const layoutEntry = {
@@ -340,6 +352,35 @@ export class TileGrid {
         }));
     }
 
+    /**
+     * Mark a tile as being configured, or clear the mark (STORY-0128).
+     *
+     * A config request (cogwheel or title double-click) highlights the
+     * requesting tile with `tile--selected` and takes that highlight off every
+     * other tile: one selection per grid. An embedder that keeps a config
+     * window open per tile marks each such tile here instead. The mark
+     * (`tile--configuring`, drawn like the selection) is the embedder's alone:
+     * no config request clears it, and it is held by id, so a tile that
+     * `setLayout` rebuilds (or an id added later) is marked again. Clear it
+     * when that tile's config window closes.
+     *
+     * @param {string} tileId
+     * @param {boolean} [on=true]
+     */
+    setConfiguring(tileId, on = true) {
+        if (on) this._configuringIds.add(tileId);
+        else this._configuringIds.delete(tileId);
+        this.tiles.get(tileId)?._applyConfiguring(!!on);
+    }
+
+    /**
+     * @param {string} tileId
+     * @returns {boolean} Whether the tile is marked as being configured.
+     */
+    isConfiguring(tileId) {
+        return this._configuringIds.has(tileId);
+    }
+
     /**
      * Set layout and rebuild tiles.
      * @param {Array|Object} layout - Layout array or object with tiles property

package/src/tiling/kind_taxonomy.js

@@ -62,6 +62,20 @@
  *               a reason, and keeps the first of any duplicates a restored
  *               layout holds. The root kind cannot be single: every new
  *               pane, tab and desktop is seeded with it.
+ *
+ *   window?     `{ width?, height? }` — the initial size, in px, of a managed
+ *               window this kind opens in (`navigate(…, { dest: 'window' })`,
+ *               or always for `windowOnly`); clamped to the screen and to the
+ *               window's minimum (400 × 300) as any window is. Absent: the
+ *               window's default size (STORY-0127).
+ *   windowOnly? `true`: the kind lives in a managed window, never in a tile
+ *               — a tool, not a page. Every open path (navigate with any
+ *               `dest`, openInPrimary, openInLeaf, the tab and split verbs)
+ *               opens it in a window; its window never docks into a tile
+ *               (no Back to tile, maximise is geometric, no drag-to-dock); a
+ *               restored layout drops a tile tab of it, with one warning, and
+ *               a tab's history entry of it opens a window. Neither the root
+ *               nor a top-nav kind can be window-only (STORY-0127).
  */
 
 import { PANEL_OFFERED, PANEL_SIDES, readPanelOffer } from './panel_availability.js';
@@ -104,6 +118,26 @@ export function createTaxonomy({ kinds, root } = {}) {
             throw new TypeError(
                 `createTaxonomy: '${kind}'.single must be true or a prop name`);
         }
+        if (def.window != null) {
+            const w = def.window;
+            const bad = (v) => v != null && !(typeof v === 'number' && Number.isFinite(v) && v > 0);
+            if (typeof w !== 'object' || Array.isArray(w) || bad(w.width) || bad(w.height)) {
+                throw new TypeError(
+                    `createTaxonomy: '${kind}'.window must be { width?, height? } in positive px`);
+            }
+        }
+        if (def.windowOnly != null && typeof def.windowOnly !== 'boolean') {
+            throw new TypeError(`createTaxonomy: '${kind}'.windowOnly must be true or false`);
+        }
+        if (def.windowOnly && def.isTopNav) {
+            throw new Error(
+                `createTaxonomy: '${kind}' is a top-nav page and cannot be windowOnly — a page lives in tiles`);
+        }
+    }
+    if (kinds[root].windowOnly) {
+        throw new Error(
+            `createTaxonomy: the root kind '${root}' cannot be windowOnly — `
+            + 'every new pane, tab and desktop is seeded with it');
     }
     if (kinds[root].single) {
         throw new Error(
@@ -227,6 +261,15 @@ export function createTaxonomy({ kinds, root } = {}) {
         return `${kind}\u0000${v == null ? '' : String(v)}`;
     };
 
+    /** Whether `kind` lives in a managed window only (KindDef `windowOnly`). */
+    const isWindowOnly = (kind) => _kinds[kind]?.windowOnly === true;
+
+    /** The initial size of a window `kind` opens in (KindDef `window`), or null. */
+    const windowSize = (kind) => {
+        const w = _kinds[kind]?.window;
+        return w ? { width: w.width ?? null, height: w.height ?? null } : null;
+    };
+
     /** The sentence a refused copy verb shows for a single kind. */
     const singleReason = (kind) =>
         `${_kinds[kind]?.label || kind} is open once: use the one that is open`;
@@ -246,5 +289,7 @@ export function createTaxonomy({ kinds, root } = {}) {
         isSingle,
         instanceKey,
         singleReason,
+        isWindowOnly,
+        windowSize,
     });
 }

package/src/tiling/tile_breadcrumb.js

@@ -24,14 +24,19 @@
 /** Build a breadcrumb strip element + render initial state. Returns
  *  `{ el, destroy }`. The strip is wired to the WM (clicks open content
  *  in the primary tile) and, when the embedder supplies a `rootCrumb`
- *  with a `subscribe` hook, to whatever keeps the root label fresh. */
+ *  with a `subscribe` hook, to whatever keeps the root label fresh.
+ *  While the path is a single segment (the tile itself) the strip is
+ *  `hidden` and takes no room; `refresh()` shows it once there are more. */
 export function mountTileBreadcrumb(kind, props, ctx) {
     const eventBus  = ctx?.eventBus;
     const taxonomy  = ctx?.taxonomy;
     const rootCrumb = ctx?.rootCrumb || null;
     if (!taxonomy) {
         console.error('[breadcrumb] no taxonomy in ctx — cannot render');
-        return { el: document.createElement('nav'), destroy: () => {} };
+        const el = document.createElement('nav');
+        el.className = 'twm-topbar-breadcrumb twm-tile-breadcrumb';
+        el.hidden = true;   // nothing to draw: no strip, as for a one-segment path
+        return { el, refresh: () => {}, destroy: () => {} };
     }
     const root = document.createElement('nav');
     root.className = 'twm-topbar-breadcrumb twm-tile-breadcrumb';
@@ -82,9 +87,12 @@ export function mountTileBreadcrumb(kind, props, ctx) {
         try { return ctx.trailSegments() || []; }
         catch (err) { console.warn('[breadcrumb] trailSegments threw', err); return []; }
     };
+    // One segment is the tile itself, which its title already names: the strip
+    // is hidden (and its page-shell slot with it) until there is a level above.
     const render = () => {
-        _renderInto(root,
-            _segments(kind, props, taxonomy, rootCrumb, rootLabel, navigate, trailOf()));
+        const segments = _segments(kind, props, taxonomy, rootCrumb, rootLabel, navigate, trailOf());
+        _renderInto(root, segments);
+        root.hidden = segments.length < 2;
     };
     render();