flexdesk 0.17.2 → 0.17.4

package/docs/components/layout-widgets.md

@@ -0,0 +1,163 @@
+# Tabs, section stacks and scrollbars
+
+> **Package:** `@flexdesk/widgets` · [All docs](../README.md)
+
+`createTabs` draws one tab strip keyed by your own ids, with or without the panes behind it. `createSectionStack` draws inspector-style titled sections in a column, each opened and closed from its header. `installAutoScrollbars` replaces the browser's scrollbars with thin overlay bars.
+
+## Scrollbars
+
+`installAutoScrollbars(root)` (from `@flexdesk/widgets`) replaces the browser's
+scrollbars under `root` with thin overlay bars that show while an element is
+hovered or scrolling and fade out afterwards. Native bars are hidden, so no
+element reserves layout width for one. The overlay bars live in one fixed
+layer, so a container that redraws its contents cannot lose its bar, and
+textareas get one too. Containers that already use `installOverlayScrollbar`
+keep their own.
+
+`installCollapsibleScrollbars(root = document.body)` gives every
+`.twm-collapsible-content.visible` section under `root` a vertical overlay
+bar: the ones already visible at once, and the ones mounted or expanded
+later. It watches `root` only and returns a disconnect. (It used to take no
+argument and look for a `#twm-fixed-200` that nothing created, so visible
+sections got no bar until a class changed — BUG-0006.)
+
+## A pane at the window's edge keeps its bar (0.17.4)
+
+An overlay bar whose track is covered (a popover, a menu, a dialog over it)
+is not drawn. The window's own resize handles are not cover: the 6px
+`.twm-resize-handle` strips and corners that `WindowChromeController` lays
+along the edges of a non-maximized window are skipped when `barCovered()`
+looks at what sits over the track, as the overlay layer's own bars are. A
+pane flush against the right or bottom edge shows its bar on hover and while
+scrolling, and a popover over that pane still hides it, handle or not.
+
+Until 0.17.4 the right strip (z-index 9999) counted as covering every pane
+at the right edge of a window that was not maximized, so those panes had no
+scrollbar at all (BUG-0036). `tests/autoscroll_resize_handle_not_cover.test.mjs`
+holds it.
+
+## A stack of collapsible sections: `createSectionStack` (0.17.0)
+
+Inspector-style panel content: titled sections in a column, each opened and
+closed from its header. It is built from the tree's `.twm-collapsible-*`
+pieces plus `.twm-section-stack*` (`@flexdesk/widgets`).
+
+```js
+const stack = createSectionStack(panel, {
+    sections: [
+        { id: 'notes', title: 'Notes', icon: 'edit_note', content: notesEl },
+        { id: 'chat', title: 'Assistant', fill: true,
+          actions: [{ icon: 'delete', label: 'Clear', onClick: (id, event) => clear() }] },
+        { id: 'params', title: 'Parameters', defaultExpanded: false },
+    ],
+    key: 'inspector.sections',
+    stateStore: { read: (key) => saved[key], write: (key, map) => { saved[key] = map; } },
+});
+stack.body('params').appendChild(paramsEl);
+const off = stack.on('toggled', ({ id, expanded, source }) => { /* … */ });
+```
+
+- **The header toggles, its actions do not.** A click anywhere on a header
+  opens or closes the section and turns its arrow. A click on one of its
+  `actions` runs that action's `onClick(sectionId, event)` and nothing else.
+  The toggle is a `<button>`, so Enter and Space work.
+- **`defaultExpanded`** is `true` unless a section says `false`.
+- **One `fill` section** takes the height the others leave, and its body is
+  what scrolls (`min-height: 0`). A long conversation scrolls inside its
+  section and the panel stays the size of the window. The stack is
+  `height: 100%` of its container, so give the container a height. A closed
+  fill section is only its header.
+- **Remembering is injected.** `stateStore` is `{ read(key), write(key, map) }`.
+  `map` is `{ [sectionId]: expanded }`, and it is written on every open and
+  close under `key`. `read` may return a promise. Until it settles the
+  sections show their defaults; a section somebody toggled in the meantime
+  keeps that choice, and that toggle is written once the read has settled,
+  over the stored states of the sections nobody touched. `stack.ready` resolves once the read has been applied. A
+  store that throws, rejects or returns anything other than a map leaves every
+  section on its `defaultExpanded`. Without a store nothing is remembered.
+- **`setVisible(id, false)`** takes a section off the stack and keeps its
+  state, so `setVisible(id, true)` brings it back open or closed as it was.
+  `isVisible(id)` reads it.
+- `expand(id)`, `collapse(id)`, `toggle(id)` and `isExpanded(id)` work on
+  any section, hidden or not. An unknown id throws.
+- **`toggled`** fires on each change with `{ id, expanded, source }`, where
+  `source` is `'user'`, `'api'` or `'restore'` (a stored state that arrived
+  after mount). `on('toggled', fn)` returns the function that stops listening.
+- **`dispose()`** removes the stack's listener and every node it made, along
+  with any `content` you passed in.
+
+`tests/section_stack.test.mjs` covers each of these in jsdom. The fill
+layout was also measured in headless Edge.
+
+## Tabs: `createTabs` (0.17.0)
+
+One tab strip, from `@flexdesk/widgets`, keyed by whatever ids you give it — not
+by file path (`NotebookTabBar`) and not by a bus event (`createBottomPanelTabs`,
+which is now built on it). It is a strip and nothing else, or a strip with the
+panes behind it.
+
+```js
+const tabs = createTabs(el, {
+    items: [
+        { id: 'inputs',  label: 'Inputs', icon: 'tune', title: 'Model inputs' },
+        { id: 'results', label: 'Results', badge: { count: 3, level: 'warning' } },
+        { id: 'draft',   label: 'Draft', dirty: true, closable: true },
+    ],
+    active: 'inputs',
+    onSelect: (id, item) => …,
+    onReselect: (id, item) => …,                                       // optional: a click on the tab in front
+    onClose: (id) => tabs.update(items.filter((i) => i.id !== id)),   // optional
+    onReorder: (ids) => …,                                             // optional: tabs drag
+    onContextMenu: (id, event, item) => …,                             // optional
+    mountPane: (item, paneEl, tabs) => ({ onShow() {}, destroy() {} }), // optional: strip only
+    compact: false,
+    label: 'Views',
+});
+tabs.update(nextItems, 'results');
+tabs.setBadge('results', 7, 'alert');
+tabs.setIndicator('inputs', 'info');
+```
+
+| Member | Does |
+|---|---|
+| `update(items, activeId?)` | Replaces the items, keeping the button of every id it keeps. In front: `activeId` if present, else the tab in front now if it is still there, else the first (none when no items are left). Panes of items that went are destroyed |
+| `select(id)`, `active()`, `has(id)`, `ids()` | The tab in front; `select` answers false for an id it does not have |
+| `setBadge(id, n, level?)` | A count, `99+` above 99, none at zero; `level` is `info`, `warning` or `alert` (`TAB_LEVELS`) |
+| `setIndicator(id, value)` | A dot: a level, `true` for the neutral one, falsy for none |
+| `instance(id)`, `instances()` | The mounted panes' instances |
+| `destroy()` | Destroys the panes, lets the bus go, removes the markup |
+
+- **Panes mount on first selection.** The tab in front at creation counts;
+  `eager: true` on an item mounts its pane at once — at creation, or in the
+  `update` that brings the item in, before the tab in front is settled. Each
+  instance hears `onShow()` whenever its tab comes to the front and `destroy()`
+  when its item goes.
+- **`onSelect` hears changes**, not the tab chosen at creation. A click on the
+  tab already in front is not a change; `onReselect(id, item)` hears it. An
+  `update` that leaves no items empties the front, heard as `onSelect(null, null)`.
+- **The bus is opt-in:** pass `eventBus` *and* `selectEvent: 'views:show'` and
+  that event selects `payload.id` (or `selectFrom(payload)`). No event name, no
+  subscription.
+- **Keys** follow the ARIA tabs pattern with automatic activation:
+  ArrowLeft/ArrowRight (wrapping), Home, End; Delete (and a middle click) closes
+  a closable tab. Only the tab in front is in the tab order. When an `update`
+  removes the tab that has focus (Delete, then your `onClose` drops it), focus
+  moves to the tab now in front instead of falling to the page. Focus that the
+  update put somewhere else (a pane that focuses itself in `onShow`) stays there.
+- **Overflow scrolls**, never wraps: a vertical wheel moves the strip sideways and
+  the tab coming to the front is scrolled into view (`revealInStrip`,
+  `wheelStripSideways`, shared with `NotebookTabBar`).
+- **Classes** are BEM under `block` (default `twm-tabs`): `__tabs`, `__tab`,
+  `__tab--on`, `__tab--dirty`, `__tab--closable` (it has a close mark), `__icon`,
+  `__label`, `__badge`, `__indicator`, `__dirty`, `__close`, `__body`,
+  `--compact`, and `twm-tabs-pane`. A dirty tab shows its dot until hovered,
+  then its close mark; one with no close mark keeps the dot. Tabs and panes
+  carry the id in `data-tab-id` (`dataKey`), as a string; callbacks and `ids()`
+  hand back the id as you gave it, so a numeric id stays a number.
+
+`tests/tabs.test.mjs` covers it in jsdom; `tests/bottom_panel_tabs.test.mjs`
+runs on the bottom panel built over it. The bottom panel behaves as it did:
+`api.root` is set inside a pane's `mount`, and a click on the tab in front
+re-shows its pane, fires `onSelect` and is remembered, as `select` does. A
+remembered tab that is already in front when `remember.read` answers is shown
+again: its pane hears `onShow` and `onSelect` fires, and nothing is written back.

package/docs/components/markdown-and-outline.md

@@ -0,0 +1,106 @@
+# Markdown and document outline
+
+> **Package:** `@flexdesk/widgets` · [All docs](../README.md)
+
+`renderMarkdown` turns a CommonMark-ish subset of Markdown into an HTML string. `createDocumentOutline` lists a long document's sections, numbered, marks the one in view while the document scrolls, and goes to one on a click.
+
+## Markdown: `renderMarkdown` (0.17.0)
+
+`renderMarkdown(source, options)` (`@flexdesk/widgets`) returns an HTML
+string. It covers a CommonMark-ish subset — ATX headings, paragraphs,
+emphasis, strong, `~~strike~~`, code spans, fenced code, block quotes, nested
+ordered and unordered lists, GFM pipe tables, rules, links, images, autolinks,
+hard breaks and `$…$` / `$$…$$` math — and is **safe by default**:
+
+- raw HTML is escaped: `<img src=x onerror=alert(1)>` shows as that text.
+  `allowHtml: ['kbd', 'br']` lets named tags through, the tag only and never
+  its attributes; a tag that runs or embeds anything (`script`, `iframe`,
+  `svg`, `img`, …) throws. An allowed tag left open is closed at the end of its
+  paragraph.
+- a link goes out only to `http(s):`, `mailto:` or a `#anchor`, always with
+  `rel="noopener noreferrer"`; a `javascript:` link (or any other) renders its
+  text and no anchor. An image loads from `http(s):` or a relative path, or
+  shows its alt text.
+
+```js
+import { renderMarkdown } from '@flexdesk/widgets';
+
+el.innerHTML = renderMarkdown(source, {
+    highlight: (code, lang) => myHighlighter(code, lang),   // null: escaped
+    math: undefined,      // default: window.katex when present, else the escaped source
+                          // false: `$` is text; or (tex, { display }) => html | null
+    inlineRules: [{ pattern: /\[\[ref:([\w-]+)\]\]/, render: (m, ctx) => `<a href="#${ctx.escape(m[1])}">…</a>` }],
+    blockRules:  [{ start: /^:::(\w+)/, end: /^:::$/, render: ({ lines, match, closed }, ctx) => '…' }],
+    inline: false,        // true: inline markup only, no blocks, no <p>
+});
+```
+
+What the caller returns — the highlighter's, the math hook's and the rules'
+HTML — is trusted and goes in as it is; a rule answering `null` declines.
+`ctx` gives a rule `escape(text)` and `inline(text)`. Not in the subset:
+setext headings, indented code blocks, reference links, raw HTML blocks.
+
+**Streaming.** Every element it opens it closes, so each prefix of a document
+arriving token by token renders to balanced HTML: an open fence is closed at
+the end of the input, and an emphasis or link whose closer has not arrived is
+still text. `tests/markdown.test.mjs` renders every prefix of a document using
+every construct and checks the tags balance; `tests/help_modal_markdown.test.mjs`
+checks jsdom has nothing to repair.
+
+**Help topics in markdown.** A `HelpProvider`'s `loadTopic` may now answer
+`{ title, markdown }`; the modal renders it with `renderMarkdown` and the
+provider's optional `markdownOptions`. `{ title, html }` is unchanged:
+pre-rendered, **trusted** HTML, inserted as it is.
+
+**A table of contents for a help topic.** A topic with two or more headings,
+markdown or html, gets its contents between the breadcrumb and the article: a
+`createDocumentOutline` (below) of its `h1`–`h6`, numbered, the one in view
+marked as the content pane scrolls, a click that scrolls to its heading. The
+outline points at the heading elements themselves, so your markup needs no
+ids and the modal adds none; a topic with one heading or none shows no
+contents (the empty `.help-content__toc` is `hidden`). Until now the modal's
+documentation promised this and drew nothing. `tests/help_modal_toc.test.mjs`
+drives it in jsdom (BUG-0010).
+
+## A document outline: `createDocumentOutline` (0.17.0)
+
+A long document's sections, listed and numbered, the one in view marked while
+the document scrolls, and a click that goes to one (in `@flexdesk/widgets`):
+
+```js
+const outline = createDocumentOutline(sidebarEl, {
+    entries: [{ id: 'intro', level: 1, label: 'Introduction' },
+              { id: 'scope', level: 2, label: 'Scope' }],
+    numbering: true,                 // 1, 1.1, 1.2, 2 …
+    maxDepth: 3,                     // deeper entries are drawn at depth 3
+    scrollContainer: articleEl,      // the element that scrolls; the spy's root
+    resolveTarget: (entry, container) => container.querySelector(`[data-section="${entry.id}"]`),
+    rootMargin: '0px 0px -70% 0px',  // the default: the top 30% is "in view"
+    onSelect: (id, entry) => { /* … */ },
+    emptyState: 'No headings',
+});
+outline.setEntries(next);            // the document has other sections now
+outline.refresh();                   // the same sections, re-rendered: resolve again
+outline.setActive('scope');  outline.getActive();
+const off = outline.onActiveChange((id, entry) => { /* … */ });
+outline.dispose();
+```
+
+Where the entries come from is yours: the outline is told `{id, level, label}`
+and, through `resolveTarget` (by default the element in the container whose
+`id` is the entry's), which element each one stands for. Labels are text.
+Numbers are hierarchical, and a skipped level is one step deeper, not two:
+levels 1, 3, 3, 2 are 1, 1.1, 1.2, 1.3.
+
+Of the targets an IntersectionObserver rooted at `scrollContainer` reports in
+view, the one listed first is active; with none in view the last one stays. An
+entry whose target does not resolve is listed, but never watched and never
+active, and `setActive` refuses it (`false`). A click marks its entry at once,
+scrolls its target into view (`scrollOnSelect: false` leaves that to
+`onSelect`) and suppresses the spy while the scroll passes the sections in
+between, until the container's `scrollend` or, without one, `scrollEndTimeout`
+(1000 ms). `dispose()` disconnects the observer and clears that timer. The
+indent per level is `--twm-doc-outline-indent` (12px).
+
+`tests/document_outline.test.mjs` drives it in jsdom with a hand-fired
+observer.

package/docs/components/menus.md

@@ -0,0 +1,86 @@
+# Menus
+
+> **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.
+
+## A menu bar: `createMenuBar` (0.17.0)
+
+File / Edit / View menus from one declarative model, instead of hand-built
+buttons and `showContextMenu` calls. A menu is `{ id, label, items }`; an item
+is `{ id, label, shortcut?, disabled?, checked?, radio?, submenu? }` or
+`{ separator: true }`:
+
+```js
+import { createMenuBar, MenuBar } from '@flexdesk/widgets';
+
+const bar = createMenuBar(document.getElementById('menus'), {
+    menus: [
+        { id: 'file', label: 'File', items: [
+            { id: 'open',   label: 'Open…',       shortcut: 'Ctrl+O' },
+            { id: 'recent', label: 'Open recent', submenu: () => recentItems() },  // rebuilt on every open
+            { separator: true },
+            { id: 'save',   label: 'Save',        shortcut: 'Ctrl+S', disabled: true },
+        ] },
+        { id: 'view', label: 'View', items: [
+            { id: 'grid',  label: 'Show grid', checked: true },                // a check item
+            { id: 'light', label: 'Light', radio: 'theme', checked: true },    // a radio group
+            { id: 'dark',  label: 'Dark',  radio: 'theme', checked: false },
+        ] },
+    ],
+    onAction: (id, { checked }) => run(id, checked),
+});
+bar.setEnabled('save', true);     // patches an open menu in place
+bar.setChecked('dark', true);     // …and unchecks the rest of the radio group
+```
+
+`createMenuBar(el, opts)` returns a `MenuBar` (also exported, for
+`instanceof`). Its methods: `open(menuId, { focusItem })`, `close()`,
+`focus()`, `isOpen()`, `isEnabled(id)`, `isChecked(id)`, `setEnabled(id, on)`,
+`setChecked(id, on)`, `commands()` and `dispose()`.
+
+- **Pointer.** Clicking a title opens its menu; while one is open, hovering
+  another title switches to it. Hovering an item with a submenu opens it.
+- **Keyboard.** Alt (on its own) or F10 focuses the bar. Left/Right move across
+  menus, Up/Down/Home/End within one, Right opens a submenu and Left closes it,
+  Enter/Space activate. Esc closes one level; the last Esc gives focus back to
+  what had it. Disabled items and separators are skipped, and never reach
+  `onAction`.
+- **Roles.** The WAI-ARIA menubar pattern: `menubar`, `menu`, `menuitem`,
+  `menuitemcheckbox`, `menuitemradio`, with `aria-checked`, `aria-disabled`
+  and `aria-expanded`.
+- `shortcut` is a label: the bar binds no key for it.
+- `bar.commands()` returns the model as palette rows (`{ id, label, shortcut,
+  context: 'File › Open recent', action }`), so the palette and the bar list the
+  same verbs.
+
+In a shell, pass the model as `menuBar` and the element as `chrome.menuBar`
+(each needs the other; either alone throws at boot);
+`shell.chrome.menuBar` is that `MenuBar`, and its enabled items follow the palette's
+own `commands` unless `menuBar.palette` is `false`:
+
+```js
+const shell = await createShell({
+    // …
+    menuBar: { menus, onAction },
+    chrome:  { menuBar: document.getElementById('menus') },
+});
+shell.chrome.menuBar.setEnabled('save', dirty);
+```
+
+The bar is `.twm-menubar` (not the older `.twm-menu-bar` icon strip).
+`tests/menu_bar.test.mjs` drives it in jsdom; `tests/menu_bar_css.test.mjs`
+holds its stylesheet.
+
+## Action dropdowns: separators (0.17.0)
+
+`new ActionDropdown({ trigger, options, onSelect })` draws one button per
+option. An entry `{ separator: true }` in `options` draws a divider instead: a
+`<div role="separator" class="twm-action-dropdown-separator">` that takes no
+focus, that ArrowUp/ArrowDown pass over, and that never reaches `onSelect`.
+A separator only separates: one at the start or end of the list, or right
+after another, is dropped, so groups that come out empty leave no stray or
+doubled rule. `setOptions` follows the same rules, and an option's
+`data-index` stays its index in `options`.
+
+`tests/action_dropdown_separators.test.mjs` drives it in jsdom.

package/docs/components/notifications.md

@@ -0,0 +1,194 @@
+# Notifications and progress
+
+> **Package:** `@flexdesk/widgets` · [All docs](../README.md)
+
+Toasts, a history of them behind a bell, and an alert log. A toast is the moment; the alert log keeps what came in until it is dismissed. Progress bars, lists and phases change in place, and a toast can track a job with one.
+
+## Progress: bars, lists and phases (0.17.0)
+
+Three classes in `widgets`, each building its own element (`.element`, appended
+to `host` when one is given) and changing it **in place**: an update twenty
+times a second gets the same nodes back every time, so hover, tooltips and the
+fill's transition survive. Names and labels are text.
+
+| Class | Does |
+|---|---|
+| `new ProgressBar(host, { value, max, indeterminate, label, showPercent, showCount, showElapsed, onCancel })` | `update(0.42)` (a fraction) or `update(21)` with `max` (a count, read "42% · 21 / 50"); `update({ value, max, label, indeterminate })`; `setState('done' \| 'error' \| 'cancelled')` ends it and stops the elapsed clock, `setState('running')` resumes it; `fraction`, `state`, `elapsed` |
+| `new ProgressList(host, { items, stats, pulse, emptyText })` | Keyed rows `{ key, name, completed, total?, state, detail? }`, `state` one of `pending`, `running`, `done`, `failed`. `setItems` reconciles by key: a known key keeps its row. A row without `total` is drawn against the largest item. `stats: true` writes a summary line, a function `(items) => string` writes yours, `false` none. Running rows pulse |
+| `new StepProgress(host, { steps })` | Ordered phases (`{ key, label }` or a label). `setStep(keyOrIndex, { pass, passes })` makes one active, those before it done and those after pending, and reads "pass 2 of 5"; `fail()` marks the active one error; `complete()` |
+
+```js
+const list = new ProgressList(panel, { items: [] });
+job.on('tick', (workers) => list.setItems(workers.map((w) => ({
+    key: w.id, name: w.label, completed: w.done, total: w.total, state: w.state }))));
+```
+
+`showRunProgressDialog` and `showComputingWindow` take `progress` (`true`, or
+ProgressBar options) and `steps`, fixed when the dialog opens. Their handles
+gain `setProgress(next)` and `setStep(which, opts)`, which throw when the dialog
+was opened without `progress` or `steps` respectively, and **`result`**, a
+Promise that settles once with
+`{ status, message }`: `complete({ ok })` gives `done` or `error` (the bar and
+the phases show it), `cancelled()` gives `cancelled`, and so does **closing the
+dialog while it runs** (by its ×, Escape, `close()`, or for `showComputingWindow`
+opening another). Closing never calls `onCancel`; only the Stop / Cancel button
+does, as before. `showComputingWindow` also gains `complete` and `cancelled`,
+after which it shows a Close button.
+
+```js
+const dlg = showRunProgressDialog({ title: 'Export', steps: ['Prepare', 'Render', 'Write'],
+                                    progress: { showElapsed: true }, onCancel: () => job.stop() });
+dlg.setStep(1); dlg.setProgress(0.4);
+const { status } = await dlg.result;   // 'done' | 'error' | 'cancelled'
+```
+
+`tests/progress.test.mjs` holds all of it in jsdom.
+
+## Notifications: `NotificationCenter`
+
+Toasts, from `toast:show` on the bus (or `toastInfo` / `toastWarn` /
+`toastError` / `toastSuccess`) or `show()`. A payload with `persistent: true`
+stays until its × is clicked. `history` keeps every notification shown, and
+`NotificationHistory` puts it behind a bell in the bottom bar (one entry per toast;
+`subscribe(fn)` hears each one, 0.17.3).
+
+*New in 0.11.0:* **`overflow: 'collapse'`.** By default, a toast past
+`maxVisible` (3) pushes the oldest off the screen. With `'collapse'`, the toasts
+on screen stay, and the rest wait behind one **"+N more"** toast whose count
+follows them. Each comes in as a visible one closes. A sticky alert is never
+pushed off unseen. Clicking the summary calls `summaryAction(held)` and emits
+`notification:summary` with `{held}`, so a history panel can open. Every toast
+is in `history` as it arrives, waiting or not.
+
+```js
+const nc = new NotificationCenter({ eventBus, maxVisible: 3, overflow: 'collapse',
+                                    summaryAction: () => history.open() });
+nc.mount(document.body);
+```
+
+*New in 0.17.0:* **the toast helpers read no global.** `toastInfo` / `toastWarn` /
+`toastError` / `toastSuccess` emit on the bus of the `NotificationCenter` mounted
+last; its `dispose()` hands them back. `setToastBus(bus)` points them at another
+bus (and returns the one it replaced), `setToastBus(null)` back at the console,
+and `getToastBus()` says which is current. With no bus — before any centre is
+mounted — a helper logs to the console and throws nothing. Until 0.17.0 they
+looked for one application's bus on a window global.
+
+### Progress toasts (0.17.0)
+
+A toast can track a job. `show({ progress })` takes a 0..1 fraction,
+`{ value, total }`, or `null` for indeterminate, and draws a `ProgressBar` in
+the toast; `status` is a line under the message and `counts` a label beside the
+bar. A progress toast is persistent, has a collapse toggle (or `collapsed: true`),
+and is not closed by a click on its body or on one of its actions while it runs.
+
+`update(id, patch)` changes only that toast's nodes: `progress`, `status`,
+`counts`, `collapsed`, `message`, `title`, `description`, `severity`. No other
+toast is redrawn, by an update or by toasts arriving and leaving, so a bar, a
+collapsed state and a hover survive (a toast whose title or description appears
+or goes is rebuilt in its place). `update()` also reaches a toast held behind
+"+N more", and `progress` on a plain toast turns it into a running progress
+toast. The toast **runs until a patch gives it an outcome severity**: `success`
+ends the bar done, `error` / `fatal` error; any other severity only restyles it.
+Once finished the bar keeps that state, whatever severity comes later. A
+`durationMs` in a patch to a toast that is not running (re)starts its
+auto-dismiss, and `0` keeps it until closed.
+
+With `overflow: 'collapse'`, a running progress toast is never held behind
+"+N more" and never counted in it (a held toast that starts running through
+`update()` comes on screen at once). It counts toward `maxVisible`, so when the
+screen is full the newest other toast steps back into the queue (first in line
+to return). Once finished it folds like any other toast. With `'drop'`, the
+oldest toast that is not a running job leaves.
+
+```js
+const id = nc.show({ title: 'Batch', message: 'Running', progress: 0, counts: '0 / 200',
+                     actions: [{ label: 'Stop', handler: () => job.stop() }] });
+job.on('tick', (done) => nc.update(id, { progress: { value: done, total: 200 },
+                                         counts: `${done} / 200`, status: job.current }));
+job.on('end', () => nc.update(id, { progress: 1, severity: 'success', message: 'Done', durationMs: 3000 }));
+```
+
+`tests/notification_progress.test.mjs` holds it in jsdom.
+
+### Toast cards are styled and clickable (0.17.2)
+
+A toast card is `.twm-notification` with `.twm-notification--<severity>`
+(`info`, `success`, `warn`, `error`, `fatal`), and the "+N more" summary is
+`.twm-notification.twm-notification--summary`. `flexdesk.css` gives the card its
+background, a left border in the severity's colour (`--color-success`,
+`--color-warning`, `--color-danger`; info keeps the blue) and the entry
+animation `twm-notification-in`, which the sheet now defines. The card sets
+`pointer-events: auto` over the root's `none`, so its buttons and its
+click-to-close work.
+
+Until 0.17.2 the card carried the bare `notification` / `notification--<severity>`
+classes, which no FlexDesk sheet styled: the card had no background and no
+border, and inherited `pointer-events: none`, so its buttons could not be
+clicked. A consumer stylesheet that targeted `.notification` should target
+`.twm-notification` instead. The live region is `.twm-notification-center__live-region`.
+`tests/notification_toast_styles.test.mjs` holds the classes, the cascade and
+the sheets.
+
+### One toast, one history entry, one unread (0.17.3)
+
+`history` holds **one entry per toast**, however it was raised: `show()`, the
+`warn()` / `error()` / `info()` / `success()` helpers, `toast:show`,
+`notification:show` or `log:entry`. A toast that leaves (timeout, ×, overflow,
+`clearAll`) marks its own entry `dismissed: true` with the `reason`, and adds
+no entry. **`nc.subscribe(fn)`** calls `fn(entry, center)` once for each entry
+added, after it is in `history` (not for a `skipHistory` toast, and not for a
+dismissal), and answers the unsubscribe; `dispose()` drops every listener.
+
+`NotificationHistory` follows the centre through `subscribe()`: every entry
+recorded is one unread on the bell until the popover is opened, also past
+`historyLimit`. It no longer watches the bus for toasts, so its
+`notificationCenter` is a `NotificationCenter` (or anything with `history` and
+`subscribe`).
+
+```js
+const off = nc.subscribe((entry) => console.log('recorded', entry.severity, entry.message));
+nc.warn('Disk almost full');          // the bell says 1
+```
+
+Until 0.17.3 the bell counted only on bus events, so a toast raised through
+`show()` / `warn()` / `error()` / `info()` never raised its badge, and a dismissal
+was pushed as a second entry: a toast that timed out was in `history` twice
+and counted twice. `tests/notification_history_follows_center.test.mjs` holds it.
+
+### Alerts with history: a log, a pane, a tab host and a bell (0.14.0)
+
+A toast is the moment. The **alert log** keeps what came in until it is
+dismissed, and four pieces draw it. Each works without the others:
+
+| Piece | Entry point | Does |
+|---|---|---|
+| `createAlertLog({ source, limit })` | `widgets` | Entries `{id, at, level, title, body?, ref?, read}`, newest first; `add`, `receive`, `markRead`, `dismiss`, `unreadCount`, `worstUnread`, `subscribe`, `loadMore` |
+| `localSource({ read, write })` | `widgets` | Keeps the whole log in one stored value (localStorage, a workspace file) |
+| `mountAlertsPane(el, { log, onOpen, onBadge, rules?, stillMatches? })` | `widgets` | Level chips with counts, a filter, day groups, relative times, Open / Dismiss / Mark all read / Clear, *Load older* |
+| `createBottomPanelTabs(el, { panes, remember, store, eventBus })` | `wm` | The `.twm-bp` tab strip, on [`createTabs`](layout-widgets.md#tabs-createtabs-0170): `select`, `setBadge(id, n, level)`, `bottompanel:show {tab}` |
+| `new NotificationHistory({ alertLog, mountPoint, alertsTab, onOpen })` | `widgets` | The bell shows the log's unread count in the worst level's colour; a click (and "+N more") opens the Alerts tab |
+
+A **source** is where entries live: `load({offset, limit})` answers
+`{entries, more?, unread?}`, plus `markRead(ids | null)` and, optionally,
+`dismiss(ids | null)`. Without `dismiss`, the pane offers no Dismiss or Clear.
+Levels are `info`, `warning` and `alert`; `warn`, `error` and `danger` are read as
+those.
+
+```js
+const log = createAlertLog({ source: {
+    load: ({ offset, limit }) => api.notifications({ offset, limit }),
+    markRead: (ids) => (ids ? Promise.all(ids.map(api.readNotification)) : api.readAll()),
+} });
+const tabs = createBottomPanelTabs(panelEl, { eventBus, panes: [
+    { id: 'alerts', label: 'Alerts', eager: true,
+      mount: (el, store, api) => mountAlertsPane(el, { log, onOpen: openRef,
+          onBadge: ({ unread, level }) => api.setBadge('alerts', unread, level) }) },
+] });
+new NotificationHistory({ notificationCenter: nc, eventBus, alertLog: log, mountPoint: statusBarEl }).mount();
+```
+
+An eager pane, and the first one shown, mount inside `createBottomPanelTabs`
+before it returns. Reach the host through `mount`'s `api` argument, not the
+variable being assigned. Without `alertLog` and `mountPoint`, `NotificationHistory`
+is the bell it was.