flexdesk 0.17.3 → 0.17.4

package/docs/components/panels-and-desktops.md

@@ -0,0 +1,127 @@
+# Panels and desktops
+
+> **Package:** `@flexdesk/wm` · **See also:** [Shell and navigation](shell.md) · [All docs](../README.md)
+
+The shell's left, right and bottom panels, and its virtual desktops. A kind says which panels a page offers; each desktop remembers how large the user dragged them; `mountNavPanel` builds a navigation panel you can drive from code; and an app that keeps desktops of its own can mark them so the desktop bar treats them as the app's.
+
+**On this page**
+
+- [Panels a page does not offer (0.17.0)](#panels-a-page-does-not-offer-0170)
+- [Panels keep the size you dragged them to (0.17.0)](#panels-keep-the-size-you-dragged-them-to-0170)
+- [A navigation panel you drive yourself: `mountNavPanel` (0.17.0)](#a-navigation-panel-you-drive-yourself-mountnavpanel-0170)
+- [Your desktops beside the app's (0.10.0)](#your-desktops-beside-the-apps-0100)
+
+## Panels a page does not offer (0.17.0)
+
+A kind says which panels it offers while it is the primary tile. Each side is
+`true`, `false` or `{ reason }`; a side it does not name is offered, and a kind
+that does not name a side takes it from its top-nav kind, so one declaration on
+a page covers every record opened under it:
+
+```js
+kinds: {
+    paper: { label: 'Paper', isTopNav: true, panels: { bottom: { reason: 'No console here' } } },
+    sheet: { label: 'Sheet', topNav: 'paper' },                        // withholds it too
+    slide: { label: 'Slide', topNav: 'paper', panels: { bottom: true } }, // offers it
+},
+```
+
+While a panel is withheld it is not in the layout, `wm.togglePanel(side)`
+answers `false` and changes nothing (nor what is saved), `wm.isPanelOpen(side)`
+is `false`, and the shell's toggle button and the palette chip carry
+`aria-disabled="true"` with the reason as their tooltip (`data-tooltip` on a
+`twm-has-tooltip` button, `title` otherwise; the button's own comes back after).
+The desktop still remembers the panel was open, and it comes back open when the
+user returns to a page that offers it. With no declarations every panel is
+offered, exactly as before.
+
+Content overrides its kind at runtime, until it clears the override with `null`:
+
+```js
+ctx.wm.setPanelAvailability('bottom', { reason: 'Run the model first' });
+ctx.wm.setPanelAvailability('bottom', null);           // e.g. in destroy()
+```
+
+`wm.isPanelAvailable(side)` and `wm.getPanelAvailability(side)` (`{ available,
+reason }`) read it, and a change is announced once — whatever caused it and
+however many sides it moved — to `wm.onPanelAvailabilityChange(fn)` (which
+returns the unsubscribe) and on the bus as `wm:panels:availability`, both with
+`{ panels, changed }`. `togglePanel` now answers `true` when it flipped a panel.
+
+`PanelStateMachine`, `PANEL_STATES` and `PANEL_TRANSITIONS` are gone from
+`@flexdesk/widgets`: nothing in the library used them, and which panels a page
+offers is now said once, in the taxonomy.
+
+`tests/panel_availability.test.mjs` drives all of it against a real shell.
+
+## Panels keep the size you dragged them to (0.17.0)
+
+Each desktop remembers every panel's share of the window-manager area along
+its axis (width for left and right, height for bottom), taken when a splitter
+drag ends, and saves it with the layout as `panelShares`. A reload, a switch to
+another desktop and back, and toggling one panel all rebuild the panels at
+those shares, and a closed panel comes back at the size it had. Only a panel
+that has never been sized on that desktop opens at the default 1:4. No split is
+built tighter than a drag allows (`TileRenderer.MIN_SLOT_FRACTION` of it per
+slot). A `TileRenderer` built by hand takes `onSplitResized(splitId)`, called
+once when a drag that changed a split's sizes ends.
+
+`tests/panel_sizes_kept.test.mjs` covers each of these.
+
+## A navigation panel you drive yourself: `mountNavPanel` (0.17.0)
+
+`mountNavPanel(hostEl, { modes })` (from `@flexdesk/wm`) builds a mode strip, a
+shared filter box and one lazily-mounted pane per mode. A strip click is no
+longer the only way to switch: the handle's `select(modeId)` takes the same
+path — it mounts the mode on first use, runs its `activate()`, restores that
+mode's filter text — and its promise resolves once `activate()` has run. An
+unknown id is ignored. `active()` names the mode shown.
+
+```js
+const nav = mountNavPanel(hostEl, {
+    modes: [
+        { id: 'files',  icon: 'folder',   label: 'Files',  mount: mountFiles },
+        { id: 'runs',   icon: 'history',  label: 'Runs',   mount: mountRuns,
+          filter: false },                // a pane with controls of its own
+    ],
+    showModeStrip: false,   // no strip: the app switches with select()
+    initialMode: 'runs',    // the mode shown at mount (default: the first)
+});
+await nav.select('files');  // mounted and activated
+nav.active();               // 'files'
+```
+
+A mode with `filter: false` hides the filter box while it is active, and its
+pane is never handed a query; the next mode with a filter shows its own saved
+text again. `showFilter: false` renders no filter box at all. All three options
+default to the old behaviour, so a panel built without them renders exactly as
+before.
+
+## Your desktops beside the app's (0.10.0)
+
+Pass `chrome.desktops` and the shell paints a desktop bar: a chip per desktop
+and a `+`. An app that keeps desktops of its own (one per page, say) marks them
+on the desktop objects themselves:
+
+```js
+const shell = await createShell({ /* … */ eventBus,
+    chrome: { desktops: barEl }, desktopBar: { switchOnAdd: true } });
+shell.wm.desktops.ensureCount(pages.length);
+shell.wm.desktops.desktops.slice(0, pages.length)
+    .forEach((d) => { d.group = 'Workbench'; d.fixed = true; });
+eventBus.emit('wm:changed', {});          // repaint the bar
+```
+
+Desktops that share a **`group`** are one chip, labelled by the group, and one
+stop for Ctrl+Left/Right; the chip goes back to the member that was on screen
+last (`wm.desktops.chips()` says what the bar draws). A **`fixed`** desktop is
+the app's: the bar offers no rename and no delete, no menu offers it as a
+*Move to desktop* target, and `removeDesktop`, `moveFocusedToDesktop` and
+`moveWindowToDesktop` refuse it. Both are persisted. A desktop the user adds is
+numbered among the ungrouped ones, and `desktopBar.switchOnAdd` puts it on
+screen. With neither set anywhere, the bar is what it always was.
+
+*Move to desktop* now carries every tab of the pane and adds them to the target's
+main pane; it used to replace that pane with the active tab alone. A target still
+holding only its seed is replaced, as before. `dispose()` removes the bar, so a
+rebuilt shell paints a fresh one.

package/docs/components/record-list-and-fact-table.md

@@ -0,0 +1,128 @@
+# Record lists and fact sheets
+
+> **Package:** `@flexdesk/widgets` · **For a table of rows:** [DataTable](data-table.md) · [All docs](../README.md)
+
+Two read-only components for the parts of an application page that are not a table of rows. `createRecordList` draws a list of a few records, each a name with a quiet line of facts, pills and verbs beside them, and a state. `createFactTable` draws a sheet of facts, a name and its value row after row, and can show a before and an after. Neither needs a height: each is as tall as its contents, in any parent.
+
+## Record lists and fact sheets (0.7.0)
+
+Two read-only components for the parts of an application page that are not a
+table of rows. Both are new: nothing that exists changes, and a page that does
+not call them looks as it did. Neither needs a height: each is exactly as tall
+as its contents, in any parent.
+
+**`createRecordList(host, config)`** draws a list of records, each as a name
+with a quiet line of facts under it, pills and verbs beside them, and a state.
+It is for the administration list of a few records with their own actions
+(keys, connections, deliveries, members), where a table would be the wrong
+shape.
+
+```js
+import { createRecordList } from '@flexdesk/widgets';
+
+const list = createRecordList(host, {
+    records: keys,
+    describe: (k) => ({
+        name: k.name,
+        facts: [k.key_id, k.role, k.expires ? `expires ${k.expires}` : 'never expires'],
+        pills: [k.paused ? { text: 'paused', tone: 'warn' } : { text: 'live', tone: 'success' }],
+        state: k.revoked ? 'off' : k.paused ? 'paused' : 'active',
+        verbs: [
+            { label: k.paused ? 'Resume' : 'Pause', onClick: (key) => toggle(key),
+              refusal: k.revoked ? 'This key is revoked.' : null },
+            { label: 'Revoke', danger: true, onClick: (key) => revoke(key) },
+        ],
+    }),
+    getKey: (k) => k.key_id,
+    rowAttrs: (k) => ({ 'data-key-id': k.key_id }),
+    onActivate: (k) => open(k),        // one click, or Enter
+    activeKey: openKeyId,
+    emptyState: 'No keys yet.',
+});
+list.setRecords(next);                 // focus stays on the same record's same verb
+```
+
+What `describe(record, idx)` returns (without `describe`, each record is
+this object itself):
+
+| Field | What it is |
+|---|---|
+| `name` | The first line: text or a node. `mono: true` draws it in the monospace face. |
+| `facts` | The quiet line: text, a node, or an array whose `null`, `false` and `''` parts are left out and the rest joined with `factSeparator` (`' — '`). A part may be a node. |
+| `pills` | Strings or `{ text, tone, title }`. The tones drawn are `muted`, `info`, `success`, `warn` and `danger`. |
+| `verbs` | `{ label, onClick(record, ev), refusal, danger, primary, icon, title, name }`. A verb with a `refusal` is a disabled button with the reason on its `title` and `data-refusal`, **and the reason is a line of text under the facts** (`twm-record__refusal`, named by `data-refusal-for`, which the button is `aria-describedby`). A reason shared by every verb is said once. `null` and `false` verbs are left out. |
+| `state` | A word: `data-state` and `twm-record--state-<word>` on the row. `paused`, `off` and `dead` dim the words and pills but never the verbs; `dead` and `error` mark the left edge in the danger colour. |
+| `error` | A line in the error colour under the facts. |
+| `key` | The record's key, over `getKey`. |
+
+| Option | What it does |
+|---|---|
+| `getKey(record, idx)` | The key (`data-record-key`). Defaults to `spec.key`, then `record.key`, then `record.id`, then the index. Keys compare as strings. |
+| `onActivate(record, idx, ev)` | Opens a record. It follows `DataTable`'s `onRowActivate` rule (`row_activation.js`): not for a press on a verb or any control, not for the click that ends a drag selecting text in the list, not for the second click of a double-click. Rows get a pointer and a hover. |
+| `activateOn` | `'click'`, `'dblclick'`, `'enter'`, or an array. Default `['click', 'enter']`. |
+| `keyboard` | Defaults to on exactly when `onActivate` is set. The records are then one tab stop (the last focused, else the open one, else the first), each enabled verb keeps its own, ArrowUp/ArrowDown move between records (from a record or one of its verbs), Home/End go to the ends, and Enter on a record opens it. |
+| `activeKey`, `setActiveKey(key)`, `getActiveKey()` | The record that is open: `twm-record--active` and `aria-current="true"`, drawn as an accent on the left edge. It survives `setRecords`. |
+| `rowClass(record, idx)`, `rowAttrs(record, idx)` | Classes and attributes for the record's `<li>`, as `DataTable`'s (`null`/`false` leaves an attribute off, `true` sets it empty). |
+| `emptyState` | Text, a node, or a function returning either, shown when there are no records. |
+| `facts: 'ellipsis'` | Keeps every fact line to one line and puts the whole line on its `title`. By default a long fact line wraps. |
+| `verbClass` | A class string, or `(verb) => string`, for a consumer with its own buttons. By default verbs are FlexDesk's `twm-btn`, with `--primary` and `--danger`. |
+| `label`, `className` | The list's `aria-label`; a class on the root. |
+
+Methods: `setRecords(records)` (keeps the focus on the same record's same verb,
+by key), `getRecords()`, `refresh(key)` (asks `describe` again for that record
+only; with no key, all), `getItem(key)`, `focusRecord(key)`, `dispose()`, and
+`element` (the root).
+
+**`createFactTable(host, config)`** draws a sheet of facts: a name and its
+value, row after row. A `DataTable` is the wrong tool for this, because it
+draws a header row, clips a long value to one line and needs a box with a
+height. A fact sheet has no header row, never truncates (a value wraps at
+spaces, inside a long word or URL when it must, and keeps its own line breaks),
+and is as tall as its rows. The label column stays on one line.
+
+```js
+import { createFactTable } from '@flexdesk/widgets';
+
+createFactTable(host, {
+    rows: [
+        { label: 'Server', value: 'db-main-01.internal' },
+        { label: 'Connection string', value: dsn, mono: true },
+        { label: 'Options', value: { pool: { min: 2, max: 16 } } },   // drawn as indented JSON
+        { label: 'Replica', value: null },
+    ],
+    nullDisplay: '—',
+});
+
+// Before and after:
+createFactTable(host, {
+    compare: true,
+    headers: ['Field', 'Now', 'After the restore'],
+    rows: [{ label: 'Amount', before: 1200, after: 950 }, { label: 'Reviewer', after: 'Bea Beta' }],
+});
+```
+
+| Option | What it does |
+|---|---|
+| `rows` | Objects `{ label, value }` (or `{ label, before, after }` with `compare`), with optional `mono`, `numeric`, `labelTitle` (a tooltip on the label), `key` (`data-key`) and `status`; or arrays of cells, `[label, value, …]`. A value is text, a number, a node, or an object (drawn as indented JSON). |
+| `compare: true` | Each row draws its label, its before, an arrow and its after. A row is `twm-facts__row--changed`, `--same`, `--added` (no `before`) or `--removed` (no `after`), worked out from the two sides (objects by their JSON, a node always changed) unless the row's `status` says otherwise; `data-status` says the same. An absent side reads as `missing` (`'—'`). A row with a plain `value` spans both sides. |
+| `headers` | Adds a header row (there is none by default). With `compare`, three names stand over the label, before and after columns. |
+| `numeric` | Column indices drawn in tabular numerals (`twm-facts__num`), header included. |
+| `mono` | Every value in the monospace face. A row's own `mono` does it for that row. |
+| `nullDisplay` | What `null` and `undefined` read as (`twm-facts__null`). By default the cell is empty. |
+| `labelColumn: false` | The first column is ordinary data, not a label. |
+| `wrapLabels: true` | Lets a long label wrap. |
+| `wrap` | How a value wraps. `'anywhere'` (the default) wraps at spaces, and inside a long word or URL when it must. `'words'` wraps at spaces only, so a long word stays whole and the sheet grows wider; use it inside a sideways scroller. `'none'` keeps only the value's own line breaks. |
+| `rowClass(row, idx)`, `rowAttrs(row, idx)` | Classes and attributes for each `<tr>`. |
+| `emptyState`, `label`, `className` | Shown (spanning the sheet) when there are no rows; the `aria-label`; a class on the `<table>`. |
+
+Methods: `setRows(rows)`, `getRows()`, `getRow(idx)` (the `<tr>`), `dispose()`,
+and `element` (the `<table>`).
+
+Both were measured in headless Edge with real input (`demo/records.html`,
+driven by `demo/records_probe.mjs`): no list, record, sheet or row has zero
+height and none overflows its card; a long fact line, a long URL, a connection
+string and a JSON value wrap inside their column while labels stay on one line;
+every verb, refused ones included, is what `elementFromPoint` finds at its
+centre, and a real press runs it without opening the record; real Tab,
+ArrowDown and Enter open a record; at 300px the verbs go under the record's
+words, inside the card.

package/docs/components/settings-view.md

@@ -0,0 +1,112 @@
+# Settings page
+
+> **Package:** `@flexdesk/widgets` (the store is in `@flexdesk/core`) · [All docs](../README.md)
+
+`SettingsView` draws a settings store's schema as a page: a category list, a filter, and the settings themselves. `SettingsCategories` draws the sidebar parts for a view somewhere else, such as an app's left navigation. Where the settings are *saved* is a separate choice, covered under [storage keys](../concepts/domain-neutrality.md#storage-keys-and-names-are-yours-0170).
+
+## A settings page: `SettingsView` (0.17.0)
+
+`new SettingsView({ store, eventBus })` (in `@flexdesk/widgets`) draws a
+settings store's schema as a page. `store` is a `createSettingsStore()` handle
+or the app-global binding's own, `getSettingsStore()` from `@flexdesk/core`
+(its `set` is the one `setSetting` calls); `eventBus` is the bus that store
+emits on (`registerSettingsEventBus(bus)` for the binding).
+
+```js
+import { getSettingsStore, registerSettingsEventBus } from '@flexdesk/core';
+import { SettingsView, settingsViewContent } from '@flexdesk/widgets';
+
+registerSettingsEventBus(bus);
+const view = new SettingsView({ store: getSettingsStore(), eventBus: bus });
+view.mount(host);
+view.selectCategory('window');
+view.setQuery('shadow');        // what the filter box does
+await view.resetAll();           // asks first; true when it reset
+view.dispose();
+
+// or as tile content (props.category picks the category shown first):
+createShell({ content: { settings: settingsViewContent({ store: getSettingsStore(), eventBus: bus }) } });
+```
+
+The sidebar holds a filter box, every category in `CategoryDef.order` and
+*Reset all*. Beside it the chosen category's settings are listed under its
+title, description and *Reset category*, grouped by `SettingDef.group` in
+schema order. A row shows the label, a *Modified* marker while the value
+differs from its default, the description, the path, its control and a reset
+button. Text in the filter searches every category's labels, descriptions and
+paths; the matches are listed under "Category › Group", and choosing a
+category clears it.
+
+| `type` | Control |
+| --- | --- |
+| `boolean` | a `ToggleField` |
+| `select` | a select over `options`; a value the options lack (stored, or set elsewhere while the view is open) is kept and shown as *value (not found)* |
+| `number` | a number box with `min`, `max` and `step`; a written value is always in the range and on the step grid (`min + k·step`, or `k·step` with no `min`): snapped to the nearest grid point, and one outside the range moved inward to the nearest grid point inside it (with `max` below `min` the range holds none, and the value is `min`); with no `step` it is only clamped; an empty or unreadable box goes back to the value |
+| `text` | a text box, written `textDebounceMs` (default `SETTINGS_TEXT_DEBOUNCE_MS`, 300) after the last keystroke, or at once on Enter or blur; emptied, it writes `null` when the default is `null` |
+| `colorList` | a `ColorListField`, written on each committed edit while every row holds a colour |
+
+A type it does not know shows the value as text, read only.
+
+The view is live both ways: a control writes with `store.set`, and the view
+listens for `settings:<path>:changed` on every schema path, `settings:changed`
+with a null path (the resets) and `settings:registered`, which the store now
+emits from `extend()` / `registerSettings()` with `{ paths, categories }`. So a
+`setSetting` made anywhere moves the open view, and a slice registered after
+mount adds its categories and rows without a remount. A row's reset button
+resets that one setting; *Reset category* and *Reset all* first ask
+`confirm({ title, message, confirmLabel, danger })` (default `openConfirm`) and
+change nothing unless it resolves true. Every label, description, category name
+and query is set as text, so markup in any of them is shown as typed.
+
+Options: `store`, `eventBus` (both required), `confirm`, `category`,
+`textDebounceMs`, `title` (the sidebar heading, and the content factory's tab
+title; default "Settings"). The markup is `.twm-settings` >
+`.twm-settings__sidebar` + `.twm-settings__content`, with rows
+`.twm-settings__row` (`--modified`); `flexdesk.css` styles it from tokens.
+`tests/settings_view.test.mjs` covers it in jsdom.
+
+## The settings categories outside the page: `SettingsCategories` (0.17.2)
+
+A `SettingsView` made with `sidebar: false` draws no sidebar: no heading, no
+filter box, no category list and no *Reset all*, only the chosen category's
+settings (or the filter's matches). `new SettingsCategories({ view })` (in
+`@flexdesk/widgets`) draws those parts for that view wherever it is mounted,
+for example in an app's left navigator:
+
+```js
+import { SettingsView, SettingsCategories } from '@flexdesk/widgets';
+
+const view = new SettingsView({ store, eventBus: bus, sidebar: false });
+view.mount(pageHost);
+const cats = new SettingsCategories({ view });
+cats.mount(navigatorHost);
+
+const off = view.subscribe(({ category, query }) => { /* e.g. a tab title */ });
+// …
+off();
+cats.dispose();
+view.dispose();
+```
+
+It keeps no state of its own. Typing in its filter box is `view.setQuery()`,
+clicking a category is `view.selectCategory()` and its *Reset all* is
+`view.resetAll()`, which asks the view's `confirm` first and changes nothing
+unless it resolves true. It redraws from the view whenever the view's category,
+filter or registered categories change, so the two agree whichever side moved
+them: `view.selectCategory('window')` marks that category in the list, and
+`view.setQuery('shadow')` puts the text in its filter box. As in the view's own
+sidebar, choosing a category clears the filter, and no category is marked while
+the filter is in effect. Its clicks and keystrokes act once the view is mounted.
+
+Two methods on `SettingsView` serve it and anything else that follows the view:
+`subscribe(fn)` calls `fn({ category, query })` after each such change and
+answers the unsubscribe; `isFiltering()` is true while the filter's trimmed
+text is not empty. `settingsViewContent({ …, sidebar: false })` passes the
+option through. A view made without `sidebar` (or with `sidebar: true`) draws
+exactly as in 0.17.1.
+
+The markup is `.twm-settings-categories` > `.twm-settings__search`,
+`.twm-settings__nav` (`button.twm-settings__cat`, `--active`) and
+`.twm-settings__reset-all`, the same parts and classes as the sidebar's;
+`flexdesk.css` styles it, leaving its width and padding to the host.
+`tests/settings_view.test.mjs` §11–§14 cover it.

package/docs/components/shell.md

@@ -0,0 +1,189 @@
+# Shell and navigation
+
+> **Package:** `@flexdesk/wm` · **Next:** [Panels and desktops](panels-and-desktops.md), [Command palette](command-palette.md), [Keys, Back and tab layout](keymap.md) · [All docs](../README.md)
+
+`createShell` boots the tiling window manager into an element of your page: tiles that split and tab, the top navigation, dockable panels, virtual desktops and the command palette. It knows nothing about your domain. You give it a taxonomy of *kinds*, a content factory for each kind and a [host](../concepts/host-port.md), and it draws and persists the rest.
+
+A complete first boot is in the [quickstart](../quickstart.md#hello-shell). This page covers what you can add to it: the opt-in shell features, kinds that exist only once, what happens when a link names a kind nobody registered, and what a pane can tell its own chrome.
+
+**On this page**
+
+- [Opt-in shell features](#opt-in-shell-features)
+- [A kind that exists once: `single` (0.17.0)](#a-kind-that-exists-once-single-0170)
+- [An open single instance takes new props: `navigate(props)` (0.17.2)](#an-open-single-instance-takes-new-props-navigateprops-0172)
+- [A link to a kind nobody registered (0.17.2)](#a-link-to-a-kind-nobody-registered-0172)
+- [A pane that names what it shows: `ctx.setTitle` (0.12.1)](#a-pane-that-names-what-it-shows-ctxsettitle-0121)
+- [Buttons that change with the pane: `ctx.setChromeActions` (0.17.0)](#buttons-that-change-with-the-pane-ctxsetchromeactions-0170)
+
+## Opt-in shell features
+
+These change what the user sees, so all of them are off until you ask:
+
+```js
+await createShell({
+    // …everything above…
+    snapPromotion: true,     // drag a floating window onto a tile: it snaps, and docks back in
+    promoteInPlace: true,    // a window floated out of a tile stays inside that tile's pane
+    backToOpenList: true,    // Back in a record opened beside its list closes onto that list
+    floatActiveTab: true,    // floating a tile takes the tab on screen, not the whole pane
+    tabLayout: 'header',     // tabs in the tile header, in place of its title, with a + (0.8.0)
+    newTabButton: false,     // …and without the + (0.8.1)
+    chrome: {
+        topNav: document.getElementById('nav'),
+        zoom:   document.getElementById('status-bar'),   // content zoom, 50–200%
+    },
+});
+```
+
+## A kind that exists once: `single` (0.17.0)
+
+Some content holds heavy app-wide state and must not be mounted twice. Mark its
+kind `single` in the taxonomy:
+
+```js
+createTaxonomy({
+    root: 'cosmos',
+    kinds: {
+        cosmos:      { label: 'Cosmos', isTopNav: true },
+        observatory: { label: 'Observatory', isTopNav: true, single: true },  // one, ever
+        planet:      { label: 'Planet', single: 'id' },                       // one per props.id
+    },
+});
+```
+
+- **Every open path reveals the instance that exists** — `navigate`, the top
+  nav, `openInPrimary`, `openInTab*`, `splitLeafWith`, Back. It switches to the
+  desktop it is on, activates its tab (bringing back a top-nav page the tile
+  had switched away from) and focuses its tile, or raises its window. Nothing
+  is mounted twice, and a reveal is one `onChange` / `wm:changed`
+  (`'single-reveal'`), however many steps it took.
+- **A page restore never brings back a copy.** A tile's archived top-nav page
+  can still list an instance that has since moved to another tile or a window;
+  switching back to that page (top nav, `openInPrimary`, Back) leaves it out.
+- **The copy verbs refuse.** Alt+T, Alt+N, Alt+Shift+H/V do nothing; the tile
+  menu's *Open in new tab* and *Open a copy in a window* are greyed with the
+  reason as their tooltip (`taxonomy.singleReason(kind)`); the palette draws its
+  split and window hints greyed, and Ctrl/Shift+Enter on such a row does nothing.
+- **The move verbs still work**: float, dock, drag a tab, move to a desktop.
+- **A restored layout keeps the first** of any duplicates (desktop order, then
+  tile order): the other leaf shows its next tab, or closes if it held nothing
+  else.
+
+The root kind cannot be `single` — every new pane, tab and desktop is seeded
+with it. The taxonomy answers `isSingle(kind)`, `instanceKey(kind, props)` and
+`singleReason(kind)`; the window manager answers `isSingleKind(kind)`,
+`findInstance(kind, props)` and `revealInstance(kind, props)`.
+
+## An open single instance takes new props: `navigate(props)` (0.17.2)
+
+Revealing a `single` instance used to drop the props the open asked for: the
+observatory kept showing the planet it was opened with. A content factory that
+returns a `navigate(props)` hook from its mount is now handed them:
+
+```js
+content: {
+    observatory: (el, props) => {
+        const view = mountObservatory(el, props);
+        return {
+            destroy: () => view.destroy(),
+            navigate: (next) => view.focusPlanet(next.planet),   // already open: go there
+        };
+    },
+},
+
+wm.navigate('observatory', { planet: 'mars' });   // open: revealed, then navigate({ planet: 'mars' })
+```
+
+- **Every open path that reveals the instance calls it once**, after the
+  reveal, with a copy of the new props — `navigate`, the top nav,
+  `openInPrimary`, `openInTab*`, `splitLeafWith`, Back. The same props twice
+  are two calls; nothing is deduplicated, and no second instance is mounted.
+- **The props are recorded on the instance's tab** (or its window's), so a
+  top-nav page restore or a reload mounts it with the latest. The tile is not
+  rebuilt by the write.
+- **An open that names no props only reveals** — the top-nav button,
+  `openInPrimary(kind)`, `navigate(kind)`: it asks to see the instance, not to
+  empty it, so the hook is not called and the tab keeps its props.
+- **A content without the hook is revealed as before**: its tab keeps its props
+  and nothing is called. A hook that throws is a console warning.
+
+## A link to a kind nobody registered (0.17.2)
+
+`wm.navigate(kind, props, opts)` returns `true` once it has routed the
+navigation. A `kind` the shell's `content` map has no factory for is refused
+instead, on every destination (`main`, `origin`, a new tab, a window, a split,
+the legacy `target`):
+
+```js
+if (!wm.navigate(link.kind, link.props)) {
+    // nothing opened: tell the user the link is dead
+}
+```
+
+- **One `console.warn` naming the kind**, per call, and `false` back.
+- **Nothing changes**: no tile, tab, window or desktop, no per-tab history, no
+  `onChange` — and no "no factory registered yet" placeholder tile, which is
+  what such a link used to leave behind.
+- **No exception reaches the caller**, whatever `kind` is (`undefined`, `null`
+  and `''` included).
+
+A shell that only navigates to kinds it registered sees no change; the return
+value is new, so code that ignored it is unaffected. A split destination used
+to hand back the new leaf's id; it now returns `true` like the others — call
+`wm.splitLeafWith(...)` for the id. A restored layout that names an
+unregistered kind still draws its placeholder: only `navigate` refuses.
+
+## A pane that names what it shows: `ctx.setTitle` (0.12.1)
+
+A content factory receives `(hostEl, props, ctx)`, and `ctx` carries, per pane,
+`setTitle(text)`. It renames the pane's chrome title, at mount or any time
+after, and the title survives repaints — including a panel's, whose tree title
+the shell resets to Navigator / Inspector / Console on every layout pass:
+
+```js
+content: {
+    'panel:bottom': (hostEl, props, ctx) => {
+        // …a panel with tabs of its own…
+        const show = (tab) => { /* swap the body */ ctx.setTitle(tab.label); };
+        show(tabs[0]);
+        return { destroy() {} };
+    },
+},
+```
+
+`setTitle(null)` or `''` gives the title back to the tree. It changes what the
+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.
+
+## Buttons that change with the pane: `ctx.setChromeActions` (0.17.0)
+
+A factory may return `chromeActions` — `[{icon, title, onClick}]`, drawn in the
+pane's chrome left of the split/float/close buttons — but those are read once.
+`ctx.setChromeActions(specs)` replaces them at any time, the way `setTitle`
+replaces the title: called during the mount it wins over the returned list, the
+later call wins, the list survives repaints, `null` or `[]` clears it, and a
+call from content whose pane has since been rebuilt does nothing. The content is
+never re-mounted.
+
+```js
+content: {
+    page: (hostEl, props, ctx) => {
+        let wide = false;
+        const paint = () => ctx.setChromeActions([
+            { icon: wide ? 'width_normal' : 'width_wide', title: 'Page width',
+              pressed: wide, onClick: () => { wide = !wide; paint(); } },
+            { separator: true },
+            { icon: 'add', label: 'New', title: 'Add a page', onClick: addPage },
+            { icon: 'publish', title: 'Nothing to publish yet', disabled: true },
+        ]);
+        paint();
+        return { destroy() {} };
+    },
+},
+```
+
+A spec may add **`label`** (text beside the glyph, or instead of it),
+**`pressed`** (`aria-pressed`, plus a pressed style; leave it out for a button
+that is not a toggle), **`disabled`** (greyed and inert, with its tooltip kept —
+it is `aria-disabled`, not the `disabled` attribute) and **`{separator: true}`**
+(a divider). A spec with none of them renders exactly as before.

package/docs/components/slide-out-panel.md

@@ -0,0 +1,68 @@
+# Slide-out panel
+
+> **Package:** `@flexdesk/widgets` · **Used by:** [the tile settings form](tiles.md#a-tiles-settings-as-a-form-mounttileconfigform-0170) · [All docs](../README.md)
+
+`SlideOutPanel` is an inline panel that slides in over its host container from the right edge. A page uses it to show the settings of the element the user picked (a plot, a widget, a node) without taking over the shell's right panel.
+
+## A slide-out panel: `SlideOutPanel`
+
+```js
+import { SlideOutPanel } from '@flexdesk/widgets';
+
+const panel = new SlideOutPanel({ width: 480, onClose: () => commit() });
+panel.mount(hostEl);                               // hostEl: position: relative; overflow: hidden
+
+const body = panel.open('Plot settings', 'tune');  // a title and a Material Symbols icon name
+body.append(settingsForm);                         // you draw the content
+
+panel.close();                                     // or Esc, the × button, or a click outside the panel
+panel.dispose();                                   // closes it if open, then removes it from the host
+```
+
+- **The host.** It must be `position: relative; overflow: hidden`. `mount(host)` adds a transparent, click-catching backdrop and the panel to it. A second `mount` does nothing.
+- **Options.** `width` is in px and defaults to 700. The stylesheet gives the panel `min-width: 400px`, so a smaller width is held at 400, and no width goes past the host's own (see [A slide-out stays inside its host](#a-slide-out-stays-inside-its-host-0174)). `onClose` is called after the panel has closed and its content has been cleared.
+- **`open(title, icon)`** clears the content, sets the header and returns the content element, which is also `panel.contentEl` and scrolls vertically. With no `icon` the header draws none. Opening a panel that is already open replaces its title, icon and content without sliding it in again. Before `mount`, `open` returns `null`. `isOpen` says whether it is open.
+- **Closing.** The close button, a click on the backdrop and Esc all call `close()`. Esc is heard on the document while the panel is open, and the panel calls `stopPropagation()` on it. `close()` on a closed panel does nothing. `dispose()` closes first, so `onClose` runs if the panel was open.
+
+## Where it sits
+
+While it is open the panel is `position: fixed`, pinned to the right edge of its host's visible frame, at the host's full height. A host may be a scroll container, and an absolutely positioned child of one would scroll away with the content. Fixed positioning keeps it in place, and the panel measures its host again whenever the geometry can have changed:
+
+- on window scroll and window resize;
+- when the host, or any of its ancestors, is resized. A tile splitter drag or a dock panel toggling moves the host without any window event, and a toggle beside a fixed-width tile resizes an ancestor while the tile only shifts;
+- under the shell's content zoom the host's rectangle is read in screen pixels, so the panel divides it by its effective zoom (`currentCSSZoom`). It stays flush with the host's right edge, top and height at 50% and at 150%. An engine without `currentCSSZoom` is treated as 100%.
+
+`tests/slide_out_host_resize.test.mjs` and `tests/slide_out_panel_zoom.test.mjs` drive the tracking in jsdom.
+
+## Styling
+
+| Class | What it is |
+|---|---|
+| `.twm-slide-out-panel` | The panel. `--open` is added while it is open; it slides in over 200 ms. While open it carries the host's width as `--twm-slide-out-host-w`, its `max-width` and the ceiling of its 400px `min-width` (0.17.4) |
+| `.twm-slide-out-panel__header` | The header row: the icon, the title and the close button |
+| `.twm-slide-out-panel__icon` | The header icon, a `material-symbols-outlined` glyph at **18px** (0.17.4) |
+| `.twm-slide-out-panel__title` | The title, on one line, cut with an ellipsis |
+| `.twm-slide-out-panel__close` | The close button, also a `.twm-btn-icon`. Its `material-symbols-outlined` icon is **18px** (0.17.4) |
+| `.twm-slide-out-panel__body` | The content area, `overflow-y: auto` |
+| `.twm-slide-out-panel__backdrop` | The transparent click-catcher over the host. `--visible` is added while the panel is open |
+
+The header icon and the close button are `material-symbols-outlined` glyphs. Their 18px rules use two classes each, so they win over the icon font's own 24px (the icon-font rule in [Theming and CSS](../concepts/styling.md)).
+
+## A slide-out stays inside its host (0.17.4)
+
+A `SlideOutPanel` is never wider than the host it is mounted in. Its right edge
+is pinned to the host's right edge, and while it is open it carries the host's
+width as `--twm-slide-out-host-w`, which `.twm-slide-out-panel` uses as its
+`max-width` and as the ceiling of its 400px `min-width`. In a host narrower than
+the panel's `width` (700px by default) the panel is the host's width and starts
+at the host's left edge, at any content zoom, and it is capped again whenever
+the host is resized (a splitter drag, a dock toggling). In a wider host nothing
+changes.
+
+The header icon (`.twm-slide-out-panel__icon`) and the close button's icon are
+**18px**, by rules that win over `.material-symbols-outlined`'s 24px.
+
+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.