flexdesk 0.17.2 → 0.17.4

package/docs/README.md

@@ -0,0 +1,97 @@
+# FlexDesk documentation
+
+New here? Start with the [quickstart](quickstart.md). The [README](../README.md) is the one-page overview.
+
+- **[Components](#components).** One page per component: what it is, how to use it, and every option.
+- **[Concepts](#concepts).** The ideas the components share: the host port, packages, naming, theming.
+- **[Best practices](best-practices.md).** The rules the reference states, gathered in one place.
+
+## Packages
+
+FlexDesk is nine entry points that share their code, so you load only what you use. [Packages and entry points](concepts/packages-and-entry-points.md) has the sizes and the reasoning.
+
+| Entry | What is in it | Read |
+|---|---|---|
+| `@flexdesk/core` | Event bus, settings store, logging, state machine, state guard | [State guard](concepts/state-guard.md), [Settings page](components/settings-view.md), [Storage keys and names](concepts/domain-neutrality.md#storage-keys-and-names-are-yours-0170) |
+| `@flexdesk/host` | The host port | [Host port](concepts/host-port.md) |
+| `@flexdesk/wm` | Tiling window manager: tabs, splits, desktops, command palette, `createShell()` | [Shell and navigation](components/shell.md) and the three pages after it |
+| `@flexdesk/widgets` | DataTable, forms, menus, tabs, toasts, panels and more | [Tables and records](#tables-and-records), [Forms, inputs and menus](#forms-inputs-and-menus), [Layout, content and feedback](#layout-content-and-feedback) |
+| `@flexdesk/charts` | Plotly wrapper, plot grid and config editor, plot windows | [Charts](components/charts.md) |
+| `@flexdesk/tiles` | Draggable, resizable widget grid and its tiles | [Dashboard tiles](components/tiles.md) |
+| `@flexdesk/editor` | Monaco loader, editor factory, tab bar, search, split panes | [Editor](components/editor.md) |
+| `@flexdesk/canvas` | The canvas kernel: a pannable, zoomable surface, the edge router, a graph layer | [Flow canvas editor](components/flow-canvas-editor.md) |
+| `@flexdesk/flow` | The flow-editor kit and the canvas, outline and lane editors | [Flow editors and the flow kit](components/flow-editors.md) |
+
+## Components
+
+### Window manager
+
+`@flexdesk/wm`
+
+- [Shell and navigation](components/shell.md): `createShell`, kinds, navigating between them, what a pane tells its chrome.
+- [Panels and desktops](components/panels-and-desktops.md): which panels a page offers, panel sizes, `mountNavPanel`, the desktop bar.
+- [Command palette](components/command-palette.md): grouped results, drill-down, disabled rows, prefix-only sources.
+- [Keys, Back and tab layout](components/keymap.md): rebinding the window manager's keys, Back and the breadcrumb, zoom, tab layout.
+
+### Tables and records
+
+`@flexdesk/widgets`
+
+- [DataTable](components/data-table.md): sorting, filtering, paging, rows from a server, row details, CSV export.
+- [DataTable as a grid](components/data-table-grid.md): editable cells, staged edits, fill handle, paste from Excel, column groups, crosstabs.
+- [Record lists and fact sheets](components/record-list-and-fact-table.md): the parts of a page that are not a table of rows.
+
+### Forms, inputs and menus
+
+`@flexdesk/widgets`
+
+- [Forms and dialogs](components/forms-and-dialogs.md): `openForm`, `openConfirm`, and every field type.
+- [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`.
+
+### Layout, content and feedback
+
+`@flexdesk/widgets`
+
+- [Tabs, section stacks and scrollbars](components/layout-widgets.md): `createTabs`, `createSectionStack`, `installAutoScrollbars`.
+- [Slide-out panel](components/slide-out-panel.md): `SlideOutPanel`, an inline panel that slides in over its host.
+- [Markdown and document outline](components/markdown-and-outline.md): `renderMarkdown` and `createDocumentOutline`.
+- [Conversation view](components/conversation.md): a transcript above a composer.
+- [Notifications and progress](components/notifications.md): toasts, history, the alert log, progress bars, lists and phases.
+
+### Charts, editor and dashboards
+
+- [Charts](components/charts.md): `@flexdesk/charts`, on Plotly.
+- [Editor](components/editor.md): `@flexdesk/editor`, on Monaco.
+- [Dashboard tiles](components/tiles.md): `@flexdesk/tiles`, a draggable widget grid.
+
+### Flow editors
+
+`@flexdesk/flow`, `@flexdesk/canvas`
+
+- [Flow editors and the flow kit](components/flow-editors.md): what the three editors share.
+- [Flow canvas editor](components/flow-canvas-editor.md): nodes and lines, and how to build a modeler.
+- [Flow outline editor](components/flow-outline-editor.md): the graph drawn as a list of blocks.
+- [Flow lane editor](components/flow-lane-editor.md): data flows as lanes, left to right.
+
+### Not yet documented
+
+These have no page of their own: `ManagedWindow`, modals, `TreeView`, context menus, tooltips, the help modal, the window taskbar, and `@flexdesk/core`'s event bus, logging service and state machine. Where another page mentions one, it is in passing. Their sources are under `src/ui/components/`, `src/help/` and `src/core/`.
+
+## Concepts
+
+- [Packages and entry points](concepts/packages-and-entry-points.md): the nine entries, what they weigh, and why they are separate.
+- [Host port](concepts/host-port.md): how FlexDesk reaches storage, dialogs and native windows without touching them.
+- [Domain neutrality](concepts/domain-neutrality.md): storage keys, theme names and MIME types are yours; no application globals.
+- [State guard](concepts/state-guard.md): who wrote that `data-*` attribute.
+- [Peer dependencies](concepts/peer-dependencies.md): Plotly and Monaco, and why there is no default path.
+- [Theming and CSS](concepts/styling.md): the three stylesheets and the class-name rules.
+- [Build and packaging](concepts/building-and-packaging.md): why `dist/` is committed, and the `exports` map.
+
+## Writing these docs
+
+- A feature is documented in a section of the page for its component. The section's heading carries the release that introduced it, as in `A menu bar: createMenuBar (0.17.0)`.
+- The [changelog](../CHANGELOG.md) links to those sections by their heading, so **do not rename a heading that has shipped**. If one must change, update the changelog link in the same commit.
+- Some test suites read these pages and assert on specific sections, headings and tables. After editing them, run `node tests/run.mjs`, or the suite for the page you touched. `grep -l "docs/" tests/*.mjs` lists them.

package/docs/best-practices.md

@@ -0,0 +1,45 @@
+# Best practices
+
+The rules the reference pages state, gathered in one place. Each item says what to do and why, and links to the page that explains it.
+
+## Wiring FlexDesk into an application
+
+**1. Describe your domain in the taxonomy, and nowhere else.** Your kinds, their ancestors, which are single-instance and which panels each page offers are all declared once, in `createTaxonomy`. FlexDesk has no ontology of its own, and which panels a page offers is "said once, in the taxonomy". Likewise hand the shell elements, not selectors: the library never guesses at your markup. See [kinds that exist once](components/shell.md#a-kind-that-exists-once-single-0170), [panels a page does not offer](components/panels-and-desktops.md#panels-a-page-does-not-offer-0170) and the [quickstart](quickstart.md#hello-shell).
+
+**2. Start with the smallest host.** Pass `createHost` only the capabilities you have. A capability you leave out is absent and the library degrades instead of throwing: no native window buttons without `window`, a Blob download for CSV without `dialogs`. An in-memory `Map` is a perfectly good `state`, and `NULL_HOST` is a valid host with nothing behind it. See [the host port](concepts/host-port.md#the-host-port).
+
+**3. Load every entry from one copy.** The entries share code through chunks, so importing several does not give you several event buses or several copies of a module-level singleton. Keep it that way: map all entries to the same install or the same import map, rather than mixing a vendored `dist/` with a second bundled copy. See [packages and entry points](concepts/packages-and-entry-points.md#nine-entry-points).
+
+**4. Name your storage before anything reads it.** Every key FlexDesk writes is an option, with a generic default. Set them at boot, before the first read. Tile layouts are the sharp edge: the store is a singleton, and one built before you supply your key uses the default, so every layout your users saved becomes silently invisible, with no error. If users already have data under older keys, pass those keys explicitly and nothing is lost. See [storage keys and names](concepts/domain-neutrality.md#storage-keys-and-names-are-yours-0170) and [layouts are keyed by whatever you key them by](components/tiles.md#layouts-are-keyed-by-whatever-you-key-them-by).
+
+**5. Set the peer-dependency paths yourself, and show the failure.** Plotly and Monaco are not bundled and their locations are not guessed. `initMonaco()` and `getEditorFactory()` reject when no path is set or loading fails, so catch that and show a message instead of waiting for an editor that never appears. A failure in Monaco's own loader is final for the page: fix the path and reload. If your page already loads Plotly, you can skip `setPlotlySource`. See [peer dependencies](concepts/peer-dependencies.md#peer-dependencies).
+
+**6. Adopt new options one at a time.** Options are opt-in across the library. Most sections of the reference say what a component that sets none of the options does, and the answer is that it behaves as it did in the previous release. Turn a feature on where you need it and leave the rest alone.
+
+## Building screens
+
+**7. Give a table values, not formatted text.** Pass `rows` as values and declare `columnTypes` (`'date'`, `'datetime'`, `'duration'`) so sorting and filtering work on the value, then format for display with `dateFormat`, `durationFormat` and `nullDisplay`. See [DataTable options in 0.5.0](components/data-table.md#datatable-options-in-050-lists-that-need-no-help).
+
+**8. Set house rules once.** `DataTable.withDefaults({ … })` returns a subclass whose defaults sit under every config it is given, so each list is one `mount` call.
+
+**9. Say how long a table lives.** `autoDispose: true` disposes a table that has left the document, which suits lists you rebuild. Do not set it on a table you detach and attach again later, such as a cached tab: a disposed table comes back empty. For that case add `keepWhileDetached`. See [DataTable options in 0.5.0](components/data-table.md#datatable-options-in-050-lists-that-need-no-help) and [0.7.0](components/data-table.md#datatable-options-in-070-details-rows-from-a-server-and-filters-that-are-not-text).
+
+**10. Let the server be the server.** For large or live data, use `dataSource` instead of fetching and slicing in your code, and give the table a `getRowKey`: without it a row's index is only its place in the page drawn, so an open detail survives a new answer only where the same row sits at the same place. Only the newest answer is drawn. When a filter of your own, outside the table, changes, call `reload()`. See [paging](components/data-table.md#a-servers-rows-in-pages-or-as-one-list-paging) and [dataSource](components/data-table.md#datatable-options-in-070-details-rows-from-a-server-and-filters-that-are-not-text).
+
+**11. Pass text as text.** A confirm's message and labels, and a progress bar's names and labels, are set as text, so `<` shows as `<`. Do not build HTML strings for them. See [confirms](components/forms-and-dialogs.md#confirms-show-text-not-markup-0170) and [progress](components/notifications.md#progress-bars-lists-and-phases-0170).
+
+**12. Leave a key to the component that handled it.** The keymap skips any keydown that is already `defaultPrevented`. A list that deletes a row on Backspace calls `preventDefault()`, and the window manager does not also navigate back. To take a chord away from the window manager altogether, set it to `false` in `keymap.bindings`. See [keys](components/keymap.md#your-keys-not-the-window-managers-keymap-0170).
+
+**13. Keep I/O out of the editors.** The flow editors never fetch, never save and never start a timer that writes. Step types, reference grammar, findings and all I/O are yours, passed in as options and returned through callbacks. See [flow editors](components/flow-editors.md#flow-editors).
+
+## Looking right, staying right
+
+**14. Restyle through the tokens.** Every rule reads its values from `tokens.css`, so swapping that one file restyles the shell. Library classes are `twm-` prefixed, and that prefix is stable; the editor components and the help modal keep the class names they were extracted with. Supply the icon font, or accept that icons show their text names. See [theming and CSS](concepts/styling.md#styling).
+
+**15. Run the state guard strictly in your own code.** `StateGuardService` defaults to `mode: 'warn'`. FlexDesk's own widgets run clean under `'strict'`, so choose strict for your code and add your application's keys on top of `DEFAULT_STATE_GUARD_CONFIG`. See [state guard](concepts/state-guard.md#the-state-guard-who-wrote-that-attribute-0170) and [the default allow-list](concepts/state-guard.md#the-defaults-cover-flexdesks-own-keys-0170).
+
+**16. Dispose what you create.** `shell.dispose()` removes the `?` shortcut and the desktop bar along with the rest of the shell. A `NotificationCenter`'s `dispose()` hands the toast helpers back. Menu bars, tables and lists have `dispose()` too.
+
+## One page, browser and native window
+
+**17. Call the native helpers unconditionally.** The same app runs in a browser tab, a native window with the OS frame, and a native window with its own chrome, and the page needs no switch. `routeExternalLinks({ host })` is a no-op without `host.shell`. `WindowChromeController` asks `host.window.chrome()` and draws handles and buttons only for a custom frame. `suppressNativeContextMenu()` leaves the native menu in editable and selected text. See [links out](concepts/host-port.md#links-out-and-the-browsers-right-click-menu-0160) and [a window with its own chrome](concepts/host-port.md#a-window-with-its-own-chrome-0150).

package/docs/components/charts.md

@@ -0,0 +1,211 @@
+# Charts
+
+> **Package:** `@flexdesk/charts` · **Needs:** Plotly, as a [peer dependency](../concepts/peer-dependencies.md) · [All docs](../README.md)
+
+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).
+
+## Derived series: `seriesTransforms` (0.17.0)
+
+A plot can draw series worked out from its own: a trend, a moving average, a
+decomposition. `@flexdesk/charts` ships none; you pass them to
+`PlotPopoutWindow` (or `openPlotPopoutWindow`) as `seriesTransforms`:
+
+```js
+import { openPlotPopoutWindow, renderSeriesTransformControls } from '@flexdesk/charts';
+
+const seriesTransforms = {
+    hp: {
+        label: 'HP filter',
+        params: { lambda: { label: 'Lambda', default: 1600, min: 1, step: 100 } },
+        outputs: {
+            trend: { label: 'Trend', suffix: ' (HP Trend)', lineStyle: 'dashed' },
+            cycle: { label: 'Cycle', suffix: ' (HP Cycle)', lineStyle: 'dotted', lineWidth: 1 },
+        },
+        run: (y, { lambda }) => myBackend.hpFilter(y, lambda),   // -> { trend: [...], cycle: [...] }
+    },
+};
+
+openPlotPopoutWindow({ id, title, plotConfig, getResults, services, seriesTransforms,
+    configRenderer: (el) => renderSeriesTransformControls(el, plotConfig.subplots[0],
+                                                           seriesTransforms, { onChange: redraw }) });
+```
+
+What a subplot switches on is in the subplot:
+`subplot.transforms = { hp: { outputs: { trend: true }, params: { lambda: 100 } } }`.
+For every transform with an output switched on, `run(y, params)` is called
+once per line or scatter trace of the subplot (params: the declared defaults
+under the subplot's own), and each switched-on output it returns is drawn as
+an extra trace in the source trace's colour, on its axis, named
+`<source name><suffix>`, with the output's `lineStyle` and `lineWidth`
+(default 2). A transform that throws or rejects is skipped for that trace,
+reported to `services.logger.warn`, and the figure is drawn without it.
+`deriveSeriesTraces(traces, subplot, seriesTransforms, { onError })` is that
+step on its own, for a renderer of your own.
+
+`renderSeriesTransformControls(container, subplot, seriesTransforms, { onChange })`
+renders, per transform, a toggle for each output and a number field for each
+parameter (disabled while no output is on); it edits `subplot.transforms` in
+place and returns `{ dispose }`. With no transforms it renders nothing.
+
+Until 0.17.0 the plot window called one application's backend for a
+Hodrick-Prescott filter, and every default subplot carried `showHpTrend`,
+`showHpCycle` and `hpLambda`. Those keys are gone and are ignored in saved
+configs; without `seriesTransforms` no derived trace is drawn.
+`tests/series_transforms.test.mjs` pins all of it.
+
+## A plot config in any container: `renderPlotGrid` (0.17.0)
+
+`PlotPopoutWindow` used to keep its subplot renderer private, so anything else
+that showed the same plot config (a notebook cell, a dashboard tile) had to
+copy it. It is now exported, and the window is one of its callers:
+
+```js
+import { renderPlotGrid, migrateData } from '@flexdesk/charts';
+
+const grid = renderPlotGrid(el, migrateData(savedConfig), { time, series }, {
+    overlays,                 // { [series.id]: { years, values } } for series with an `overlay`
+    seriesTransforms,         // as above
+    hiddenSeries: new Set(),  // trace names not to draw
+});
+await grid.update({ results: next });   // any of plotConfig, results, overlays, hiddenSeries
+grid.resize();
+grid.dispose();
+```
+
+It lays a `.twm-plot-grid` out from `PLOT_LAYOUTS` (a cell per slot, a
+`.twm-plot-grid__cell` in that slot's grid area) and draws one figure per
+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
+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()`
+purges every figure and removes the grid; `grid.charts` is the cells, for
+Plotly calls of your own (relayout, toImage), and `grid.plotted` is the cells
+that show a figure right now, however it got there (an `update()`, or a
+deferred draw on a resize). `update()` resolves whether it drew anything, but a
+cell it deferred is drawn later, so ask `grid.plotted`, not that value, before
+acting on a figure.
+
+The other options:
+
+| Option | What it does |
+|---|---|
+| `resolveSeries(series, results, subplot)` | Returns `{ y, x? }` or null. Default `resolveSeriesData`: `series[_resultKey ?? variable]`, then `variable`, then the name after its first `.`; `x` is `_resultTime`. Also resolves the x variable. |
+| `derivedTraces(traces, subplot, { results, index })` | Extra Plotly traces (or a promise of them) appended to a subplot's figure. |
+| `onTransformError`, `onError` | A transform that failed (`{ transformId, traceName, error }`); a subplot that failed to draw (`{ index, error }`), on an `update()` or on the resize that draws a deferred one, which then shows the empty message. |
+| `theme` | Overrides for `PLOT_GRID_THEME`: `fontFamily`, `fontColor`, `fontSize`, `paperBackground`, `plotBackground`, `gridColor`, `lineColor`, `tickColor`, `zeroLineColor`, `hoverBackground`, `hoverBorder`. |
+| `alwaysShowLegend` | Draws a subplot whose legend is `'hidden'` with one at the top. |
+| `layout` | Plotly layout fields merged over every figure's (`hovermode`, `margin`, ...). |
+
+`PlotPopoutWindow` takes `resolveSeries` too, for its chart and its data
+table. Its chart cells were `div.plot-tile-chart` and are now
+`div.twm-plot-grid__cell` inside a `.twm-plot-grid`. An overlay is drawn for
+any series with an `overlay` and data under its id in `actuals`; it used to
+need `overlay.etlKey` as well. More changes to what the window draws, for
+configs outside the fixtures:
+
+- On an `'area-stacked'` subplot, overlays are stacked too, in a group of their
+  own per y-axis (`stackgroup: 'overlay-<y ref>'`, `groupnorm: 'fraction'`,
+  `mode: 'lines'`, no fill), so they read on the same 0..1 scale as the stack.
+  They used to be drawn unstacked, at their raw values.
+- A subplot with no traces draws an empty figure, not the empty message, only
+  when **all of its own** series are hidden (its overlays and derived traces do
+  not count). It used to do that for every subplot as soon as any series
+  anywhere in the window was hidden. Null results win over that rule: with no
+  results every configured subplot shows `emptyMessage`, hidden series or not.
+- While `getResults()` answers null and nothing has been drawn yet, every cell
+  shows `emptyMessage`; the cells used to stay blank. Figures already drawn
+  stay while the results are briefly null, as before.
+- A y axis's positive `step` sets the Plotly `dtick` of that axis. The window
+  used to ignore `step`, so Plotly chose the tick spacing.
+- A subplot with `xAxis: { useTime: false, variable }` is drawn against that
+  variable, with an x-axis title (`xAxis.label`, else the variable's name) and
+  no clip of the x axis to the time range. The window used to ignore `xAxis`
+  and always drew against time, clipped to the first and last time point.
+
+Its zoom and pan buttons and Download PNG act on `grid.plotted`, so a figure the
+grid drew on a resize (the window opened while its plot area had no size) is
+zoomable and exportable; Download PNG exports the first subplot that shows a
+figure, where it used to try the first slot whatever it held.
+`tests/plot_grid.test.mjs` pins all of it,
+including that the window draws the same traces, names and axes for the
+fixture configs (`tests/fixtures/plot_grid_fixtures.mjs`) as it did before.
+
+## Editing a plot config: `renderPlotConfigEditor` (0.17.0)
+
+`renderPlotGrid` draws a plot config; `renderPlotConfigEditor` edits one, in
+place, so an embedder no longer writes its own panel for it:
+
+```js
+import { renderPlotConfigEditor, renderPlotGrid, migrateData } from '@flexdesk/charts';
+
+const plotConfig = migrateData(savedConfig);
+const editor = renderPlotConfigEditor(el, plotConfig, {
+    onChange: () => grid.update({ plotConfig }),            // after every edit
+    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 */ },
+});
+editor.dispose();
+```
+
+It draws a layout picker (every `PLOT_LAYOUTS` entry), 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, under each, its series (a picker, legend label, colour, width, dash and
+stack group); its z axis while the chart type is 3D; its reference lines and
+shaded bands; and the toggles of any `seriesTransforms`. Every edit writes the
+config it was given and then calls `onChange(config)`.
+
+- A layout with more slots than there are subplots adds default subplots
+  (`makeDefaultSubplot`); one with fewer keeps the extra subplots, so switching
+  back restores them.
+- **Add Y axis** adds `makeDefaultYAxis(index)` (left for an even index, right
+  for an odd one) and **Add series** adds `makeDefaultSeries(index)` (coloured
+  by its place among the subplot's series). Both come from `@flexdesk/charts`,
+  and `makeDefaultSubplot` and `migrateData` build their axes and series from
+  them, so an axis added in the editor matches a default subplot's.
+- A 3D chart type gives the subplot a z axis (label, scale, min, max, step and
+  a series) and uses its first y axis only: the other y axes are shown disabled
+  and **Add Y axis** is disabled. A 2D chart type sets `zAxis` back to `null`.
+- Every series picker is an `AutocompleteField` fed by `seriesProvider`, asked
+  `{ value, role, subplot }`, where `role` is `'series'`, `'x'` or `'z'`. It
+  answers AutocompleteField items (`{ label, insertText?, type? }`) or a promise
+  of them. A provider that throws or rejects shows no suggestions and leaves
+  the typed text as it is (`logger.warn` hears it when you pass `logger`).
+  Without `seriesProvider` the pickers suggest nothing and take typed text.
+- `overlaySources()` answers choice options (`{ value, label }`, or
+  `{ group, options }`), or a promise of them, asked once per draw. With it,
+  every series row gets an overlay source select; choosing one writes
+  `series.overlay = { source, ... }` and shows the overlay's label, colour,
+  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
+  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.
+
+It returns `{ dispose, refresh, selectSubplot, activeSubplot }`: `dispose()`
+disposes every field it created (every `AutocompleteField` among them) and
+removes the editor; `refresh()` redraws it after the config was changed from
+outside; `selectSubplot(index)` brings a subplot to the front. It fits
+`PlotPopoutWindow`'s `configRenderer` slot, `(container) => { dispose() } | void`:
+the window disposes what the renderer returns when it closes, so return the
+editor and its dropdowns leave `document.body` with the window.
+`openPlotPopoutWindow` is async; await it:
+
+```js
+const win = await openPlotPopoutWindow({ id, title, plotConfig, getResults, services,
+    configRenderer: (el) => renderPlotConfigEditor(el, plotConfig,
+                                { onChange: () => win.updateConfig(plotConfig) }) });
+```
+
+Its classes are under `.twm-plot-config` in `flexdesk.css`.
+`tests/plot_config_editor.test.mjs` pins all of it.

package/docs/components/command-palette.md

@@ -0,0 +1,102 @@
+# Command palette
+
+> **Package:** `@flexdesk/wm` · **See also:** [Keys, Back and tab layout](keymap.md) · [All docs](../README.md)
+
+Ctrl+K opens the command palette. It searches the entity catalog you pass to `createShell` (built with `createEntityCatalog`) and the commands you give it, and a pick can open in place, in a split or in a window. Everything here is passed as `palette: { … }`, and the options are opt-in: a shell that passes none keeps the chip strip, the panel toggles and the flat list.
+
+## The palette that finds anything (0.9.0; matching tightened in 0.9.1)
+
+Ctrl+K's grouped layout. Every option is off unless you pass it, so a shell that
+passes none of them keeps the chip strip, the panel toggles and the flat list:
+
+```js
+await createShell({
+    // …everything above…
+    palette: {
+        placeholder: 'Search everything…',
+        layout: 'grouped',                       // a header per kind, matches marked
+        chrome: { pages: false, panels: false }, // nothing between the input and the results
+        groupCap: 4,                             // then "Show all N", which scopes to the kind
+        cache: true,                             // a re-open draws the last catalogue at once
+        empty: async () => recentRows(),         // shown before anything is typed, under "Recent"
+        commands: () => commandRows(),           // `{label, action}`; `>` restricts to them
+        drill: (pick) => pick.kind === 'planet'  // Tab on a row enters a scope
+            ? { label: `${pick.label} › moons`, search: (q, signal) => findMoons(pick.id, q, signal) }
+            : null,
+        onPick: (pick, { mode, scope }) => openSomewhere(pick, mode), // 'open' | 'split' | 'window'
+    },
+});
+```
+
+A row may carry `context` (drawn, not searched), `keywords` (searched, not
+drawn), `modes` (which of `split`/`window` its keys offer), `drillLabel` (the Tab
+hint), `boost`, `group`/`groupLabel`, `kindLabel`, `shortcut` and `verb`. A group's
+header is the taxonomy's `plural` for the kind, else its `label`. Matching ranks
+exact, prefix, word starts (`ord li` finds *Order lines*), substring, then an
+abbreviation: it starts at a word, and the letters it skips outside word starts are
+at most half the query (`cstmr` finds *customer*; `cour` does not find *Scroll up
+to*). A drill's `search` is debounced, and a stale answer is aborted and
+never drawn. `palette.invalidate()` drops the cache.
+
+**The built-in *Keyboard shortcuts* command** opens the help topic
+`keyboard-shortcuts`. If your `HelpProvider` defines that id, your topic is
+shown. If it does not, or you register no help at all, the modal shows the window
+manager's own bindings, `KEYMAP_SHORTCUTS` from `@flexdesk/wm`, as a table
+(`keyboardShortcutsTopic()`). Before this the modal showed *Failed to load help
+topic.* The fallback comes from `HelpModal.open(id, { fallback })`
+(`@flexdesk/widgets`), and you can pass one yourself. A topic id that nobody
+provides now shows *Help topic not found.* where it used to raise a load error.
+
+## A palette row drawn disabled, with a reason (0.17.2)
+
+A palette row (a command from `commands`, or any other row) may carry
+`enabled: () => boolean` and `disabledReason`. While `enabled()` returns false
+the row is still listed, so it can say why it does nothing:
+
+```js
+palette: {
+    commands: () => [
+        { id: 'save', label: 'Save', action: save,
+          enabled: () => dirty, disabledReason: 'Nothing to save' },
+    ],
+},
+```
+
+- The row gets the class `twm-cmdpal__item--disabled` and `aria-disabled="true"`,
+  and `disabledReason`, when given, is its `title` (the tooltip). The stylesheet
+  greys it.
+- Picking it with a click, Enter, Ctrl+Enter or Shift+Enter runs nothing: not
+  its `action`, not `onPick`. The palette stays open on it.
+- The arrow keys still move onto it and past it.
+- `enabled()` is called again on every draw and every pick, so the row follows
+  your state while the palette is open. An `enabled()` that throws counts as
+  false.
+- A row without `enabled` is drawn and picked as before. Both layouts (flat and
+  `grouped`) behave the same way.
+
+`tests/command_palette_disabled.test.mjs` drives it in jsdom.
+
+## A catalog source only behind its prefix: `scopedOnly` (0.17.2)
+
+A source can be too broad to compete with everything else in the palette: help
+topics, say, which would crowd every query. Mark it `scopedOnly` and its rows are
+listed only once its prefix has made the type chip:
+
+```js
+createEntityCatalog({
+    sources: [
+        { navKind: 'model', list: listModels, shape: toRow },
+        { navKind: 'topic', list: listTopics, shape: toRow, scopedOnly: true },
+    ],
+    aliases: { help: ['topic'] },
+});
+```
+
+A plain typed query (`solver`) lists no `topic` row, in the flat and the grouped
+layout alike: no row, no group header, no *Show all*. `help: solver` or
+`topic: solver` lists its rows as any source's, and `help:` alone lists them all.
+The mark is the palette's business: `loadAll`, `loadGrouped` and the tile menu
+still return every source, a picked row reaches `onPick` as its `shape` made it,
+and commands and `empty()` rows of the same kind are not held back. A source
+without the option, or with `scopedOnly: false`, is searched exactly as in
+0.17.1. A value that is not a boolean is refused with a `TypeError`.

package/docs/components/conversation.md

@@ -0,0 +1,72 @@
+# Conversation view
+
+> **Package:** `@flexdesk/widgets` · [All docs](../README.md)
+
+A transcript of role-tagged messages above a composer. It has no Markdown and no model in it: you draw a message's body, and it tells you when the user submits or cancels.
+
+## A conversation: `mountConversationView` (0.17.0)
+
+A transcript of role-tagged messages above a composer, in `@flexdesk/widgets`.
+It has no markdown and no model in it: you draw a message's body, and it tells
+you when the user submits or cancels.
+
+```js
+const view = mountConversationView(el, {
+    render:   (message, bodyEl, { streaming }) => { bodyEl.innerHTML = toHtml(message.text); },
+    onSubmit: (text) => { view.append({ role: 'user', text }); view.setBusy(true); ask(text); },
+    onCancel: () => abort(),
+    placeholder: 'Ask anything',
+});
+view.beginStream({ role: 'assistant' });
+for await (const chunk of reply) view.appendChunk(chunk);  // re-renders this message only
+view.endStream();
+view.setBusy(false);
+```
+
+| Method | Does |
+|---|---|
+| `append({ id?, role, text, meta? })` → id | Adds a message; `role` becomes `twm-chat__msg--<role>` |
+| `replaceAll(messages)`, `clear()` | Restores a transcript (and scrolls to its end), or empties it |
+| `beginStream(message?)` → id, `appendChunk(text)`, `endStream()` | A message that grows; each chunk re-renders that message's body and nothing else |
+| `slot(id)` | The element below a message's body, yours to fill (tool output, buttons); a re-render leaves it alone |
+| `messages()`, `streamingId()` | Copies of the messages; the one streaming |
+| `getScrollTop()`, `setScrollTop(px)`, `scrollToBottom()`, `isPinned()` | The transcript's scroll position, to keep across a remount |
+| `setBusy(bool)`, `isBusy()` | `true` turns Send into Cancel |
+| `getText()`, `setText(text)`, `focus()`, `destroy()` | The composer, and teardown |
+
+- **`render(message, bodyEl, { streaming })`** fills an emptied body. One that
+  throws leaves that message as its plain text and the view carries on; the
+  error goes to `onRenderError(error, message)`. Without `render`, every body
+  is plain text (`textContent`, never markup).
+- **Pinned to the bottom.** The transcript starts out following new content.
+  Any scroll up, even a few px from the end (the first frame of a smooth wheel
+  or arrow-key scroll), stops that and shows *Jump to latest*, and later chunks
+  leave the reader where they are. It follows again only after a scroll down
+  that ends within `pinThreshold` px (32) of the end, a click on *Jump to
+  latest*, `scrollToBottom()`, `replaceAll()` / `clear()`, or a
+  `setScrollTop(px)` that lands within the threshold. Content growing below
+  never unpins it, nor does content shrinking under it (the browser moves
+  `scrollTop` back to the new end, which is not the reader scrolling). A wheel
+  over a scroller nested in a body or a slot (a `<pre>`, a tool-output box)
+  scrolls that scroller (or, at its top with `overscroll-behavior: contain`,
+  keeps the wheel), and a wheel a handler in the transcript cancels, a
+  Ctrl+wheel (page zoom, or a trackpad pinch) and a wheel up over a transcript
+  already at its top move nothing, so in all these cases the transcript keeps
+  following.
+- **The composer** grows with its text up to `composerMaxHeight` (200 px).
+  Enter submits and clears it (blank text is ignored, and so is Enter during
+  IME composition); Shift+Enter is left to the browser, which inserts the
+  newline (so undo and `input` listeners see it). While busy, Enter submits
+  nothing, and Esc (wherever focus is inside the view) or a click on Cancel
+  calls `onCancel` once per busy period. That Esc goes no further
+  (`stopPropagation`), so a `ManagedWindow` or panel holding the view that
+  closes on Escape stays open. An Esc a handler inside the view has already
+  consumed (`preventDefault`, e.g. an inline popup in the transcript closing
+  itself) is left alone: it neither cancels nor is stopped.
+- **Ids are unique.** `append`, `beginStream` or `replaceAll` with an id already
+  in the transcript (or repeated within the `replaceAll` list) throws, and the
+  refused call changes nothing: no row, no open stream, the old transcript kept.
+- `labels: { send, cancel, jump, input }` replaces the four texts.
+
+`tests/conversation_view.test.mjs` drives all of it in jsdom with a fake
+scroll geometry.