flexdesk 0.17.14 → 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

@@ -230,18 +230,35 @@ openForm({
   row hidden by `setVisible` drops its bounds until it is shown again, as it
   drops `required`. As with any `<input type="number">`, a `min` is also where
   `step` counts from.
-- **`{ row: [field, ...] }`** puts its fields on one line, sharing the width.
+- **`{ row: [field, ...] }`** puts its fields on one line; their inputs share
+  what the labels leave equally (see below).
   The row is layout only and has no name: each field in it is an ordinary
   field with its own label, hint, error, `setVisible`, value and submitted
   key, so hiding one hides only that one. The first keeps the form's label
   column; the others size their label to its text. A form narrower than
   360px stacks them (a container query, `twm-form`, on a form that has a row;
   a form without one is not made a container). A form with a row opens at the
-  wide (640px) layout. The row is `.twm-modal__field-group`.
+  wide (640px) layout, or wider for a row of three or more fields (below).
+  The row is `.twm-modal__field-group`.
 
 A form with neither renders exactly as before.
 `tests/open_form_rows_bounds.test.mjs` covers both in jsdom.
 
+### The inputs of a row are equally wide (0.17.15)
+
+Every input in a `{ row }` gets the same width: each field takes its label's
+width (the first one the form's 130px label column), and what is left of the
+row is shared equally between the inputs. The share is equal up to each
+control's own padding and border: a native `<input>` or `<textarea>` keeps its
+~18px, a select, toggle or picker (which sit in a padding-less slot) does not,
+so in a row that mixes the two the native input is that much wider. A form
+whose widest row has three or more fields opens wider: `170 + 230 × fields` px
+(860px for three, 1090px for four), at least 640px, otherwise at most 90% of the
+window; forms without such a row open as before. Until 0.17.14 every field was
+an equal share of the row, including the first one's label column, so its input
+was a sliver beside the others: about 15px for the first of four number fields
+in a 640px form (BUG-0050).
+
 ### A switch: `ToggleField` and `type: 'toggle'` (0.17.0)
 
 ```js
@@ -292,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

@@ -155,6 +155,58 @@ content: {
 chrome shows only — the tree, the tab labels and the saved layout are left
 alone — and a call from content whose pane has since been rebuilt does nothing.
 
+## A tile breadcrumb of one segment is not drawn (0.17.15)
+
+`mountTileBreadcrumb` (and the page shell around a content, which mounts one)
+draws the path to where a tile is: an optional root crumb, the top-nav page,
+the trail, the entity's ancestors and the entity. When that path is a single
+segment (or none), for instance a top-nav page with no root crumb, no trail and
+no entity, or an `appGlobal` kind, the strip says nothing the tile's own title
+bar does not already say. It is then `hidden`, and
+`.twm-page-shell__breadcrumb` around it takes no room, so the tile's content
+starts right under its title. `refresh()` shows the strip again as soon as the
+path has two segments; a path of two or more is drawn as before. Until 0.17.14
+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/slide-out-panel.md

@@ -66,3 +66,18 @@ Until 0.17.4 a panel in a narrow tile reached past the tile's left edge across
 the neighbouring pane, and neither icon had a size of its own: both took
 whatever the page's global icon size was. `tests/slide_out_panel_clamp.test.mjs`
 holds it.
+
+## Never drawn outside its box (0.17.15)
+
+While it is open the panel is `position: fixed`, pinned to its host's right
+edge, so the host's `overflow: hidden` no longer clips it. Until 0.17.14 it
+slid in (and out) by `translateX(100%)` and, on the way, was drawn across
+whatever lies right of the host: a dock panel, an inspector. It no longer
+moves: a clip alone carries the motion, revealing it from its right edge
+leftwards (`clip-path: inset(0 0 0 100%)` closed, `inset(0 0 0 -16px)` open,
+200ms ease-out), so no frame paints outside its final box, which lies inside
+the host. No transform is animated beside the clip: the two could drift apart,
+the transform often running on the compositor. The left inset of -16px keeps
+the panel's shadow; when the panel is as wide as its host (BUG-0035's cap)
+that shadow falls on the neighbouring pane, as before. Nothing changes for
+callers (BUG-0051).

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.14",
+    "version": "0.17.16",
     "description": "A tiling window manager and widget set for desktop-class web applications. Zero runtime dependencies.",
     "license": "MIT",
     "repository": {