flexdesk 0.17.2 → 0.17.4

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

@@ -0,0 +1,294 @@
+# Forms and dialogs
+
+> **Package:** `@flexdesk/widgets` · **See also:** [Input fields](input-fields.md), [Wizard](wizard.md) · [All docs](../README.md)
+
+`openForm` opens a modal form and resolves with the values, or with `null` when the user cancels. `openConfirm` asks a yes-or-no question. The field types are `text`, `number`, `password`, `select`, `textarea`, `checkbox`, `toggle`, `picker`, `checklist`, `radio`, `color` and `colorList`.
+
+## Forms: `openForm`
+
+`openForm({ title, fields, defaults, submitLabel })` (in `@flexdesk/widgets`)
+opens a modal form and resolves with `{ [name]: value }`, or `null` when it is
+cancelled. Fields are `text`, `number`, `password`, `select`, `textarea`,
+`checkbox`, `toggle`, `picker`, `checklist`, `radio`, `color` and `colorList`;
+`{ section: 'Label' }` entries are headings and `{ row: [...] }` entries put
+fields side by side. The additions below are opt-in, with one change every form
+sees, even one that uses none of them: a `select` or `radio` comes back with
+its option's OWN value and type (a numeric option submits `2`, not `'2'`; an
+option whose value is `null` submits `null`), a default of that type selects
+its option (`defaults: { s: 2 }` selects the option whose value is `2`), and an
+option object with no `label` shows its value. A select with no option
+selected still reads and submits `''`.
+
+### A form that adapts: `onFieldChange`
+
+```js
+openForm({
+    fields: [
+        { name: 'type', label: 'Type', type: 'select', options: ['bug', 'story'] },
+        { section: 'Story', name: 'story' },          // a NAMED section can be hidden
+        { name: 'points', label: 'Points', type: 'number', required: true },
+    ],
+    onFieldChange: (name, value, api) => {
+        const story = api.get('type') === 'story';
+        api.setVisible('story', story);
+        api.setVisible('points', story);
+    },
+});
+```
+
+`onFieldChange(name, value, api)` is called once when the form opens (with
+`name === null`, so the form starts consistent with its defaults) and after
+every field's `change`. `api` addresses fields and named sections by name:
+
+- `setVisible(name, on)` hides or shows the row. A hidden row keeps its value
+  and is still submitted (a disabled option it holds submits as no value:
+  `''` for a select or combobox, `null` for a radio), but it is not asked
+  about: its `required` and its
+  `validator` stand down until it is shown again.
+- `get(name)` reads the control as it stands: a checkbox as a boolean, a
+  select or radio as its option's own value (a select with no option selected
+  as `''`, a radio with none as `null`), a combobox as the value of the option
+  its text names — exactly what it submits — or as its text when it names
+  none, a checklist as the array of chosen values, anything else as its
+  string.
+- `set(name, value)` writes it. It does not call `onFieldChange` back, so a
+  hook that fills one field from another cannot loop. A value a select or
+  radio does not offer, or offers only disabled, clears it (a select then
+  submits `''`, a radio `null`).
+- `setOptions(name, options)` replaces the options of a `select` (a
+  combobox's suggestions too), `checklist` or `radio` while the form is open
+  — see below.
+
+A hook that throws is logged and the form carries on.
+
+### Hidden rows stay hidden
+
+`.twm-modal__row` is a grid, and a grid rule beats the `display: none` that
+the `hidden` attribute gets from the browser, so a hidden row stayed on
+screen. `flexdesk.css` now has `.twm-modal__row[hidden],
+.twm-modal__section[hidden] { display: none !important }`, and `setVisible`
+also sets the row's inline `display`, so it holds under a stylesheet of your
+own as well.
+
+### A value you look up: `type: 'picker'`
+
+```js
+{ name: 'parent', label: 'Parent', type: 'picker', required: true,
+  pick: async (current) => ({ value: 'EPIC-0001', label: 'EPIC-0001 — Auth rewrite' }),
+  displayFor: (value) => titleOf(value) }
+```
+
+The row shows a read-only box and a search button. The button, or a click on
+the box, awaits `pick(currentValue)`. Return `{ value, label }` (the label is
+shown, the value is submitted), a bare value (shown through `displayFor`, or
+as itself), or `null` to leave the field as it was. `displayFor(value)` gives
+the text for the value the form opens with and for `api.set`. The value is
+kept in a hidden input, which the browser's own `required` check skips, so
+`required: true` on a picker is checked by the form instead. The markup is
+`.twm-picker` > `.twm-picker__display` + `.twm-btn.twm-picker__btn`.
+
+### A select you may type into: `create`
+
+A `select` with a `create` spec is a type-ahead combobox: pick an option or
+type a new value. `create: { onCreate, hint }` makes the typed value into an
+entity before the form resolves, and shows "↳ will create *hint* …" while you
+type. `create: true` is the plain case: the typed value is submitted as typed,
+with no hint, because nothing is created. Until now `create: true` failed the
+submit with "onCreate is not a function".
+
+`tests/open_form.test.mjs` mounts the real `openForm` in jsdom and covers all
+four, plus a plain form submitting as before.
+
+### Options: typed, unavailable, grouped, and changed while open (0.17.0)
+
+```js
+openForm({
+    fields: [
+        { name: 'country', label: 'Country', type: 'select', options: ['no', 'it'] },
+        { name: 'town', label: 'Town', type: 'select', options: [] },
+        { name: 'plan', label: 'Plan', type: 'select', options: [
+            { value: 1, label: 'Free' },
+            { value: 2, label: 'Pro', disabled: true, reason: 'needs a licence' },
+            { group: 'Teams', options: [{ value: 10, label: 'Small team' }, { value: 50, label: 'Large team' }] },
+        ] },
+        { name: 'days', label: 'Days', type: 'checklist', required: true,
+          options: [{ value: 'mon', label: 'Mon' }, { value: 'tue', label: 'Tue' }] },
+        { name: 'mode', label: 'Mode', type: 'radio', options: [
+            { value: 'fast', label: 'Fast', description: 'Skips the checks.' },
+            { value: 'safe', label: 'Safe' },
+        ] },
+    ],
+    onFieldChange: (name, value, api) => {
+        if (name === null || name === 'country') api.setOptions('town', townsOf(api.get('country')));
+    },
+});
+// → { country: 'it', town: 'Rome', plan: 10, days: ['mon'], mode: 'fast' }
+```
+
+An option is a bare value or `{ value, label?, disabled?, reason?,
+description? }`.
+
+- **Values keep their type.** An option whose value is the number 10 submits
+  10, and `api.get` reads 10 — not `'10'`. A default matches an option of the
+  same text, so `defaults: { plan: '10' }` selects 10. A combobox entry typed
+  as an option's text submits (and `api.get` reads) that option's value. An
+  option whose value IS the given one wins over one that only has its text:
+  with options `[1, '1']`, a default `'1'` submits `'1'`.
+- **A disabled option** is shown with its `reason` (in a select's option text
+  and tooltip, under a radio, on a chip) and is never the submitted value: a
+  default naming it does not select it, `api.set` to it clears a select,
+  radio or combobox and leaves a checklist's chip unpressed, the reader
+  cannot pick it, a combobox does not suggest it, and a submit
+  that finds one selected anyway (a script set `.value`, or every option is
+  disabled) is refused with "Not available: *reason*" on the field. In a
+  hidden row, which is not asked about, it submits as no value instead.
+- **`{ group, options }`** in a select's list is an `<optgroup>` headed
+  *group*. In a checklist or radio it is a `.twm-choice__group` heading over
+  that group's chips or rows (a group with no options draws none). A combobox
+  suggests a group's enabled options, without headings.
+- **`api.setOptions(name, options)`** replaces the list while the form is
+  open and keeps the current value when the new list offers it enabled.
+  Otherwise a select falls to its first enabled option, a radio to none and a
+  checklist drops what is gone. It does not call `onFieldChange` back.
+- **`type: 'checklist'`** draws toggle chips and submits the array of chosen
+  values in the list's order (`[]` for none). `required` means at least one,
+  and nothing chosen is "Required." on the field.
+- **`type: 'radio'`** draws one radio row per option, with its `description`
+  under it, and submits the chosen value, or `null`. `required` means one is
+  chosen.
+
+The select, the chips and the radio list are the flow kit's
+(`src/ui/components/choice_controls.js`): the settings panel's `enum` select,
+`enum-chips`, `upstream-columns` and `choice-cards` draw with the same code, so
+a form and a settings panel cannot drift apart. In a form they are classed
+`.twm-flow-togglechips` / `.twm-flow-togglechip` and `.twm-flow-choices` /
+`.twm-flow-choice`; an unavailable option's reason is `.twm-choice__reason`.
+
+`tests/open_form_choices.test.mjs` covers each of these in jsdom.
+
+### Colours: `type: 'color'` and `type: 'colorList'` (0.17.0)
+
+```js
+openForm({
+    fields: [
+        { name: 'accent', label: 'Accent', type: 'color', default: 'rgb(31,119,180)',
+          presets: ['#1f77b4', '#ff7f0e', '#2ca02c'] },
+        { name: 'palette', label: 'Palette', type: 'colorList', default: ['#1f77b4', '#ff7f0e'] },
+    ],
+});
+// -> { accent: '#1f77b4', palette: ['#1f77b4', '#ff7f0e'] }
+```
+
+A `color` row is a swatch that opens the native picker, a hex box kept in step
+with it (picking writes the box; typing a valid hex moves the swatch), and,
+with `presets`, a strip of preset swatches. It submits lowercase `#rrggbb`, or
+`''` when left empty. A `colorList` row is an ordered list of such fields: add,
+remove, and reorder by drag or by the up / down buttons; `presets` are offered
+on every row, and it submits the colours in their current order as an array of
+`#rrggbb`. An `rgb()` / `rgba()` default (or `api.set` value) is shown as its
+hex; alpha is dropped, because the native picker has none. A box that does not
+hold `#rgb` or `#rrggbb` is a field error ("Not a hex colour", with the row
+numbers for a list) and the form does not resolve; `required` on either is
+checked by the form. `api.get` reads a `color` as its box text and a
+`colorList` as the array of its rows' text.
+
+Both are also components of their own in `@flexdesk/widgets`:
+`new ColorField({ value, presets, name, label, onChange })` and
+`new ColorListField({ value, presets, newColor, addLabel, name, onChange })`,
+each with `render()`, `getValue()` (null while something typed is not a
+colour), `setValue()`, `focus()` and `dispose()`; `onChange(value, { commit })`
+reports every edit and, with `commit: true`, every committed one.
+`normalizeHex(value)` (`#rgb`, `#rrggbb`, `rgb()` -> `#rrggbb` or null) and
+`isHexColor(value)` are exported with them, and `validateField` (in
+`@flexdesk/tiles`) now rejects a `FieldTypes.COLOR` value that is not a hex
+colour. The markup is `.twm-color-field` > `.twm-color-field__swatch` +
+`.twm-color-field__hex` (+ `.twm-color-field__presets`), and `.twm-color-list`
+rows are `.twm-color-list__row`. `tests/color_field.test.mjs` covers all of it.
+
+### Number bounds and fields side by side: `min`, `max` and `{ row }` (0.17.0)
+
+```js
+openForm({
+    fields: [
+        { name: 'steps', label: 'Steps', type: 'number', min: 2, max: 200, step: 1 },
+        { row: [
+            { name: 'lo', label: 'Min', type: 'number', hint: 'lowest value' },
+            { name: 'hi', label: 'Max', type: 'number', min: 0 },
+        ] },
+    ],
+});
+// → { steps: 50, lo: 0, hi: 10 }
+```
+
+- **`min` / `max`** on a `number` field are the input's own `min` and `max`
+  attributes, and a value outside them is refused on submit with an error
+  under that field: "Must be between 2 and 200." (or "Must be at least 2." /
+  "Must be at most 200." with only one). The browser's own range check stops
+  such a submit first; the form cancels its bubble and shows the field error
+  instead, and it checks the range itself as well, before the field's
+  `validator`. An empty field that is not `required` is not out of range. A
+  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.
+  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`.
+
+A form with neither renders exactly as before.
+`tests/open_form_rows_bounds.test.mjs` covers both in jsdom.
+
+### A switch: `ToggleField` and `type: 'toggle'` (0.17.0)
+
+```js
+import { ToggleField } from '@flexdesk/widgets';
+
+const autosave = new ToggleField({
+    label: 'Autosave', onText: 'On', offText: 'Off',   // all optional
+    checked: true, compact: false, disabled: false,
+    onChange: (on) => settings.set('autosave', on),
+});
+host.appendChild(autosave.render());
+autosave.get();              // true
+autosave.set(false);         // does not call onChange
+autosave.setDisabled(true);
+autosave.dispose();
+```
+
+A track and a knob drawn over a real checkbox with `role="switch"` and an
+`aria-checked` that follows it. Space and Enter toggle the focused switch, a
+click on the track, the state text or the label toggles it, the focused input
+draws a ring on the track, and a disabled switch ignores clicks and keys alike.
+`ariaLabel` names a switch with no visible label. The markup is
+`label.twm-toggle` (`--compact`, `--disabled`) > `.twm-toggle__control` >
+`input.twm-toggle__input` + `.twm-toggle__track` > `.twm-toggle__knob`, then
+`.twm-toggle__state` and `.twm-toggle__label`; `flexdesk.css` styles it from
+tokens alone, with no colour literal.
+
+In a form, `{ name, label, type: 'toggle', onText?, offText?, disabled?,
+compact? }` mounts one and submits a boolean, like a checkbox; `api.get` reads
+it as a boolean and `api.set` moves it. `tests/toggle_field.test.mjs` covers
+both.
+
+## Confirms show text, not markup (0.17.0)
+
+`openConfirm({ title, message, confirmLabel, cancelLabel, danger, icon })`
+resolves `true` or `false`. Its `message` and both labels are **text**: they
+are set with `textContent`, so a `<` shows as a `<`. Until 0.17.0 they went into
+`innerHTML`, and `showDeleteConfirmDialog` / `showCloseConfirmDialog` put
+`itemName` and `itemType` into that message raw: a flow named
+`<img src=x onerror=…>` rendered an image and ran its handler, and a name with
+an unclosed `<` swallowed the rest of the message.
+
+A caller that passed markup in `message` now sees the tags; write a `\n` for a
+line break instead (the message body is `white-space: pre-line`).
+`additionalMessage` on `showDeleteConfirmDialog` follows on its own paragraph
+exactly as before. A body that needs real markup is `openModal`'s job: it takes
+the caller's own DOM.
+
+`tests/confirm_escaping.test.mjs` opens each of them in jsdom with hostile
+names and labels.

package/docs/components/input-fields.md

@@ -0,0 +1,72 @@
+# Input fields: slider and tags
+
+> **Package:** `@flexdesk/widgets` · **More fields:** the toggle and colour fields are in [Forms and dialogs](forms-and-dialogs.md) · [All docs](../README.md)
+
+Two stand-alone inputs. `SliderField` draws a range input, with an optional number box, readout, default and enable toggle. `createTagInput` draws a list of short strings as removable chips followed by a text box.
+
+## SliderField: a number box, a readout, a default and an enable toggle (0.17.0)
+
+`new SliderField({ fieldId, field, onChange })` (from `@flexdesk/widgets`)
+draws a range input. Its companions are opt-in through `field`; with none of
+them the DOM is the range and the helper line, as it always was.
+
+```js
+import { SliderField } from '@flexdesk/widgets';
+
+const slider = new SliderField({
+    fieldId: 'rate',
+    field: {
+        min: 0, max: 1, step: 0.01, value: 0.25,
+        numberInput: true,                         // an editable box, kept in sync both ways
+        readout: (v) => `${Math.round(v * 100)}%`, // or true for the plain value
+        defaultValue: 0.25,                        // --modified state and a reset button
+        toggleable: true, disabledValue: null,     // an enable checkbox before the slider
+    },
+    onChange: (value, { immediate }) => save(value),
+});
+host.appendChild(slider.render());
+```
+
+| Field / method | What it does |
+| --- | --- |
+| `numberInput` | A text box beside the slider. Dragging updates it on every frame; Enter (or leaving the box) commits what was typed, clamped to `[min, max]` and snapped to `step`. Text that is not a finite number (`abc`, empty, `Infinity`) changes nothing and the box shows the value again; Escape does the same |
+| `readout` | A span after the slider: `true` shows the value, a function `(value: number) => string` formats it. It follows the drag live |
+| `defaultValue` | While the value differs from it the root carries `twm-slider-field--modified` and the reset button shows; reset restores it and reports it through `onChange`, like a release |
+| `toggleable`, `enabled`, `disabledValue` | A checkbox before the slider (`enabled: false` starts it off). While off, the inputs are disabled, the root carries `twm-slider-field--off`, and `onChange`/`getValue()` report `disabledValue` (default `null`) |
+| `onChange(value, { immediate })` | Called once per commit: a drag release, a typed Enter, a reset, a toggle. The value is the slider's value as a string, as before. With `emitOnInput` it is also called on every drag frame with `immediate: true` |
+| `setValue(x, { silent })`, `setRange({ min, max, step }, { silent })`, `setEnabled(on, { silent })`, `reset({ silent })` | Change the field from code. Each reports at most once, nothing with `silent: true`, and nothing when the reported value did not move, so a caller that writes back from its own `onChange` does not loop. `setValue` refuses a non-finite value (returns `false`); `setRange` refits the value and the default |
+| `getValue()`, `isEnabled()`, `isModified()` | What `onChange` would report now, the toggle state, and whether the value differs from `defaultValue` |
+
+## A list of tags: `createTagInput` (0.17.0)
+
+`createTagInput(host, { value, placeholder, readOnly, allowDuplicates, onChange })`
+(in `@flexdesk/widgets`) draws a list of short strings as removable chips
+followed by a text box, and appends it to `host`.
+
+```js
+const tags = createTagInput(host, {
+    value: ['baseline'],
+    placeholder: 'Add a tag…',
+    onChange: (list) => save(list),   // a fresh copy after each change the reader makes
+});
+tags.getValue();            // ['baseline']
+tags.setValue(['a', 'b']);  // redraws; does not call onChange
+tags.dispose();
+```
+
+- **Enter**, a **comma** and **blur** commit what was typed: it is split at
+  commas and each piece trimmed, so `a, b` then Enter adds two chips and
+  `onChange` receives `['a', 'b']`.
+- Empty pieces are ignored, and so is a piece already in the list unless
+  `allowDuplicates` is set. A commit that adds nothing calls no `onChange`.
+- **Backspace** in an empty box removes the last chip.
+- A **paste** that carries a comma is split into chips at once; a paste
+  without one is ordinary text in the box.
+- Each chip's remove button has an `aria-label`, "Remove <tag>" by default;
+  `removeLabel(tag)` words it (for another language). `label` names the text
+  box and the group.
+- `readOnly` draws the chips alone: no remove buttons and no text box.
+
+The handle is `{ element, input, getValue, setValue, focus, dispose }`
+(`input` is `null` when read-only). The styles are the `twm-tag-input` block in
+`flexdesk.css`. `tests/tag_input.test.mjs` covers each of the above in jsdom.

package/docs/components/keymap.md

@@ -0,0 +1,143 @@
+# Keys, Back and tab layout
+
+> **Package:** `@flexdesk/wm` · **See also:** [Command palette](command-palette.md) · [All docs](../README.md)
+
+The window manager binds a set of keyboard chords: F1 to F12, Backspace, Ctrl+K, Ctrl+Tab, Ctrl/Shift+Arrows, the Alt chords, `?` and Esc. `keymap.bindings` takes any of them back or rebinds it. The same page covers what depends on those keys and on how a user moves around: what Back and the breadcrumb do, the content zoom control (`chrome.zoom`), and the shell options `backToOpenList`, `floatActiveTab` and `tabLayout`.
+
+## Your keys, not the window manager's: `keymap` (0.17.0)
+
+The window manager binds F1..F12, Backspace, Ctrl+K, Ctrl+Tab, Ctrl/Shift+Arrows,
+the Alt chords, `?` and Esc, and swallows any other bare Alt+letter. Each of
+those chords can be taken back or rebound:
+
+```js
+await createShell({
+    // …everything above…
+    keymap: {
+        bindings: {
+            'F1': false,               // F1 is the page's: not prevented, nothing clicked
+            'F2': 'nav:0',             // F2 opens the first top-nav kind
+            'Backspace': false,        // Backspace never calls navigateBack
+            'Alt+W': (e, { wm }) => { /* yours; return false to leave e unprevented */ },
+        },
+    },
+});
+```
+
+A value is `false`, an action name, or a function. The actions are `palette`,
+`palette:close`, `help`, `back`, `nav:N`, `desktop:N`, `toDesktop:N` (all
+counted from 0), `desktop:next|prev`, `tab:next|prev`, `panelTab:next|prev`,
+`split:h|v`, `splitWith:h|v`, `openInTab`, `openInWindow`, `close`, `float`,
+`focus:left|right|up|down`, `move:left|right|up|down` and `suppress`. The chord
+ids are the defaults in `src/tiling/keymap.js`: `Ctrl+K`, `Meta+K`, `?`,
+`Escape`, `F1`..`F12`, `Backspace`, `Alt+H`, `Alt+Shift+H`, `Alt+ArrowLeft`,
+`Alt+Shift+1`, `Ctrl+Tab`, `Shift+ArrowRight` and so on, with `Alt+Letter` for
+the Alt+letter suppression. Modifiers may come in any order and case. A chord id
+or action the keymap does not know is warned about once, through `logger` (else
+`console`), when the shell is built, and is then ignored. Only the window
+manager's own chords can be rebound. To add a new key, put your own listener on
+the page. `keymap` itself must be an object whose only key is `bindings`:
+anything else (a string, a typo such as `{ binding: … }`) makes `createShell`
+throw a `TypeError`, so a binding you meant to change never stays in force
+unnoticed.
+
+**A key press is read as loosely as before.** With no bindings every key does
+what it did in 0.16, and a binding takes over every key press its chord was
+read as. Backspace ignores Shift and Alt, so `{ Backspace: false }` also hands
+Shift+Backspace and Alt+Backspace to the page. Alt+T/N/W/F ignore Shift. With
+Alt held, Ctrl and Meta are ignored, so Alt+Ctrl+H is `Alt+H`. Ctrl+K and
+Ctrl+Tab also match with Meta held, and Ctrl wins when both are held:
+Ctrl+Meta+K is `Ctrl+K`, and Meta+K is `Meta+K` only without Ctrl. Esc and `?`
+ignore every modifier. F1..F12, Shift+Left/Right and Ctrl+Left/Right match only
+with exactly those modifiers.
+
+**A key a component handled is the component's.** The keymap skips every
+keydown that is already `defaultPrevented`. A list that deletes a row on
+Backspace calls `preventDefault()`, and the window manager does not navigate
+back as well.
+
+**`?` is installed by the shell.** Importing `HelpModal` no longer adds a
+`document` listener as a side effect. A shell binds `?` as one of its chords,
+and `shell.dispose()` removes it with the rest. A page that uses the help modal
+without a shell calls `installHelpShortcut()` from `@flexdesk/widgets`, which
+returns its disposer. `HelpModal.toggle()` is what `?` does.
+
+**The *Keyboard shortcuts* command shows the bindings in effect.** It lists
+`keymapShortcuts(bindings)` from `@flexdesk/wm`. That is `KEYMAP_SHORTCUTS`
+with each changed row replaced by one line per chord still bound, and no line
+for a chord you disabled. `createCommandPalette({ shortcuts })` takes that table.
+The command's hint names the keys that open help in it: `?` by default, `F9`
+after `{ '?': false, F9: 'help' }`, and none when no key opens help (for
+example after `{ '?': 'palette' }`).
+
+**`chrome.zoom`** paints a − / track / + / readout control into the element you
+pass, restores the saved zoom through the host's `state` capability, and scales
+the content of tiles and floating windows. It deliberately scales *content only*
+— never the root, a tile's frame or a window's frame — because CSS `zoom`
+establishes a scaled coordinate space and every window drag, resize and snap
+measures in real pixels. `shell.chrome.zoom` exposes `get()` and `set(percent)`
+for a settings pane. An embedder that builds its own `WindowManager` instead of
+calling `createShell` mounts the same control with `mountZoomControl(el, { root,
+host })`.
+
+**`backToOpenList`** is for apps that open a record from a list in a new tab.
+Without it, Back in that record has no history to pop, so it walks the taxonomy
+up and rewrites the record into its parent, and the tile now shows the list
+twice. With it, Back closes the record tab and activates the list it came from:
+the nearest tab to the left, else to the right, that is not a record (no
+`props.id`) and belongs to the same top-nav section. Per-tab history still comes
+first, and a record with no such list beside it still walks up in place.
+
+**`floatActiveTab`** is for apps whose tabs are separate records rather than
+views of one pane. The float button, Alt+F and the tile menu take only the tab
+on screen and leave its siblings in the tile, so the window holds one tab and
+draws no strip. Without it the whole pane floats, strip and all.
+
+**`tabLayout`** says where a tile draws its tabs. `'bottom'` (the default) is
+the spreadsheet strip under the body, shown from two tabs. `'top'` is the
+editor tab bar between the header and the body, also from two tabs.
+`'header'` (0.8.0) puts that tab bar inside the header in place of the title,
+on every tile, one tab included, with a `+` after the last tab that opens the
+taxonomy root in a new tab (`wm.newTab(leafId)`, the same seed a split uses).
+Pass `newTabButton: false` (0.8.1) to leave the `+` out.
+A panel tile has no tabs and keeps its title. Under `'header'` the tab, not
+the header, is what you drag to move a single-tab pane; the empty part of the
+header still floats the pane on a pull-down or a double-click. Set
+`data-twm-tabs` on the shell's root, or call `wm.setTabLayout()`, to switch
+live; nothing mounted in a tile is unmounted.
+
+**Back and the breadcrumb are one rule.** `wm.navigateBack()` (Backspace) and
+`wm.navigateUp(kind, props, { ctx })` (every breadcrumb crumb) share it. With
+`backToOpenList`, a record whose section has a list open closes onto that list;
+otherwise Back walks the taxonomy up and a crumb navigates to its level, in
+place. A crumb naming an entity, such as an epic above a story, opens that
+entity. `navigate` stays the verb for going to exactly a target; use
+`navigateUp` for anything that means "up to this level".
+
+A filter or other props passed to `openInPrimary` for a list that is already
+showing are applied to it. A bare open, such as a top-nav click, keeps the tab
+as you left it.
+
+**Back in a floating window** always acts on that window, whichever option is
+set. The last click decides: inside a window, Backspace walks that window up;
+anywhere else, it walks the focused tile as before. With `backToOpenList`, a
+record in a window closes onto an open list of its section, first among the
+window's own tabs and then in any tile of its desktop.
+
+**A page's own levels come first** (0.4.7). A page can have levels that are not
+tabs, such as a section whose list opens one member in place of itself. Return
+`navigateBack()` from the content factory's mount, and Backspace asks it before
+anything above: it climbs one of the page's own levels and returns `true`. Only
+a strict `true` counts. `false`, any other value, a missing function or a throw
+(logged as a warning) all let Back walk the tab history, the open list and the
+taxonomy exactly as before. It is asked in the same place as the rest of Back:
+the window you last clicked in, else the focused tile. Return
+`canNavigateBack()` as well, and `wm.canNavigateBack()` reports the page's own
+levels, for that same window or tile. `TileRenderer.contentOf(leafId)` reads
+what a tile's factory returned. To draw the page's levels, call
+`renderBreadcrumb(container, segments)` from `@flexdesk/wm`, with
+`segments = [{ label, icon?, onClick? }]`. It uses the tile breadcrumb's
+markup, so it looks the same, and each `onClick` is yours: the last segment,
+and any without `onClick`, is drawn as plain text. The current segment's item
+carries `aria-current="page"`, and every label has a `title` with its full text,
+so a label your CSS truncates still reads whole (0.15.1).