flexdesk 0.18.0 → 0.18.2

package/dist/wm.js

@@ -9,13 +9,13 @@ import {
 import {
   openForm,
   showContextMenu
-} from "./chunk-RKVYIXDC.js";
+} from "./chunk-NFZJ6P42.js";
 import {
   isRowActivation
 } from "./chunk-VLOAI3HS.js";
 import {
   ManagedWindow
-} from "./chunk-ZL3VKINP.js";
+} from "./chunk-HL3IIHU3.js";
 import "./chunk-Q7BALEPX.js";
 import "./chunk-HNU6MM2B.js";
 import {

package/docs/components/charts.md

@@ -414,6 +414,10 @@ config it was given and then calls `onChange(config)`.
   is disposed. A `dispose()` that throws is reported to `logger.warn` and does
   not stop the rest of the editor being disposed.
 
+- [`hide`](#hiding-parts-of-the-editor-hide-0181) takes parts of the editor away,
+  and [`constantsProvider`](#a-reference-line-that-names-a-constant-constantsprovider-resolveconstant-0181)
+  lets a reference line name a constant.
+
 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
@@ -431,3 +435,39 @@ const win = await openPlotPopoutWindow({ id, title, plotConfig, getResults, serv
 
 Its classes are under `.twm-plot-config` in `flexdesk.css`.
 `tests/plot_config_editor.test.mjs` pins all of it.
+
+## Hiding parts of the editor: `hide` (0.18.1)
+
+An embedder whose plots are always 2D time series has no use for some of the editor:
+
+```js
+renderPlotConfigEditor(el, plotConfig, { hide: ['3d', 'stackGroup', 'xAxis'] });
+```
+
+| Name | What goes |
+|---|---|
+| `'3d'` | The 3D chart types and the z axis section. A subplot saved as 3D keeps its chart type, marked as one the list does not offer, until someone picks a 2D one. |
+| `'stackGroup'` | Each series' stack group box. A saved stack group stays in the config and is drawn. |
+| `'xAxis'` | The x axis section. The subplot then plots against time: `xAxis.useTime` is set to true when it opens, and `xAxis.variable` is left as it was. |
+
+Any other name throws. Without `hide` the editor draws what it always did.
+
+## A reference line that names a constant: `constantsProvider`, `resolveConstant` (0.18.1)
+
+A reference line's value is a number, so it cannot follow a parameter whose value changes between runs. With `constantsProvider` it may also name one:
+
+```js
+renderPlotConfigEditor(el, plotConfig, {
+    constantsProvider: () => [{ name: 'bank.rate', value: 0.25, label: 'Bank rate', group: 'bank' }],
+});
+renderPlotGrid(host, plotConfig, results, {
+    resolveConstant: (name) => constants.get(name),   // a number, or undefined
+});
+```
+
+The value box then offers the names, with their values and under their groups, as `attachInputOptions` does. It is asked each time the list is drawn. What is stored is a number when what was typed is one, even when it is part of a name on the list, and the name as a string otherwise; beside a name it knows, the box shows `= 0.25`. An empty box stores `null`, as the number box does. A click shows every name.
+
+`renderPlotGrid` asks `resolveConstant(name)` each time it draws a subplot, so a redraw follows a new value, and `grid.update({ results })` is enough. A name it does not know draws no line and no label, and so does any name without `resolveConstant`. The config keeps the name.
+
+Without `constantsProvider` the box is the number box it always was.
+

package/docs/components/chat-shell.md

@@ -62,7 +62,7 @@ So a transport that gives each run its own callback, and calls that run's `emit`
 
 #### A backend with no run id
 
-A backend that pushes to a global has one place to send a frame, and the frame does not say which run it is from. The adapter holds the latest `emit`, so the chat cannot tell an old run's chunk from the new reply's. Runs must therefore not overlap, and `cancel` is how: it answers a promise that settles when the cancelled run is over and the backend takes a new request. The next turn shows at once, with its typing dots, and its `send` is called when the promise settles. A promise that rejects is logged and counts as settled; one that never settles leaves the next turn waiting until the user stops it.
+A backend that pushes to a global has one place to send a frame, and the frame does not say which run it is from. The adapter holds the latest `emit`, so the chat cannot tell an old run's chunk from the new reply's. Runs must therefore not overlap, and `cancel` is how: it answers a promise that settles when the cancelled run is over and the backend takes a new request. The next turn shows at once, with its typing dots, and its `send` is called when the promise settles. A promise that rejects is logged and counts as settled. One that never settles, or a run-over that is lost, holds the next turn only until the user stops it: [Stop releases a turn that is waiting](#stop-releases-a-turn-that-is-waiting-0181).
 
 ```js
 let emit = null;
@@ -99,6 +99,12 @@ const transport = {
 
 While the run winds down, `emit` is still the cancelled turn's, so its late chunks and its report that it was cancelled are dropped, with no check of yours. The promise must not settle before the backend would accept a request: if the backend sends its last frame and only then frees itself, have it send the end of the run after that, and settle on that instead. A `cancel` that answers no promise says there is nothing to wait for, and `send` is called at once.
 
+#### Stop releases a turn that is waiting (0.18.1)
+
+A send made after a Stop waits for `cancel`'s promise. If that promise never settles, because the backend stalled or its run-over was lost, the turn shows its typing dots with nothing behind them. Stop on that turn releases the wait: it was never sent, so `transport.cancel` is not called for it, and the next send goes out at once.
+
+The person has then said twice that they will not wait, and the chat does what they ask. So a backend whose old run may still be alive can see a request while it runs. One that takes one run at a time should refuse the overlapping request: the refusal shows as an error with Retry. One that accepts it will mix the old run's frames into the new reply, because they arrive through the one `emit` the adapter holds.
+
 ### A turn
 
 The user's message goes in, then a streamed assistant message that shows the typing dots while it is empty. While the turn runs, Send is Cancel and Esc cancels, as in the conversation view, and the New and Clear buttons are disabled. A turn ends in one of three ways:
@@ -125,7 +131,7 @@ A reply still empty is not in a snapshot, and a tool that was `running` when a s
 |---|---|
 | `send(text)`, `cancel()` → bool | As the user would; false when refused |
 | `isBusy()`, `messages()`, `snapshot()` | A turn is running; the messages in front; everything to keep |
-| `activeConversation()`, `newConversation()` → id, `switchTo(id)`, `close(id)`, `rename(id, title)`, `reset()` | The tabs. `reset` empties the one in front. Refused ones answer false (`newConversation`: null) |
+| `activeConversation()` → id, `newConversation()` → id, `switchTo(id)`, `close(id)`, `rename(id, title)`, `reset()` | The tabs. `activeConversation` answers the id of the one in front, not the conversation; `snapshot()` holds its messages. `reset` empties the one in front. Refused ones answer false (`newConversation`: null) |
 | `setConversationId(tabId, id)` | Your backend's id for a conversation |
 | `setMessages(tabId, messages)` | Replaces a conversation's messages, when your backend knows better. The one a turn is writing to refuses |
 | `updateMeta(id, patch)`, `refreshControls(id)`, `controlsSlot(id)` | A message's controls, below |

package/docs/components/filter-builder.md

@@ -92,14 +92,24 @@ A field naming an operator the catalogue lacks throws when the model is created.
 |---|---|
 | `matcherFor(expr)` | `(row) => boolean`, compiled once and cached by the expression's JSON. An unknown field or operator matches nothing and warns. |
 | `evaluateFilter(expr, row)` | One row. |
-| `describeFilter(expr, { formatValue })` | One line of words. `formatValue(value, field)` names each value (a key shown as a name, say). An unknown field is said: `⚠ unknown field “gone”`; the `unknownName(key)` option of `createFilterModel` shapes the key shown. |
+| `describeFilter(expr, { formatValue, groupBrackets })` | One line of words. [What it says](#what-a-sentence-says-0181). |
 | `validateFilter(expr)` | `{ ok, errors }`, listing every problem, not the first. |
 | `unknownFields(expr)` | The keys it names that the catalogue lacks, for a marker wherever a saved filter is listed. |
-| `pruneFilter(expr)` | A copy without empty groups and conditions with nothing to compare against, or null when nothing is left. A condition the catalogue cannot read is kept. |
+| `pruneFilter(expr)` | A copy without empty groups and conditions with nothing to compare against, or null when nothing is left. A condition the catalogue cannot read is kept, and so is a range with one end filled. |
+| `partialRanges(expr)` | What is said of each range with one end filled: `Count between: needs two values`. [The dialog refuses one](#a-range-with-one-end-filled-is-refused-0181). |
+| `moveClause(clause, key)` | The condition on another field. [What it keeps](#what-a-condition-keeps-when-its-field-changes-0181). Null when the catalogue has no such field. |
 | `operatorsFor(key)`, `operatorById(id)`, `newClause(key?)`, `defaultValue(field, op)`, `fieldByKey(key)` | What the builder uses. |
 
 `coerceFilterValue(field, text)` is the one place a control's string becomes a value. A `number` field writes a number when the string is a plain decimal a double holds exactly. It leaves the string alone when converting would change the filter: an empty box, a half-typed `-`, or a decimal wider than a double.
 
+### What a sentence says (0.18.1)
+
+`formatValue(value, field)` names each value (a key shown as a name, say); without it a value is shown as itself.
+
+- **Every value of a list**, under any operator: `Tags contains a, b`, not the first alone. A saved condition or one from elsewhere may hold several under an operator that takes one.
+- **A field the catalogue does not know is said, with what the condition asks:** `⚠ unknown field “gone” is x`. The `unknownName(key)` option of `createFilterModel` shapes the key shown. `formatValue` is not asked about it, because there is no field to hand it. An operator the catalogue does not know is said as its id, with its value.
+- **Brackets** go where the sentence would misread without them: a nested group of two or more, and whatever a NOT covers: `A AND (B OR C)`, `NOT (A)`. With `groupBrackets: true` every group of two or more has them, the root too, and a NOT of one thing has none: `(A AND (B OR C))`, `NOT A`. That is for a surface that reads a group by its brackets.
+
 ## The condition tree (0.18.0)
 
 A server that compiles conditions usually wants a different spelling. `toConditionTree(expr)` and `fromConditionTree(tree)` convert to and from:
@@ -179,6 +189,15 @@ Each group has an AND/OR toggle, NOT, `+ Condition` and `+ Group`; each conditio
 
 **It rewrites nothing it cannot read.** A condition on a field the catalogue lacks, an operator it lacks, an operator this field is not offered, an `enum` value no longer offered and a carried node all stay exactly as they are until someone changes or removes them: the selects show them as their own entry (`⚠ unknown field “gone”`, `made_up (unknown)`), and a value it cannot interpret is shown read-only. Opening and closing a builder leaves the expression byte-identical, with one exception: an `enum` condition with no value takes the first option, because a select cannot show nothing.
 
+### What a condition keeps when its field changes (0.18.1)
+
+Choosing another field for a condition goes through `model.moveClause(clause, key)`:
+
+- The **operator** stays when the new field offers it. Otherwise the condition starts on the field's first operator, as `newClause(key)` does.
+- The **value** stays when it still fits: it passes `validateFilter` on the new field and, where the editor offers a list (an `enum` field, a `multi` operator on a field with `options`), it is on that list. Otherwise it starts as `defaultValue(field, op)`. `validateFilter` checks every value of a `multi` operator as it does a single one, so `one_of ['abc']` on a number field is refused and does not move there. A value that does fit is kept as it stands: `is '5'` moved to a number field is still the string `'5'`.
+
+A condition whose field or operator cannot be drawn shows the value it holds read-only: an unknown field, an unknown operator, or a known operator its field does not offer. A box drawn for that operator would look empty over a value the result still carries. A custom editor is not asked about one. An unknown field's whole warning is the field select's tooltip, and the select takes its width from it where the row can spare that.
+
 ### A custom value editor (0.18.0)
 
 `field.editor` replaces the value control. It is a factory, called each time the value cell is drawn:
@@ -226,21 +245,48 @@ const result = await openFilterDialog({
 | Option | |
 |---|---|
 | `model`, `value` | As the builder's. `value` is copied, so dismissing loses nothing. |
-| `seedField` | A field key: adds a new condition on it, for "filter by this". |
+| `seedField` | A field key: adds a new condition on it, for "filter by this". [Beside a negated root](#a-seed-beside-a-negated-root-0181), not inside it. |
 | `title`, `icon`, `width`, `height` | The window. |
 | `head` | An element drawn above the conditions. |
-| `name` | `{ value, label, placeholder, required }` adds a name box. `required` defaults to true and holds the submit button off until it is filled. The result's `name` is trimmed. |
+| `name` | `{ value, label, placeholder, required }` adds a name box, which opens with focus and [its text selected](#the-name-box-opens-selected-0181). `required` defaults to true and holds the submit button off until it is filled. The result's `name` is trimmed. |
 | `iconChoice` | `{ value, options }` adds a searchable grid over those Material Symbols names. |
 | `preview` | `(host, { expr, sentence, signal })`: yours to draw into. Called on open and, debounced, after each change, while the expression can be submitted; otherwise the slot is emptied and hidden and the errors are shown. `signal` aborts when this drawing is superseded or the dialog closes, for a preview that asks a server. The dialog shows `sentence` above the slot. |
-| `requireValid` | Default true: the submit button is off, and the errors are listed, while `validateFilter` objects. False submits regardless. |
+| `requireValid` | Default true: the submit button is off, and the errors are listed, while `validateFilter` objects. False submits regardless, except [a range with one end filled](#a-range-with-one-end-filled-is-refused-0181). |
 | `prune` | Validate, preview and submit `model.pruneFilter(...)`, so a half-built row is dropped rather than refused. `expr` is null when nothing is left. |
 | `confirmDiscard` | Ask before Cancel, Esc or the X throws away a change. |
+| `dismissOnBackdrop` | [A click on the dimmed page beside the dialog dismisses it](#a-click-beside-the-dialog-dismissonbackdrop-0181), as Esc does. |
 | `submitLabel`, `onSubmit` | `onSubmit(result)` may be async: until it settles every button is off and Esc and the X do nothing, so the answer always says what happened. If it throws, the message is shown and the dialog stays. A promise that never settles holds the dialog open, so give a call that can hang its own timeout. |
 | `clearLabel` | Adds a button answering `{ action: 'clear', expr: null }`, for a caller to whom "no filter" and "leave it alone" are different answers. |
-| `actions` | More buttons, before Cancel: `{ label, value, danger, icon, confirm, run }`. `confirm` is `openConfirm`'s options, asked first, and `run` behaves as `onSubmit` does. |
+| `actions` | More buttons, before Cancel: `{ label, value, danger, icon, confirm, run }`. `confirm` is `openConfirm`'s options, asked first, [with a `message` that may be computed](#a-question-that-quotes-what-was-typed-0181), and `run` behaves as `onSubmit` does. |
 
 `confirmDiscard` asks through [`openModal`'s `beforeClose`](forms-and-dialogs.md#a-modal-that-can-refuse-to-close-beforeclose-0180).
 
+### A range with one end filled is refused (0.18.1)
+
+`between` with `[5, null]` is not blank, so `prune` keeps it, and it matches nothing: with `requireValid: false` it used to leave the dialog, and a filter that a server compiles to `BETWEEN 5 AND NULL` emptied the view with no word why. The submit button is now off and the dialog says `Count between: needs two values`, whatever `requireValid` and `prune` say. A range with both ends blank is still a half-built row, which `prune` drops.
+
+`model.pruneFilter` keeps such a range for a caller without the dialog, and `model.partialRanges(expr)` names them.
+
+### A seed beside a negated root (0.18.1)
+
+A new condition narrows what the filter already says. Pushed into a negated root it would become `NOT (title is x AND qty is 7)`, and rows the filter excluded would come back. So `seedField` on a negated root wraps it: `(NOT (title is x)) AND qty is 7`.
+
+### The name box opens selected (0.18.1)
+
+The name box takes focus when the dialog opens, with its text selected: editing a name usually means replacing it, and `Mine (copy)` always does. The rest of the library's dialogs keep the caret at the end, and [`openModal` leaves focus where `onMount` put it](forms-and-dialogs.md#focus-placed-by-onmount-stays-0181).
+
+### A click beside the dialog: `dismissOnBackdrop` (0.18.1)
+
+`openFilterDialog({ dismissOnBackdrop: true })` dismisses on a click on the dimmed page beside it, through [`openModal`'s option of that name](forms-and-dialogs.md#a-click-beside-a-modal-dismissonbackdrop-0181). `confirmDiscard` still asks, and an action in flight still holds it open.
+
+### A question that quotes what was typed (0.18.1)
+
+`confirm.message` may be `(result) => string`, called when the question is asked with what the dialog would answer (`{ action, expr, name?, icon? }`):
+
+```js
+confirm: { title: 'Delete this filter?', message: ({ name }) => `Delete “${name}”?`, confirmLabel: 'Delete', danger: true },
+```
+
 ## Styling
 
 Classes are `twm-filter-builder*` and `twm-filter-dialog*`. Every rule reads tokens; retheme through those.

package/docs/components/flow-editors.md

@@ -81,6 +81,26 @@ be used is disabled and its reason is shown next to it, not only in a tooltip.
 `extra` holds the editor's own fields (a port shown as a setting) and notes,
 placed with `after: '<key>'` or `at: 'start'`.
 
+### A flat panel: `variant: 'sheet'` (0.18.2)
+
+`createSettingsPanel({ ..., variant: 'sheet' })` draws the panel flat, as one
+section of a page of them: no fill and no icon chip, the title and the
+description in a margin at the left, the id line, findings, slots and fields
+beside them. Two sheets in a row are split by a rule, so a settings page built of
+several panels (one per subject: *Run*, *Solver*, *Metadata*) reads as one form.
+Narrower than 560px the margin goes above the fields. Everything else is the
+card's: `show()`, the repaints, focus, findings and slots behave the same.
+`variant` is `'card'` (the default) or `'sheet'`; any other value is refused when
+the panel is created.
+
+```js
+for (const section of sections) {
+    const panel = createSettingsPanel({ widgets, host: page, variant: 'sheet', onChange: section.write });
+    panel.show({ title: section.title, description: section.hint, type: { config_schema: section.schema },
+                 value: section.read() });
+}
+```
+
 **The widgets.** A schema type with no `x-ui-widget` draws its plain control: an
 `enum` a select (writing the enum's own value, so a number stays a number), a
 string a text box, a number a number box, a boolean a checkbox, an object with

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

@@ -332,6 +332,14 @@ answering false keeps it open. An action button does not ask it. A modal it lets
 close resolves `null`, as any dismissal does. `openFilterDialog`'s `confirmDiscard`
 is built on it.
 
+## A click beside a modal: `dismissOnBackdrop` (0.18.1)
+
+`openModal({ dismissOnBackdrop: true })` dismisses on a click on the dimmed page beside the modal, as Esc does: `beforeClose` is asked, and the modal resolves `null`. A drag that starts in the modal and ends on the page is no click on the backdrop. The press takes no focus from the modal, so when `beforeClose` refuses, the caret is where it was. Default `false`: the backdrop only blocks, which is what it has always done, whatever older comments in the source said.
+
+## Focus placed by `onMount` stays (0.18.1)
+
+`openModal` focuses the first field, or the primary button, a frame after `onMount` ran. It now leaves focus alone when `onMount` already put it inside the modal, with its selection. Before, the first field took it and the caret went to the end.
+
 ## Windows: closing, focus and Esc (0.17.16)
 
 Every dialog above is a `ManagedWindow`, and so is any window you build

package/docs/components/input-fields.md

@@ -235,3 +235,27 @@ fires a bubbling `change` on the input, for a form around it.
 also means "this one", such as the tag input's comma.
 
 `tests/select_combobox_popover.test.mjs` covers these and the tag input's options in jsdom.
+
+## A list under a name being edited: `attachInlineRenamer` (0.18.1)
+
+`attachInlineRenamer`'s `onStart` now runs before the renamer adds its own key listeners, and is handed the input as `{ value, triggerEvent, input }`. So what it attaches hears each key first, which is what [`attachInputOptions`](#a-text-box-that-also-offers-a-list-createcombobox-0180) asks for:
+
+```js
+const renamer = attachInlineRenamer({
+    label,
+    onStart: ({ input }) => {
+        list = attachInputOptions(input, {
+            options: names,
+            onPick: (option) => {
+                input.value = option.value;
+                renamer.commit('pick');
+            },
+        });
+    },
+    onCommit: (name) => save(name),
+    onFinish: () => list.destroy(),
+    onCancel: () => list.destroy(),
+});
+```
+
+Enter on an arrow-highlighted row commits the row; with no row highlighted it commits what was typed. Esc with the list open closes only the list, and the next one cancels. Taking the field off the page ends the edit first, so the blur a browser fires for it commits nothing after a commit or an Esc.

package/docs/components/menus.md

@@ -33,6 +33,10 @@ items they hold:
 
 Nothing changes in how you call them.
 
+## A press inside no longer disarms a context menu (0.18.1)
+
+`showContextMenu` kept its outside-press listener for one press. A press inside the menu (a separator, the padding, a disabled row) used it up, and from then on a press outside was ignored until Escape. It now listens until the menu closes. A consumer's own outside-press listener for this can go.
+
 ## A menu bar: `createMenuBar` (0.17.0)
 
 File / Edit / View menus from one declarative model, instead of hand-built

package/docs/components/shell.md

@@ -37,6 +37,10 @@ await createShell({
 });
 ```
 
+## Keyboard focus shows a tooltip (0.18.1)
+
+`TooltipService` shows a `twm-has-tooltip` element's tooltip (or a `has-latex-tooltip` element's) when it takes keyboard focus, as hovering does, and hides it when focus leaves the element or on Esc. Focus moving inside the element keeps it. A pointer does not take it down: over another target the pointer's tooltip shows for as long as the pointer stays, then focus's comes back. A scroll does not hide it, the one the focus itself caused included: it goes with its target, and waits while a wheel has the target out of sight. Keyboard focus means the last press was a key, not a Ctrl, Cmd or Alt chord: the focus a click leaves shows nothing, nor does a field its handler then focuses. The browser's `:focus-visible` cannot tell this, being true for any text field. A consumer that wires `focusin` to `TooltipService.show` itself can stop.
+
 ## The pages as a vertical rail: `chrome.rail` (0.18.0)
 
 `chrome.topNav` paints the pages as a strip in the top bar. `chrome.rail` paints

package/docs/components/workspace-picker.md

@@ -107,10 +107,54 @@ A centred field's `hostEl` must be positioned. It measures again whenever `hostE
 
 `refresh()` asks `actions`, `card` and `footer` again. `reload()` asks `load` again. `open({ select })` highlights the row with that `id` when the answer lands. `setCurrent(item)` takes the item whether or not any page holds it.
 
-**The keyboard.** The caret stays in the input. The arrows walk a highlight over the rows, Load more, the action rows, the card's buttons and the footer's, wrapping. Until they move, the highlight is the first row or action row, and Enter takes it, or, while the answer to what was typed is on its way, the first one when it lands. Esc closes and gives focus back to where it was. A press outside closes and leaves focus where it was pressed. Tab goes to the panel's buttons, and out of the panel closes it.
-
 **Nothing is rebuilt under a pointer.** Every part is reconciled by key, so an answer landing while a row is being pressed leaves that row's node in place and the click still fires.
 
+### The keyboard (0.18.1)
+
+Focus is real: what the keyboard is on is `document.activeElement`, so a screen reader says each stop, the card's and the footer's buttons included, and Tab and the arrows agree about where the reader is.
+
+| Key | |
+|---|---|
+| The arrows | Walk focus over every stop, wrapping: the input, the rows that can be chosen (a disabled one is stepped over), Load more, the action rows, the card's buttons, the footer's. After `open({ select })` they start from the row it chose. An answer or a redraw leaves focus where it is, on a row that moved too. |
+| Tab | The rows are one tab stop: the row last focused, else the current one, else the first. So are the action rows. Out of the panel closes it. |
+| A character | Goes to the input from anywhere in the panel, and to nothing else: a keymap does not read it as a shortcut. |
+| Enter in the input | Takes what wears the highlight: the first row or action row of what is shown, or, while the answer to what was typed is on its way, the first one when it lands. |
+| Enter or Space elsewhere | Takes the row or runs the button with focus. |
+| Shift+Delete | Removes the row with focus, or the highlighted one from the input. Focus goes on to the next row. |
+| Backspace | The input's in the input. Elsewhere it stops at the panel, where a window manager's keymap would read it as "up one level". |
+| Esc | Closes, and gives focus back to where it was. |
+
+A press outside closes and leaves focus where it was pressed. A row that held focus and went away, because an answer no longer holds it, gives focus to the input. Load more keeps focus while something loads: it is `aria-disabled` then, not `disabled`, and refuses the press itself.
+
+### A trigger of your own (0.18.1)
+
+The field is optional. `createPickerSwitcher` opens on any anchor, so a control of yours can be the trigger:
+
+```js
+const switcher = createPickerSwitcher({
+    anchor: trigger,
+    placement: 'below',
+    visibleRows: 5,
+    load, describe, onPick, card, footer,
+    onOpenChange: (open) => trigger.setAttribute('aria-expanded', String(open)),
+});
+trigger.addEventListener('click', () => switcher.toggle());
+```
+
+A press on the anchor does not count as a press outside, and Esc, a pick or a verb give focus back to it when it had focus. `setCurrent(item)` on the switcher marks the row; naming it on your trigger is yours.
+
+## The field's look: tokens (0.18.1)
+
+Set these over FlexDesk's defaults (`css/tokens.css`) instead of overriding the field's rules:
+
+| Token | Default | |
+|---|---|---|
+| `--twm-wspicker-field-icon` | `var(--accent-bright)` | Its icon. |
+| `--twm-wspicker-field-focus-border` | `var(--accent-bright)` | Its border, focused by keyboard and while open. |
+| `--twm-wspicker-field-muted-icon` | `var(--text-muted)` | Its icon while it names nothing (`muted`). |
+| `--twm-wspicker-field-muted-style` | `italic` | Its name's `font-style` while muted. |
+| `--twm-wspicker-field-muted-opacity` | `0.55` | Its name's opacity while muted. |
+
 ## Recently opened: `createRecentItems` (0.18.0)
 
 A most-recent-first list kept through the [host's](../concepts/host-port.md) `state` capability.

package/package.json

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

@@ -28,6 +28,14 @@
  * added. A 2D chart type removes the z axis (`zAxis: null`, as in
  * makeDefaultSubplot).
  *
+ * `hide` takes parts of the editor away, for an embedder whose plots never use
+ * them: '3d' (the 3D chart types and the z axis), 'stackGroup' (a series' stack
+ * group), 'xAxis' (the x axis section; the subplot then plots against time).
+ *
+ * A reference line's value is a number. With `constantsProvider` it may also name
+ * a constant: the box offers the names, and stores a name as a string, which
+ * renderPlotGrid's `resolveConstant` turns into a value at each draw.
+ *
  * Series names come from `seriesProvider`, through an AutocompleteField per
  * picker: it is asked `{ value, role, subplot }` (`role` is 'series', 'x' or
  * 'z') and answers AutocompleteField items (`{ label, insertText?, type? }`)
@@ -43,6 +51,7 @@
  */
 
 import { AutocompleteField } from '../ui/components/autocomplete_field.js';
+import { attachInputOptions } from '../ui/components/combobox.js';
 import { ColorField } from '../ui/components/color_field.js';
 import { ToggleField } from '../ui/components/toggle_field.js';
 import { selectBox } from '../ui/components/choice_controls.js';
@@ -55,6 +64,7 @@ const CHART_TYPE_OPTIONS = Object.freeze([
     { group: '2D', options: CHART_TYPES_2D },
     { group: '3D', options: CHART_TYPES_3D },
 ]);
+const HIDEABLE = Object.freeze(['3d', 'stackGroup', 'xAxis']);
 const SCALES = Object.freeze([{ value: 'linear', label: 'Linear' }, { value: 'log', label: 'Log' }]);
 const POSITIONS = Object.freeze([{ value: 'left', label: 'Left' }, { value: 'right', label: 'Right' }]);
 const DASHES = Object.freeze([
@@ -200,6 +210,10 @@ let editorCount = 0;
  *        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 {Array<'3d'|'stackGroup'|'xAxis'>} [options.hide] - Parts of the editor not to
+ *        draw. See the file's header. Any other name throws.
+ * @param {Function} [options.constantsProvider] - `() => [{ name, value, label?, group? }]`:
+ *        the names a reference line's value may take, asked each time the list is drawn.
  * @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,
@@ -212,9 +226,15 @@ function renderPlotConfigEditor(container, config, options = {}) {
         overlaySources: null,
         seriesTransforms: null,
         extraSeriesFields: null,
+        hide: [],
+        constantsProvider: null,
         logger: null,
         ...options,
     };
+    for (const part of opts.hide) {
+        if (!HIDEABLE.includes(part)) throw new TypeError(`[plot config editor] cannot hide "${part}"`);
+    }
+    const hidden = new Set(opts.hide);
     const editorId = `twm-plot-config-${++editorCount}`;
     let fieldCount = 0;
     let active = 0;
@@ -380,6 +400,7 @@ function renderPlotConfigEditor(container, config, options = {}) {
 
     function normalise(sp) {
         if (!sp.xAxis) sp.xAxis = { useTime: true, variable: '' };
+        if (hidden.has('xAxis')) sp.xAxis.useTime = true;
         if (!Array.isArray(sp.yAxes) || !sp.yAxes.length) sp.yAxes = [makeDefaultYAxis(0)];
         for (const axis of sp.yAxes) if (!Array.isArray(axis.series)) axis.series = [];
         if (is3DChart(sp.chartType) && !sp.zAxis) sp.zAxis = makeZAxis();
@@ -403,9 +424,9 @@ function renderPlotConfigEditor(container, config, options = {}) {
             section('Subplot', field('Title', textInput(sp.displayName, (v) => { sp.displayName = v; notify(); },
                                                         { placeholder: 'Untitled' }))),
             section('Display', ...displayFields(sp)),
-            section('X axis', ...xAxisFields(sp)),
+            hidden.has('xAxis') ? null : section('X axis', ...xAxisFields(sp)),
             section('Y axes', yAxesEditor(sp, is3D, overlaySources)),
-            is3D ? section('Z axis', ...zAxisFields(sp)) : null,
+            is3D && !hidden.has('3d') ? section('Z axis', ...zAxisFields(sp)) : null,
             section('Reference lines', referenceLinesEditor(sp)),
             section('Shaded bands', shadedBandsEditor(sp)),
             transformsSection(sp),
@@ -414,7 +435,7 @@ function renderPlotConfigEditor(container, config, options = {}) {
 
     function displayFields(sp) {
         return [
-            field('Chart type', select(CHART_TYPE_OPTIONS, sp.chartType ?? 'line', (v) => {
+            field('Chart type', select(hidden.has('3d') ? CHART_TYPES_2D : CHART_TYPE_OPTIONS, sp.chartType ?? 'line', (v) => {
                 const was3D = is3DChart(sp.chartType);
                 sp.chartType = v;
                 const now3D = is3DChart(v);
@@ -543,9 +564,11 @@ function renderPlotConfigEditor(container, config, options = {}) {
             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 (!hidden.has('stackGroup')) {
+            fields.appendChild(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);
@@ -655,6 +678,67 @@ function renderPlotConfigEditor(container, config, options = {}) {
         return wrap;
     }
 
+    /**
+     * A reference line's value as a number or a constant's name. What was typed
+     * settles on change, on Enter or Tab, or on a pick; a typed number stays a number
+     * even when it is part of a constant's name, so Enter does not take that row.
+     */
+    function constantValueField(line) {
+        const wrap = el('div', 'twm-plot-config__constant');
+        const input = el('input', 'twm-plot-config__input');
+        input.type = 'text';
+        input.spellcheck = false;
+        input.placeholder = 'Number or name';
+        input.setAttribute('aria-label', 'Value');
+        input.value = line.value ?? '';
+        const now = el('span', 'twm-plot-config__constant-value');
+        wrap.append(input, now);
+
+        const isNumber = (text) => text !== '' && Number.isFinite(Number(text));
+        const sayValue = () => {
+            const named = opts.constantsProvider().find((c) => c.name === input.value.trim());
+            now.textContent = named ? `= ${named.value}` : '';
+        };
+        const settle = () => {
+            const text = input.value.trim();
+            const next = isNumber(text) ? Number(text) : text || null;
+            sayValue();
+            if (next === (line.value ?? null)) return;
+            line.value = next;
+            notify();
+        };
+        const offered = (query) => {
+            const words = (query ?? '').trim().toLowerCase();
+            const groups = new Map();
+            for (const c of opts.constantsProvider()) {
+                const text = c.label ?? c.name;
+                if (words && !`${c.name} ${text}`.toLowerCase().includes(words)) continue;
+                if (!groups.has(c.group)) groups.set(c.group, []);
+                groups.get(c.group).push({ value: c.name, label: text, hint: `= ${c.value}` });
+            }
+            return [...groups].flatMap(([group, rows]) => (group ? [{ group, options: rows }] : rows));
+        };
+        const list = attachInputOptions(input, {
+            options: offered,
+            debounce: 0,
+            autoHighlight: true,
+            isCandidate: (typed) => isNumber(typed.trim()),
+            openOnFocus: true,
+            isCurrent: (option) => option.value === input.value.trim(),
+            onPick: (option) => {
+                input.value = option.value;
+                settle();
+            },
+            onSettle: settle,
+        });
+        input.addEventListener('change', settle);
+        // After the list's own keys, which take Enter while a row is active.
+        input.addEventListener('keydown', (event) => { if (event.key === 'Enter') settle(); });
+        track(() => list.destroy());
+        sayValue();
+        return wrap;
+    }
+
     function referenceLinesEditor(sp) {
         const axisOptions = sp.yAxes.map((a, i) => ({ value: a.id, label: a.label || `Y axis ${i + 1}` }));
         return listEditor(sp, 'referenceLines', {
@@ -663,7 +747,9 @@ function renderPlotConfigEditor(container, config, options = {}) {
             fields: (line) => [
                 select(axisOptions, line.yAxisId ?? sp.yAxes[0].id, (v) => { line.yAxisId = v; notify(); },
                        { label: 'Axis' }),
-                numberInput(line.value, (v) => { line.value = v; notify(); }, { placeholder: 'Value', label: 'Value' }),
+                opts.constantsProvider
+                    ? constantValueField(line)
+                    : numberInput(line.value, (v) => { line.value = v; notify(); }, { placeholder: 'Value', label: 'Value' }),
                 textInput(line.label, (v) => { line.label = v; notify(); }, { placeholder: 'Label', label: 'Label' }),
                 colorField(line.color, (v) => { if (v) line.color = v; else delete line.color; }, 'Colour'),
                 select(DASHES, line.lineStyle ?? 'dashed', (v) => { line.lineStyle = v; notify(); }, { label: 'Dash' }),

package/src/charts/plot_grid.js

@@ -91,6 +91,9 @@ function emptyMessageFor(message, subplot, results, index) {
  * @param {Object} [options]
  * @param {Function} [options.resolveSeries] - `(series, results, subplot) => { y, x? } | null`;
  *        default resolveSeriesData. Also resolves the x variable, as `{ variable }`.
+ * @param {Function} [options.resolveConstant] - `(name) => number | undefined`: the value of a
+ *        reference line that stores a name (renderPlotConfigEditor's `constantsProvider`),
+ *        asked at each draw. A name it does not know draws no line; so does any name without it.
  * @param {Object} [options.overlays] - `{ [series.id]: { years, values } }`, drawn for
  *        every series with an `overlay` description.
  * @param {Object} [options.seriesTransforms] - `{ [id]: transform }` (series_transforms.js).
@@ -326,7 +329,9 @@ function renderPlotGrid(container, plotConfig, results, options = {}) {
             ? 'top' : (sp.legendPosition ?? 'hidden');
         const xRange = !useX && time.length >= 2 ? [time[0], time[time.length - 1]] : undefined;
         const { shapes, annotations } = buildOverlayShapes({
-            referenceLines: sp.referenceLines,
+            referenceLines: (sp.referenceLines ?? []).map((line) => (typeof line.value === 'string'
+                ? { ...line, value: opts.resolveConstant?.(line.value) }
+                : line)),
             shadedBands: sp.shadedBands,
             yRefByAxisId,
         });

package/src/flow/kit/settings_panel.js

@@ -50,13 +50,20 @@ const TITLE = 'data-twm-flow-title';
  * @param {string} [o.valuesNote]            the picker's footer sentence
  * @param {(step: object) => object[]|null} [o.columns]  a step's input columns (a data flow)
  * @param {HTMLElement} [o.host]             appended here when given
+ * @param {'card'|'sheet'} [o.variant]       'card' (the default): a raised panel, its header above
+ *        its fields. 'sheet': flat, one section of a page of them — the title and the description
+ *        in a margin at the left, the fields beside them, a rule between two sheets (0.18.2)
  */
 export function createSettingsPanel({ widgets, references = {}, strings = null, services = null, readOnly = false,
                                       onChange = null, onRename = null, onFocusLost = null, values = null,
-                                      valuesNote = null, columns = null, host = null } = {}) {
+                                      valuesNote = null, columns = null, host = null, variant = 'card' } = {}) {
     if (!widgets?.get) throw new Error('createSettingsPanel needs a widget registry (createWidgetRegistry()).');
+    if (variant !== 'card' && variant !== 'sheet') {
+        throw new Error(`createSettingsPanel's variant is 'card' or 'sheet', not ${JSON.stringify(variant)}.`);
+    }
+    const sheet = variant === 'sheet';
     const S = createStrings(strings);
-    const root = el('section', 'twm-flow-panel');
+    const root = el('section', sheet ? 'twm-flow-panel twm-flow-panel--sheet' : 'twm-flow-panel');
     root.setAttribute('role', 'region');
     root.setAttribute('aria-label', say(S, 'settings'));
     if (host) host.appendChild(root);
@@ -167,15 +174,23 @@ export function createSettingsPanel({ widgets, references = {}, strings = null,
         root.replaceChildren();
         if (!spec) return;
         if (isReadOnly() && readOnlyReason()) root.appendChild(el('p', 'twm-flow-panel__readonly', readOnlyReason()));
-        root.appendChild(paintHeader());
-        if (spec.description) root.appendChild(el('p', 'twm-flow-panel__description', spec.description));
-        if (spec.idLine) root.appendChild(el('div', 'twm-flow-panel__id', spec.idLine));
+        // A sheet sets the header and the description in its margin, the rest beside them
+        const margin = sheet ? el('div', 'twm-flow-panel__margin') : root;
+        const body = sheet ? el('div', 'twm-flow-panel__body') : root;
+        if (sheet) {
+            const grid = el('div', 'twm-flow-panel__sheet');
+            grid.append(margin, body);
+            root.appendChild(grid);
+        }
+        margin.appendChild(paintHeader());
+        if (spec.description) margin.appendChild(el('p', 'twm-flow-panel__description', spec.description));
+        if (spec.idLine) body.appendChild(el('div', 'twm-flow-panel__id', spec.idLine));
         findingsBox = el('ul', 'twm-flow-panel__findings');
         findingsBox.hidden = true;
-        root.appendChild(findingsBox);
+        body.appendChild(findingsBox);
         slotBefore = el('div', 'twm-flow-panel__slot');
         slotBefore.dataset.slot = 'before';
-        root.appendChild(slotBefore);
+        body.appendChild(slotBefore);
 
         const list = el('div', 'twm-flow-panel__fields');
         allFields = Array.isArray(spec.fields) ? spec.fields : fieldsFromSchema(spec.type?.config_schema);
@@ -213,10 +228,10 @@ export function createSettingsPanel({ widgets, references = {}, strings = null,
             const anchor = placed(e);
             if (anchor === null || !keys.has(anchor)) drawExtra(e);
         }
-        root.appendChild(list);
+        body.appendChild(list);
         slotAfter = el('div', 'twm-flow-panel__slot');
         slotAfter.dataset.slot = 'after';
-        root.appendChild(slotAfter);
+        body.appendChild(slotAfter);
         paintSlots();
         applyFindings();
     }