flexdesk 0.17.15 → 0.17.16

package/docs/README.md

@@ -49,7 +49,7 @@ FlexDesk is nine entry points that share their code, so you load only what you u
 - [Settings page](components/settings-view.md): a settings store's schema drawn as a page.
 - [Wizard](components/wizard.md): a multi-step flow, inline or in a window.
 - [Input fields: slider and tags](components/input-fields.md): `SliderField` and `createTagInput`.
-- [Menus](components/menus.md): `createMenuBar` and `ActionDropdown`.
+- [Menus](components/menus.md): `createMenuBar`, `ActionDropdown` and `CategoryPicker`.
 
 ### Layout, content and feedback
 

package/docs/components/charts.md

@@ -4,6 +4,70 @@
 
 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 plot config series is one block, and an embedder's fields share it (0.17.16)
+
+[`renderPlotConfigEditor`](#editing-a-plot-config-renderplotconfigeditor-0170)
+drew each series as one wrapped line: the series picker, the legend label, the
+colour swatch with a wide hex box, the width, the dash and the stack group,
+then the embedder's `extraSeriesFields` and the overlay select on label
+columns of their own. Each series is now one block:
+
+- **A header line**: the series picker, the legend label and the remove
+  button. It wraps when the window is narrow.
+- **Its fields, one per line, on the editor's label column** (the same 96px
+  column as the subplot's and the axes' fields): **Colour** (a `ColorField`:
+  the swatch and a hex box sized to `#rrggbb`), **Width**, **Dash**,
+  **Stack group**, then the embedder's fields, then **Overlay** (with
+  `overlaySources`). An overlay's own label, colour, dash, width and mode sit
+  under its source, set in by a rule, with their controls still on the
+  series' control column.
+
+It reads at the usual ~600px config window and down to 360px without
+overflowing. The classes are `.twm-plot-config__series-head` and
+`.twm-plot-config__series-fields`; `.twm-plot-config__series-main` is gone.
+
+`extraSeriesFields(el, series, ctx)` can now put its fields on that same
+column, in either of two ways, and the 0.17.0 form keeps working:
+
+```js
+renderPlotConfigEditor(el, plotConfig, {
+    // 1. return field specs: the editor lays them out
+    extraSeriesFields: (el, series, { onChange }) => [
+        { label: 'Scenario', control: scenarioSelect(series, onChange),
+          hint: 'The run this series is read from' },
+        { label: 'Note', render: (slot) => mountMyWidget(slot, series, onChange) },  // may return { dispose }
+    ],
+    // 2. or draw rows with the editor's own helper
+    // extraSeriesFields: (el, series, { onChange, field }) => {
+    //     el.appendChild(field('Scenario', scenarioSelect(series, onChange), { hint: '…' }));
+    // },
+});
+```
+
+- `ctx.field(label, control, { hint })` returns a field line (a `<label>`
+  when the control is a single input, select or textarea). A hint is drawn
+  under the control, outside the label: the line is then a `<div>`, its label
+  text is the `<label for>` of a single control, and the hint is the control's
+  `aria-describedby`, so it describes the control without joining its name.
+- Only an ARRAY return is field specs. A spec is
+  `{ label: string, control: HTMLElement, hint? }` or
+  `{ label: string, render(slot), hint? }`; `render` draws into an empty slot
+  on the field line and may return `{ dispose }`. Specs are laid out after
+  anything drawn into `el`. A spec without a string `label`, with a `control`
+  that is not an Element, with neither `control` nor `render`, or whose
+  `render` throws is skipped with a warning (`logger.warn`, else
+  `console.warn`); the rest of the row is drawn. Any other return is a handle
+  as in 0.17.0 (`{ dispose }`), even one that has a `fields` property.
+- `el` sits in the field column (`display: contents`), so rows appended to it
+  line up with the editor's; content drawn there any other way shows as
+  before. A returned `{ dispose }` is still disposed on every redraw.
+
+The config the editor reads and writes is unchanged: no key was added, renamed
+or defaulted differently, opening a series writes nothing, and each control
+writes its own key only.
+
+`tests/plot_config_editor.test.mjs` §12 pins it.
+
 ## An empty cell can name what is missing: `emptyMessage` as a function (0.17.12)
 
 [`renderPlotGrid`](#a-plot-config-in-any-container-renderplotgrid-0170),
@@ -303,7 +367,7 @@ const editor = renderPlotConfigEditor(el, plotConfig, {
     seriesProvider: ({ value, role, subplot }) => names(value),   // items, or a promise of them
     seriesTransforms,                                       // their toggles, per subplot
     overlaySources: () => mySources(),                      // optional
-    extraSeriesFields: (el, series, { subplot, axis, onChange }) => { /* your fields */ },
+    extraSeriesFields: (el, series, { subplot, axis, onChange, field }) => { /* your fields */ },
 });
 editor.dispose();
 ```
@@ -341,8 +405,11 @@ config it was given and then calls `onChange(config)`.
   dash, width and mode. `renderPlotGrid` draws it from the data you pass under
   the series' id in `overlays`. **None** removes `series.overlay`. Without
   `overlaySources` there are no overlay controls.
-- `extraSeriesFields(el, series, { subplot, axis, onChange })` puts fields of
-  your own in each series row; call `onChange()` after you edit the series. What
+- `extraSeriesFields(el, series, { subplot, axis, onChange, field })` puts fields of
+  your own in each series row; call `onChange()` after you edit the series.
+  Since 0.17.16 they can share the series' label column (`field`, or returned
+  field specs; see
+  [above](#a-plot-config-series-is-one-block-and-an-embedders-fields-share-it-01716)). What
   it returns is disposed (`dispose()`) when the row is redrawn or the editor
   is disposed. A `dispose()` that throws is reported to `logger.warn` and does
   not stop the rest of the editor being disposed.

package/docs/components/forms-and-dialogs.md

@@ -309,3 +309,64 @@ the caller's own DOM.
 
 `tests/confirm_escaping.test.mjs` opens each of them in jsdom with hostile
 names and labels.
+
+## Windows: closing, focus and Esc (0.17.16)
+
+Every dialog above is a `ManagedWindow`, and so is any window you build
+yourself with `new ManagedWindow({ id, title, content, ... })`. Three things
+changed for all of them (BUG-0053):
+
+- **A closed window is gone.** `close()` (once `beforeClose` allows it) runs
+  `onClose`, removes the window from the registry and releases its content,
+  its DOM and every callback it was given. `ManagedWindow.get(id)` then answers
+  `null`, `ManagedWindow.all()` no longer lists it and `win.isClosed` is
+  `true`. A closed window cannot be shown again: `show()` on it warns and does
+  nothing. To reopen, build a new `ManagedWindow` with the same id; it restores
+  the geometry the last one saved under that id. Until 0.17.15 a closed window
+  stayed registered, holding its content and whatever its `onClose` captured,
+  until the same id opened again.
+- **Saved geometry is bounded.** Position and size are still saved per id
+  under `flexdesk.managedWindows.v1` (or your `storageKey`), but only for the
+  50 most recently saved ids; older entries are dropped.
+  `ManagedWindow.configure({ maxSavedWindows })` changes the cap
+  (`DEFAULT_MAX_SAVED_WINDOWS` is 50). Entries saved by an earlier version
+  carry no use stamp: those under the window manager's minted ids
+  (`twm-mw-…`, which never open again) are purged when the entry is read, and
+  the others are stamped in the order they were stored, as older than anything
+  saved since, so your stable ids keep their geometry. A window whose id is
+  minted per opening passes `persistGeometry: false` and neither saves nor
+  restores geometry; the window manager's own windows do. Modal windows never
+  saved geometry and still do not.
+- **Focus moves in and back.** With `focusOnOpen` (default `true`), opening a
+  window focuses the first element of its content that takes focus (a link,
+  button, input, select, textarea, `contenteditable` or `tabindex` element
+  that is not disabled or hidden), or the window itself when there is none.
+  `focusOnOpen: 'window'` always focuses the window itself, for a dialog whose
+  first button must not catch a stray Enter (`showRunProgressDialog` uses it,
+  so Stop is never focused). Closing gives focus back to the element that had
+  it before the window opened, if that element is still in the document and
+  focus is still in the window or nowhere (on `body`); a window closed while
+  the user works elsewhere does not pull focus back. Restoring a minimised
+  window is not an open and moves nothing. A dialog that focuses a field of
+  its own a frame later, as `openForm` and `openConfirm` do, still wins, and
+  `Wizard.openInWindow` renders its first step before it shows the window, so
+  focus lands on the step's first field. Pass `focusOnOpen: false` for a
+  window that must not take focus when it appears; `showComputingWindow`
+  does.
+- **The window itself holds focus.** Every window element has
+  `tabindex="-1"`: never a Tab stop, but a press on its title bar or on empty
+  content moves focus into the window (when it was not there already), so the
+  window's Esc still works after the user clicked it.
+- **Esc closes a non-modal window only from inside it.** Which window an Esc
+  closes:
+  1. a modal window on top, wherever focus is (as before);
+  2. otherwise the window holding focus, modal or not — so a modal under a
+     non-modal window still closes on an Esc from inside it;
+  3. otherwise (focus in no window) the topmost modal.
+  A non-modal window that does not hold focus never closes on Esc, so an Esc
+  meant for an editor beside it is left alone. An Esc something inside the
+  window already handled with `preventDefault()` (an autocomplete closing its
+  list) or one ending an IME composition (`isComposing`) closes nothing. One
+  Esc closes one window, even when the close hands focus to another window.
+
+`tests/managed_window_lifecycle.test.mjs` holds all of these.

package/docs/components/menus.md

@@ -2,7 +2,7 @@
 
 > **Package:** `@flexdesk/widgets` · [All docs](../README.md)
 
-`createMenuBar` draws File / Edit / View menus from one declarative model, with pointer and keyboard behaviour and the WAI-ARIA menubar roles, and plugs into the shell. `ActionDropdown` draws a dropdown of action buttons from a trigger.
+`createMenuBar` draws File / Edit / View menus from one declarative model, with pointer and keyboard behaviour and the WAI-ARIA menubar roles, and plugs into the shell. `ActionDropdown` draws a dropdown of action buttons from a trigger. `CategoryPicker` draws a categorised picker (search, categories, items, a detail pane) from a trigger.
 
 ## Context menus stay inside the window (0.17.9)
 
@@ -188,3 +188,87 @@ its right edge. Either flips to the other edge when the menu would leave the
 window. A tile's ⋯ menu uses `'end'`
 ([Dashboard tiles](tiles.md#the--menu-is-drawn-over-the-page-0179)).
 
+## A categorised picker: `CategoryPicker` (0.17.16)
+
+An `ActionDropdown` is a flat list. When the choices fall into categories and
+each needs a sentence (and perhaps a sample) before it is chosen, use
+`CategoryPicker`: a search field over three columns — the categories (a
+colour dot, the label, the item count), the active category's items (an icon
+and the label), and a detail pane for the highlighted item (its title,
+description, an optional monospace preview and an Add button).
+
+```js
+import { CategoryPicker } from '@flexdesk/widgets';
+
+const picker = new CategoryPicker({
+    trigger: addCellButton,
+    categories: [
+        { id: 'text', label: 'Text', color: 'var(--accent-light)', items: [
+            { id: 'heading', label: 'Heading', badge: 'H',
+              description: 'A section heading; it shapes the outline.',
+              preview: '## Debt dynamics' },
+            { id: 'doc', label: 'Documentation', icon: 'description',
+              description: 'Markdown with LaTeX math.', keywords: ['markdown', 'latex'] },
+        ] },
+        { id: 'functions', label: 'Functions', color: 'var(--color-warning)', items: [
+            { id: 'lag', label: 'Delay / Lag', badge: 'Δt',
+              description: 'The value of an expression some time ago.',
+              preview: 'expected = lag(inflation, 2)', keywords: 'delay history' },
+        ] },
+    ],
+    onSelect: (item, category) => insertCell(category.id, item.id),
+    placeholder: 'Search cells…',   // the search field's placeholder (default 'Search…')
+    addLabel: 'Add cell',            // the detail pane's button (default 'Add')
+    previewLabel: 'Writes',          // a caption over the preview (none by default)
+    align: 'start',                  // or 'end', as ActionDropdown.position takes it
+    label: 'Add a cell',             // the popover's accessible name (default 'Pick')
+});
+// The trigger's click toggles it; or drive it:
+picker.open(); picker.close(); picker.toggle(); picker.position();
+picker.setCategories(next);          // finds the active category and the highlight again by id
+picker.destroy();
+```
+
+An item has `id` and `label`, and optionally `icon` (a Material Symbols
+ligature) or `badge` (a short text drawn as a monospace badge in the
+category's colour), `description`, `preview` (text, shown monospace and
+pre-wrapped) and `keywords` (an array or a string; searched, never shown). A
+category's `color` is any CSS colour; it reaches the rows as
+`--twm-category-picker-color`, and without one the dot and badge are muted.
+`onSelect(item, category)` gets your own objects back.
+
+- **Anchored like ActionDropdown.** It is appended to `body`, placed by
+  `ActionDropdown.position` (`position: fixed`, under the trigger when it fits,
+  flipped above it when it does not, kept 8px inside the window, capped to the
+  room there), and drawn on `--z-over-windows`, over the managed window it
+  opened from. Its columns scroll inside; the popover itself does not. The
+  trigger gets `aria-haspopup="dialog"`, `aria-expanded` and `twm-is-open`.
+- **Search.** Focus is in the search field on open (the query starts empty).
+  Typing filters every category's items by label, description and keywords:
+  each word must appear, case-insensitively. While a query is set the items
+  column is one hit list grouped under the category labels, the counts are hit
+  counts (a category with none is dimmed), and the first hit is highlighted.
+  Clicking a category then jumps to its first hit.
+- **Keyboard.** With no query, Up/Down move within the current column (the
+  categories, or the items) and wrap; Left/Right move between the two. With a
+  query, Up/Down walk the hit list across categories and Left/Right stay the
+  caret's. Enter picks the highlighted item. A printable key typed while a row
+  has focus goes to the search field. Tab and Shift+Tab stay inside: they
+  cycle the search field and Add (when it is enabled), as a modal
+  ManagedWindow's focus trap does. Keys an IME is composing with are left to
+  it. Escape closes the picker and nothing
+  else (it is caught first and stopped, so a ManagedWindow around it stays
+  open). Escape and a pick give focus back to the trigger.
+- **Pointer.** Hovering or clicking an item shows it in the detail pane;
+  double-clicking it, or Add, picks it. A click outside closes the picker.
+  Pressing anywhere inside but the search field keeps focus where it is, so
+  the keyboard keeps working (the preview's text cannot be drag-selected).
+- **Accessibility.** The popover is a named `role="dialog"`. The search field
+  is a combobox whose `aria-activedescendant` is the active category while the
+  categories column is current, else the highlighted item. While a query is
+  set, each category's hits are a `role="group"` named by its header.
+
+The Add button is FlexDesk's `twm-btn twm-btn--primary`; everything else is
+styled from the tokens (`tests/category_picker.test.mjs` checks there is no
+colour literal in its rules, and that base.css and flexdesk.css carry the same
+block).

package/docs/components/shell.md

@@ -170,6 +170,43 @@ a top-level page showed its name twice, in the title bar and in a one-segment
 breadcrumb under it (STORY-0124). `renderBreadcrumb`, which draws segments a
 content routes itself, is unchanged.
 
+## A kind that lives in a window: `windowOnly` and `window` (0.17.16)
+
+A kind can be a tool rather than a page: it opens in a managed window, never in
+a tile, and it can say how big that window is.
+
+```js
+const taxonomy = createTaxonomy({
+    root: 'start',
+    kinds: {
+        start: { label: 'Start', icon: 'apps' },
+        estimation: { label: 'Parameter Estimation', icon: 'tune',
+                      single: true, windowOnly: true, window: { width: 1100, height: 700 } },
+    },
+});
+wm.navigate('estimation');   // a window, whatever `dest` says
+```
+
+- **`window: { width?, height? }`** is the initial size, in px, of a window the
+  kind opens in, by `navigate(…, { dest: 'window' })` or, for a window-only
+  kind, always. ManagedWindow clamps it to the screen and to its minimum
+  (400 × 300), so a smaller size opens at the minimum. Without it a window
+  opens at ManagedWindow's default (600 × 400).
+- **`windowOnly: true`** sends every open path to a window: `navigate` with
+  any `dest`, `openInPrimary`, `openInLeaf`, the tab verbs and
+  `splitLeafWith`, `navigateActiveTab` (crumbs, Backspace) and
+  `openInWindow`. With `single`, opening it again reveals the window that is
+  open. Its window never goes into a tile: it has no *Back to tile*, its
+  maximise button maximises it, and it does not snap onto a tile when dragged.
+  A restored layout that still holds a tab of the kind in a tile (or archived
+  under a page) drops it and warns once, naming the kinds; the rest of the
+  layout stays, and the next open makes a window. An entry of it in a tab's
+  back history (a layout saved before the kind was window-only) opens its
+  window when Backspace reaches it. Neither the root kind nor a top-nav
+  page can be window-only (`createTaxonomy` refuses).
+- `taxonomy.isWindowOnly(kind)` and `taxonomy.windowSize(kind)` answer both
+  (STORY-0127).
+
 ## Buttons that change with the pane: `ctx.setChromeActions` (0.17.0)
 
 A factory may return `chromeActions` — `[{icon, title, onClick}]`, drawn in the

package/docs/components/tiles.md

@@ -233,3 +233,40 @@ Until 0.17.8 the menu was `position: absolute` inside the tile, so in a tile
 narrower than about 220px its left part and its labels were cut off
 (BUG-0043). `tests/tile_menu_unclipped.test.mjs` holds it.
 
+
+## A double-click on the title strip configures the tile (0.17.16)
+
+A double-click on a tile's header (`.tile-header`: its title, its drag grip or
+the strip between them) does what the cogwheel (`.tile-config-btn`) does: it
+calls the same `_onConfigClick`, so the tile is selected and
+`tile:config-request` goes out on the event bus and as a DOM event exactly as
+for a click on the cogwheel. A double-click on one of the strip's buttons
+(cogwheel, ⋯, info, expand, remove) or in an editable field you put in the
+strip (`input`, `textarea`, `select`, `contenteditable`) does not. A read-only
+tile has no cogwheel and opens nothing.
+
+`new TileGrid({ configOnDoubleClick: false })` turns it off for every tile of
+the grid; a tile takes the same option (`tile.configOnDoubleClick`, read at the
+double-click). `tests/tile_title_dblclick_config.test.mjs` holds it.
+
+## Several tiles marked as being configured: `grid.setConfiguring` (0.17.16)
+
+A config request (cogwheel or double-click) highlights the requesting tile with
+`tile--selected` and takes that highlight off every other tile of the grid:
+one selection per grid, which suits one config panel. An embedder that keeps a
+config window open per tile marks each of those tiles on the grid:
+
+```js
+grid.setConfiguring(tileId, true);    // when its config window opens
+grid.setConfiguring(tileId, false);   // when its config window closes
+grid.isConfiguring(tileId);           // true while marked
+```
+
+The mark is the class `tile--configuring`, drawn exactly like `tile--selected`
+(same rules in `flexdesk.css`). It is the embedder's alone: no config request,
+on that tile or another, clears it. The grid holds it **by tile id**, so a tile
+that `setLayout` disposes and rebuilds (or an id added later) is marked again,
+and clearing it after a rebuild reaches the live tile. `tile.setConfiguring(on)`
+and `tile.isConfiguring` remain as conveniences: on a tile in a grid they go
+through the grid. Do not add or remove `tile--selected` from outside; it
+belongs to the config request.

package/package.json

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

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 })),