flexdesk 0.17.18 → 0.18.1

package/docs/components/menus.md

@@ -33,6 +33,10 @@ items they hold:
 
 Nothing changes in how you call them.
 
+## A press inside no longer disarms a context menu (0.18.1)
+
+`showContextMenu` kept its outside-press listener for one press. A press inside the menu (a separator, the padding, a disabled row) used it up, and from then on a press outside was ignored until Escape. It now listens until the menu closes. A consumer's own outside-press listener for this can go.
+
 ## A menu bar: `createMenuBar` (0.17.0)
 
 File / Edit / View menus from one declarative model, instead of hand-built
@@ -307,5 +311,85 @@ category's `color` is any CSS colour; it reaches the rows as
 
 The Add button is FlexDesk's `twm-btn twm-btn--primary`; everything else is
 styled from the tokens (`tests/category_picker.test.mjs` checks there is no
-colour literal in its rules, and that base.css and flexdesk.css carry the same
-block).
+colour literal in its rules).
+
+## A rich popover: `openPopover` (0.18.0)
+
+`openPopover` hangs a panel of your own content off the element that opened it. It
+is not a menu: it holds a form, a list, anything.
+
+```js
+import { openPopover } from '@flexdesk/widgets';
+
+button.addEventListener('click', () => {
+    const pop = openPopover({
+        anchor: button,
+        content: shareForm,
+        label: 'Share',
+        focus: shareForm.querySelector('input'),
+        onClose: (reason) => saveDraft(),
+    });
+    // pop.close(), pop.reposition(), await pop.closed
+});
+```
+
+| Option | What it does |
+| --- | --- |
+| `anchor`, `content` | What it hangs from, and its body |
+| `label`, `className` | Its accessible name (`role="dialog"`), and extra classes on `.twm-popover` |
+| `focus` | What takes focus on open; else the panel. On close, focus held inside it goes back to the anchor |
+| `align` | `'start'` or `'end'`: which anchor edge it lines up with first |
+| `inside` | A selector for floating panels of your own: a press in one is not "outside" |
+| `onClose(reason)` | After it is gone: `'outside'`, `'escape'`, `'toggle'`, `'replaced'`, `'parent'`, `'detached'`, or what you passed to `close` |
+
+It closes on a press outside it, on Escape and when its anchor leaves the page. While open
+the anchor carries `.twm-is-open` and `aria-expanded="true"`. Opening one from the anchor
+that holds an open one closes it: `toggled` is then true and `el` null, so a click handler
+needs no state. Opening one anywhere else closes the open one, unless it owns the new
+anchor (see [layers](#an-anchored-layer-positionanchored-openanchoredlayer-0180)). An anchor that
+is not on the page opens nothing: `el` is null, `toggled` false, `onClose` is not called and
+`closed` is already resolved.
+
+**Tab stays inside**, going round the panel's controls, as in a modal or a `CategoryPicker`.
+The panel is mounted at the end of the page, so past its edge lies whatever comes next in the
+document, and over a modal that is behind the modal. Escape is the way out. A modal's own focus trap
+leaves focus in a layer alone. This is new for the flow kit's popover, whose pickers used
+to close when Tab took focus out of them.
+
+The flow kit's popover is this one with the class `.twm-flow-popover`. It used to place
+itself and now scrolls inside when it fits neither above nor below its anchor, where it used to be
+clamped to the window. `@flexdesk/flow` still exports its own `openPopover`, `closeFlowPopovers`
+and `openFlowPopover`.
+
+## An anchored layer: `positionAnchored`, `openAnchoredLayer` (0.18.0)
+
+There is one placement. `positionAnchored(anchor, panel, { align, gap, margin, matchWidth })`
+is what `ActionDropdown.position` calls, and `CategoryPicker`, a tile's menu, `openPopover`,
+`createSelect` and `createCombobox` place through it: `position: fixed`, under the anchor when it fits there (else
+above it when it fits there, else on the side with more room, scrolling inside), `margin` inside
+the window. `gap` is 8 by default, as it was for `ActionDropdown`.
+
+`openAnchoredLayer({ anchor, el, align, gap, matchWidth, inside, returnFocus, onClose })` is the
+behaviour around it, for a floating panel of your own. It answers `{ el, anchor, place, owns(node), close(reason) }`,
+or `null` when the anchor is not on the page: nothing opened and `onClose` will not be called.
+
+- `el` is mounted on `modalHost()` or the anchor's `document.body`, and taken off on
+  close, so a closed layer leaves nothing on the page.
+- It is placed again on a window resize, on a scroll outside it and when its size
+  changes. An anchor gone from the page closes it.
+- **Layers stack.** What a layer owns is one answer, for a press and for an anchor: its panel,
+  the layers above it, an `ActionDropdown` menu, a `CategoryPicker`, a context menu, a modal window
+  shown after it opened (a dialog its content opened), and what `inside` names. Opening a layer
+  closes every layer that does not own its anchor. A press on what a layer owns, or on its anchor,
+  is not outside it. Closing a layer closes those above it.
+  So a select in a popover works, a press in the select's list does not close the popover,
+  and neither does a list opening in a dialog the popover opened.
+- **Escape goes to the top layer and to nothing else**, so the `ManagedWindow` around the field stays
+  open. From inside the panel it is heard as it bubbles out, so that the panel's content
+  can answer first, by stopping it or preventing its default.
+- An open menu or picker, and a modal shown after the layer opened, have Escape first. A modal
+  already showing when the layer opened is under it, however long the chain of layers between them,
+  and hears Escape only when the layers are gone.
+- `isInAnchoredLayer(node)` says whether a node is in an open layer, for a focus trap of your own.
+
+`tests/select_combobox_popover.test.mjs` covers these in jsdom.

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

@@ -157,8 +157,7 @@ Text that is not JSON was always handled: the host logs `[host] bad JSON for
 state key desktops` and answers `null`. A layout that is valid JSON but not a
 layout (a split whose `sizes` is a number, a `null` desktop, a split with no
 `children`) used to make `createShell` throw, on every start, until the file was
-deleted by hand, so an app had to vet the file before booting. Others were let
-through half understood: a desktop with no `tree` came back as an empty one.
+deleted by hand, so an app had to vet the file before booting.
 
 Now such a layout is ignored. `createShell` resolves, the shell opens its
 default layout exactly as it does when nothing was saved, and one warning names
@@ -181,8 +180,8 @@ loggers) records that line as the message, with the key and the cause in it.
   (any change to it) that save replaces the file, and until then every start
   warns again.
 - **What is unreadable** is a shape `serialize()` could not have written:
-  `desktops` not a non-empty array; a desktop that is not an object, or has no
-  `tree` (a `tree` of `null` is a desktop with nothing on it, and is fine); a
+  `desktops` not a non-empty array; a desktop that is not an object, or whose
+  `tree` is something other than `{ root }`, `null` or absent; a
   `panels` or `panelShares` that is not an object; a node that is not a `leaf`
   or a `split`; a split without a `dir` of `h` or `v`, without children, or
   whose `sizes` are not one non-negative number per child; a tab without a
@@ -193,7 +192,7 @@ loggers) records that line as the message, with the key and the cause in it.
   `group` and `fixed`, a panel's flag, a tab's props. A layout saved by an
   earlier release loads too: the keys that came later (`panelShares`, `group`,
   `fixed`, a leaf's `pageTabs`) may be missing, and so may a desktop's `id`,
-  `label` and `panels`, and a leaf's `tabs`. Keys it does not know are ignored, a
+  `label`, `tree` and `panels`, and a leaf's `tabs`. Keys it does not know are ignored, a
   tab of a kind with no factory registered is the usual placeholder tile, and an
   `activeIdx` past the last desktop is clamped.
 
@@ -201,5 +200,17 @@ loggers) records that line as the message, with the key and the cause in it.
 throws the `TypeError` above for a blob that cannot be read, which is what
 `wm.load()` catches; `wm.load()` itself does not throw for one.
 
+### A desktop with no `tree` is an empty desktop (0.18.0)
+
+A desktop whose `tree` is `null` or absent has nothing on it. It loads, its
+siblings load with it, and the shell seeds it with the root kind. A host that
+composes the blob can leave the key out: one that rebuilds a desktop per page on
+every boot, say, and keeps only the desktops the user made.
+
+From 0.17.14 to 0.17.18 an absent `tree` counted as unreadable. All or nothing
+then set the user's desktops aside with it, and the next layout change saved the
+default layout over them for good. A host like that must not ship on those
+releases unless it writes `tree: null`.
+
 `tests/saved_layout_unreadable.test.mjs` boots a real shell over each of 78
 shapes of broken layout and over the readable ones.

package/docs/components/shell.md

@@ -2,13 +2,14 @@
 
 > **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.
+`createShell` boots the tiling window manager into an element of your page: tiles that split and tab, the top navigation or a page rail, 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)
+- [The pages as a vertical rail: `chrome.rail` (0.18.0)](#the-pages-as-a-vertical-rail-chromerail-0180)
 - [A kind that exists once: `single` (0.17.0)](#a-kind-that-exists-once-single-0170)
 - [A kind that exists once per desktop: `single: 'desktop'` (0.17.17)](#a-kind-that-exists-once-per-desktop-single-desktop-01717)
 - [An open single instance takes new props: `navigate(props)` (0.17.2)](#an-open-single-instance-takes-new-props-navigateprops-0172)
@@ -36,6 +37,112 @@ await createShell({
 });
 ```
 
+## Keyboard focus shows a tooltip (0.18.1)
+
+`TooltipService` shows a `twm-has-tooltip` element's tooltip (or a `has-latex-tooltip` element's) when it takes keyboard focus, as hovering does, and hides it when focus leaves the element or on Esc. Focus moving inside the element keeps it. A pointer does not take it down: over another target the pointer's tooltip shows for as long as the pointer stays, then focus's comes back. A scroll does not hide it, the one the focus itself caused included: it goes with its target, and waits while a wheel has the target out of sight. Keyboard focus means the last press was a key, not a Ctrl, Cmd or Alt chord: the focus a click leaves shows nothing, nor does a field its handler then focuses. The browser's `:focus-visible` cannot tell this, being true for any text field. A consumer that wires `focusin` to `TooltipService.show` itself can stop.
+
+## The pages as a vertical rail: `chrome.rail` (0.18.0)
+
+`chrome.topNav` paints the pages as a strip in the top bar. `chrome.rail` paints
+them as a fixed-left icon bar instead. Give it the element, and put the element
+beside the window manager's host in a `.twm-workspace`:
+
+```html
+<body class="twm-body">
+    <div class="twm-global-top-bar">…</div>
+    <div class="twm-workspace">
+        <nav id="rail" aria-label="Sections"></nav>
+        <main id="root" class="twm-host"></main>
+    </div>
+    <div class="twm-global-bottom-bar">…</div>
+</body>
+```
+
+```js
+const taxonomy = createTaxonomy({
+    root: 'start',
+    kinds: {
+        start:    { label: 'Start', icon: 'apps' },
+        atlas:    { label: 'Atlas', icon: 'map', isTopNav: true, order: 10 },
+        log:      { label: 'Ship log', icon: 'article', isTopNav: true, order: 20 },
+        settings: { label: 'Settings', icon: 'settings', isTopNav: true, railPin: 'bottom' },
+    },
+});
+
+await createShell({
+    root: document.getElementById('root'),
+    taxonomy, entities, content,
+    chrome: { rail: document.getElementById('rail') },
+});
+```
+
+- **The look.** 50px wide, 44px items, 22px icons at weight 300. An item is grey
+  at rest and white on hover; the active one is white, with a white 2px bar at
+  its left on a transparent background; keyboard focus draws the accent outline.
+  A window too short for the items scrolls the bar, with no scrollbar. No
+  stylesheet of yours is needed.
+- **`railPin: 'bottom'`** on a top-nav kind holds it at the bottom of the bar.
+  Pinned kinds come after the rest, in their own `order`, and stay together.
+  A `railPin` of any other value, or on a kind that is not `isTopNav`, is a boot
+  error. The top strip ignores it. A kind such as a settings page can be
+  `isTopNav` and `appGlobal` at once.
+- **F1..F12 press the rail's buttons in the order they are drawn**, pinned ones
+  last, with no `navSelector`. `navSelector` remains for page buttons in markup
+  of your own.
+- **Tooltips open to the right** of the bar, flipping at the window's edge, with
+  no attribute or patch of yours. They name the kind's `label`, and so do the
+  buttons' `aria-label`s (a `shortLabel` is for the strip's chips). As for every
+  `twm-has-tooltip` element, `TooltipService` draws them, and it comes with
+  `@flexdesk/widgets`: a page that imports only `@flexdesk/wm` has the labels
+  and no tooltips.
+- **The layout.** `.twm-workspace` takes the host's place in `body.twm-body`'s
+  column, and a `.twm-host` inside it fills what the rail leaves, with the rule
+  a host directly under the body has. Outside `body.twm-body`, a `.twm-workspace`
+  needs a parent that gives it a height, as a host does.
+- **The element is yours.** It gains `.twm-fl-bar` and, if it has none, the
+  `aria-label` "Pages". `shell.chrome.railEl` hands it back. `shell.dispose()`
+  empties it and takes the listener off, so a rebuilt shell paints its own.
+- **One row of pages.** `chrome.rail` with `chrome.topNav` is a boot error.
+
+Retheme or resize it from `tokens.css`:
+
+| Token | Default | |
+|---|---|---|
+| `--twm-rail-bg` | `#333333` | the bar |
+| `--twm-rail-icon` | `#9e9e9e` | an item at rest |
+| `--twm-rail-icon-on` | `var(--text-bright)` | an item hovered, the active item and its bar |
+| `--twm-rail-width` | `50px` | the bar's width |
+| `--twm-rail-item-height` | `44px` | an item's height |
+| `--twm-rail-icon-size` | `22px` | the icon's size |
+
+If you supply your own token definitions instead of `tokens.css`, define these
+too: the rules that read them have no fallback.
+
+### Without `createShell`: `mountPageRail(el, { wm, activeKind?, decorate? })`
+
+`@flexdesk/wm` exports the painter, for an embedder that constructs its own
+`WindowManager`. It answers `{ el, sync(), dispose() }`; call `sync()` when the
+window manager changes (`onChange`, `wm:changed`), once after the first load, and
+`dispose()` when the rail goes. The keymap's default finds these buttons too.
+
+```js
+const rail = mountPageRail(document.getElementById('rail'), {
+    wm,
+    // Which page to light, or null for none. Default: the primary tile's page.
+    activeKind: (w) => pageOf(w),
+    // Once per button, with its topNavEntries() entry.
+    decorate: (btn, entry) => {
+        if (entry.kind === 'archive') btn.dataset.tooltip = 'Archive: shared by every crew';
+    },
+});
+```
+
+**What changed for existing markup.** `.twm-fl-bar` and `.twm-fl-item` had rules
+and no code that drew them. `.twm-fl-bar` now has the rail's width, background
+and overflow and no `height: 100%` (it stretches in its flex row), and
+`.twm-fl-item`'s grey comes from `--twm-rail-icon`. Nothing changes for a shell
+that uses `chrome.topNav`. `topNavEntries()` gains `railPin` (null unless set).
+
 ## A kind that exists once: `single` (0.17.0)
 
 Some content holds heavy app-wide state and must not be mounted twice. Mark its

package/docs/components/workspace-picker.md

@@ -0,0 +1,193 @@
+# Workspace picker
+
+> **Package:** `@flexdesk/widgets` · **See also:** [Menus](menus.md) · [Host port](../concepts/host-port.md) · [All docs](../README.md)
+
+A field in the top bar that names what the window is working in, a switcher that changes it, and a store for "recently opened". FlexDesk does not know what is being picked: the items, the words and what a pick does are yours.
+
+## A field and a switcher: `createWorkspacePicker` (0.18.0)
+
+```js
+import { createWorkspacePicker } from '@flexdesk/widgets';
+
+const picker = createWorkspacePicker(topBar, {
+    field: {
+        layout: 'centered',
+        avoid: '.bar-left > *, .bar-right > *',
+        icon: 'folder',
+        placeholder: 'Nothing open',
+        tooltip: 'Click to switch workspace',
+    },
+    chord: 'Ctrl+P',                     // none by default
+    label: 'Switch workspace',
+    placeholder: 'Switch workspace: type to filter, Enter to open',
+    glyph: 'folder_open',
+    load: () => recent.list(),
+    describe: (item, { current }) => ({
+        id: item.id,
+        name: item.name,
+        detail: item.location,
+        icon: current ? 'folder_open' : 'folder',
+        badge: current ? 'current' : '',
+    }),
+    onPick: (item) => openWorkspace(item),
+    onRemove: (item) => recent.remove(item),
+    actions: () => [
+        { id: 'new', label: 'New workspace', icon: 'add', run: () => createOne() },
+        { id: 'open', label: 'Open…', icon: 'folder_open', run: () => openOne() },
+    ],
+});
+
+picker.setCurrent(openNow);              // named on the field, marked in the list
+```
+
+A click on the field or the chord opens the switcher in the field's place, with its input over the field, so the field reads as a search box growing its results. A pick closes it, gives focus back to where it was, and calls `onPick`, or nothing if the row is the current one. What `onPick` does is yours: navigate the whole window, or swap what is open in place.
+
+It returns `{ el, field, switcher, isOpen, current, open({select}), close(), toggle(), setCurrent(item), refresh(), reload(), destroy() }`. `createWorkspacePicker(hostEl, options)` takes everything `createPickerSwitcher` takes, and:
+
+| Option | |
+|---|---|
+| `field` | `mountPickerField`'s options, plus `placeholder`: its name while nothing is current (drawn muted). `field.icon` is its icon whatever is current; without it the current item's `icon` is used. |
+| `chord` | `'Ctrl+P'`, `'Ctrl+Shift+O'`. None by default. Ctrl also answers to Cmd, modifiers are exact, and a held key does not repeat. It is taken on `window` in the capture phase, ahead of an embedded editor and the browser's own use of the key, and it becomes the field's key hint unless `field.keyHint` says otherwise. It still works while the field is hidden for want of room. |
+
+## The field: `mountPickerField` (0.18.0)
+
+`mountPickerField(hostEl, options)` appends a real `<button>` to `hostEl` and returns `{ el, update(patch), setOpen(open), fit(), destroy() }`.
+
+| Option | Default | |
+|---|---|---|
+| `name`, `icon`, `keyHint`, `tooltip`, `ariaLabel` | empty | Drawn when given. `update` changes any of them, and `muted`. |
+| `muted` | `false` | The name drawn as naming nothing (`update({ name: 'n/a', muted: true })`). |
+| `caret` | `false` | A trailing caret, for a field that reads as a dropdown. |
+| `className` | | Extra classes. |
+| `layout` | `'inline'` | `'centered'` stands it in the middle of `hostEl`, whatever stands left and right. |
+| `avoid` | | Centred: a selector, within `hostEl`, of what it must not cover. An element counts on the side its centre is on; one taking no room does not count. |
+| `maxWidth`, `minWidth`, `tightWidth`, `gap` | 440, 120, 230, 24 | Centred, its width is the room the tighter side leaves, twice over, less `gap`, up to `maxWidth`. Below `tightWidth` the key hint goes. Below `minWidth` the field is hidden. |
+| `onActivate` | | A click. |
+
+A centred field's `hostEl` must be positioned. It measures again whenever `hostEl` resizes and when the fonts arrive; call `fit()` after you change what stands beside it. An inline field's width is its host's, and only the key hint responds, to its own width.
+
+## The switcher: `createPickerSwitcher` (0.18.0)
+
+`createPickerSwitcher(options)` is the panel alone, on any anchor or on none. `createWorkspacePicker` is this plus a field.
+
+**Where it opens.** `placement: 'over'` (the default) lays the input over `anchor`, at least `minWidth` (520) wide, kept inside the window; an anchor in the lower half of the window grows the panel upward instead. `placement: 'below'` hangs from it through `ActionDropdown.position`, flipped above when there is no room. With no `anchor`, or one that takes no room, it stands centred over a dimmed page. A window resize places it again.
+
+**What it lists.** `load({ query, offset, limit, signal })` answers an array or `{ items, total?, status? }`, now or in a promise, and is asked on every open, so a list edited behind the page is never stale for long. The last unsearched answer per `cacheKey()` is drawn at once while it is asked again. `status` is the footer's left end, a string or `{ text, error }`. Only the newest question's answer paints; `signal` aborts the older ones.
+
+| `search` | |
+|---|---|
+| `'local'` (default) | Asked once per open. Typing filters what it answered, on the name, `detail` and `keywords`, with name matches first. |
+| `'remote'` | Typing is debounced (`debounceMs`, 200) and asked again. A `total` above what is drawn offers **Load more**, `pageSize` (20) at a time. A server that hands back only what is drawn has no more, whatever it said before. A failed page keeps the rows and says so. |
+
+`describe(item, { current })` turns an item into a row:
+
+| Field | |
+|---|---|
+| `id` | Required. Two items with one `id` are one row. Make it the form you compare by: `setCurrent` and `open({ select })` go through it. |
+| `name` | Required. |
+| `detail` | A second line. |
+| `icon`, `badge` | An icon, and a short word on the right (the word for the current row, if you want one; the check mark is always drawn). |
+| `keywords` | A string or an array: searched, not drawn. |
+| `disabled` | Drawn greyed, stepped over by the arrows. |
+| `removable` | `false` takes the bin off this row. |
+| `title` | The row's tooltip; by default its name and detail. |
+
+**The rest of the panel**, every part optional:
+
+| Option | |
+|---|---|
+| `onRemove(item)` | A bin on each row, and Shift+Delete on the highlighted one. May answer a promise: while it is unsettled the panel stays open and it and its dimmed page step below managed windows, so a confirmation dialog can be answered with the mouse. Answering `false` keeps the row, rejecting keeps it and shows the error, anything else drops it and asks `load` again. The highlight moves to the next row. |
+| `actions({ query })` | Rows after the items: `{ id, label, detail?, icon?, always?, run({ query }) }`. Typing narrows them on their `label` unless `always`, which is how a row offering to create what was typed stays; when nothing else matches, it is what Enter takes. |
+| `heading({ query, shown, total })` | `{ title, count }` over the list. |
+| `card({ current, row })` | A panel under the list for the current item: `{ heading?, icon?, name, detail?, open?: { label, icon?, run }, columns?, tiles?: [{ id, label, icon?, run }] }`, or `null`. `row` is the current item as the list read it, when it has. |
+| `footer()` | `{ start?, end?, keys? }`. `start` and `end` are buttons, `{ id, label, icon?, trailing?, primary?, run }`. `keys`, `[{ keys: ['Shift', 'Del'], label: 'remove' }]`, are drawn only when the panel is centred. |
+| `visibleRows` | Scroll past this many two-line rows. |
+| `labels` | Any of `loading`, `empty()`, `noMatch(query)`, `failed(err)`, `failedMore(err)`, `failedRemove(err)`, `loadMore({ next, shown, total })`, `remove(name)`. |
+| `label`, `listLabel`, `placeholder`, `glyph`, `className`, `onOpenChange(open)` | The panel's and the list's accessible names, the input's placeholder and icon, extra classes, and a callback. |
+
+`refresh()` asks `actions`, `card` and `footer` again. `reload()` asks `load` again. `open({ select })` highlights the row with that `id` when the answer lands. `setCurrent(item)` takes the item whether or not any page holds it.
+
+**Nothing is rebuilt under a pointer.** Every part is reconciled by key, so an answer landing while a row is being pressed leaves that row's node in place and the click still fires.
+
+### The keyboard (0.18.1)
+
+Focus is real: what the keyboard is on is `document.activeElement`, so a screen reader says each stop, the card's and the footer's buttons included, and Tab and the arrows agree about where the reader is.
+
+| Key | |
+|---|---|
+| The arrows | Walk focus over every stop, wrapping: the input, the rows that can be chosen (a disabled one is stepped over), Load more, the action rows, the card's buttons, the footer's. After `open({ select })` they start from the row it chose. An answer or a redraw leaves focus where it is, on a row that moved too. |
+| Tab | The rows are one tab stop: the row last focused, else the current one, else the first. So are the action rows. Out of the panel closes it. |
+| A character | Goes to the input from anywhere in the panel, and to nothing else: a keymap does not read it as a shortcut. |
+| Enter in the input | Takes what wears the highlight: the first row or action row of what is shown, or, while the answer to what was typed is on its way, the first one when it lands. |
+| Enter or Space elsewhere | Takes the row or runs the button with focus. |
+| Shift+Delete | Removes the row with focus, or the highlighted one from the input. Focus goes on to the next row. |
+| Backspace | The input's in the input. Elsewhere it stops at the panel, where a window manager's keymap would read it as "up one level". |
+| Esc | Closes, and gives focus back to where it was. |
+
+A press outside closes and leaves focus where it was pressed. A row that held focus and went away, because an answer no longer holds it, gives focus to the input. Load more keeps focus while something loads: it is `aria-disabled` then, not `disabled`, and refuses the press itself.
+
+### A trigger of your own (0.18.1)
+
+The field is optional. `createPickerSwitcher` opens on any anchor, so a control of yours can be the trigger:
+
+```js
+const switcher = createPickerSwitcher({
+    anchor: trigger,
+    placement: 'below',
+    visibleRows: 5,
+    load, describe, onPick, card, footer,
+    onOpenChange: (open) => trigger.setAttribute('aria-expanded', String(open)),
+});
+trigger.addEventListener('click', () => switcher.toggle());
+```
+
+A press on the anchor does not count as a press outside, and Esc, a pick or a verb give focus back to it when it had focus. `setCurrent(item)` on the switcher marks the row; naming it on your trigger is yours.
+
+## The field's look: tokens (0.18.1)
+
+Set these over FlexDesk's defaults (`css/tokens.css`) instead of overriding the field's rules:
+
+| Token | Default | |
+|---|---|---|
+| `--twm-wspicker-field-icon` | `var(--accent-bright)` | Its icon. |
+| `--twm-wspicker-field-focus-border` | `var(--accent-bright)` | Its border, focused by keyboard and while open. |
+| `--twm-wspicker-field-muted-icon` | `var(--text-muted)` | Its icon while it names nothing (`muted`). |
+| `--twm-wspicker-field-muted-style` | `italic` | Its name's `font-style` while muted. |
+| `--twm-wspicker-field-muted-opacity` | `0.55` | Its name's opacity while muted. |
+
+## Recently opened: `createRecentItems` (0.18.0)
+
+A most-recent-first list kept through the [host's](../concepts/host-port.md) `state` capability.
+
+```js
+import { createRecentItems } from '@flexdesk/widgets';
+
+const recent = createRecentItems({
+    host,
+    key: 'recent-workspaces',
+    identity: (entry) => entry.path.replace(/\\/g, '/'),
+    isValid: (entry) => typeof entry?.path === 'string' && entry.path !== '',
+    onChange: () => bus.emit('recent:changed'),
+    logger,
+});
+await recent.load();
+
+recent.add({ path, name });     // stamped `openedAt`, moved to the top
+recent.remove({ path });        // by identity
+recent.clear();
+recent.list();                  // frozen copies, most recent first
+```
+
+| Option | Default | |
+|---|---|---|
+| `host`, `key` | required | The host, and the state key. |
+| `identity` | `entry.id` | Which two entries are the same one. |
+| `isValid` | `identity` answers something | Stored entries failing this are dropped on read, as is one that makes it, `identity` or `groupOf` throw, so `identity` may assume an entry's shape. |
+| `capacity` | 10 | The most entries kept, per group. |
+| `groupOf` | one group | Counted per group, so one busy kind of entry never pushes another out. |
+| `onChange` | | After every change, and after a read that replayed changes. |
+| `logger` | | Its `warn` hears a failed read or write. |
+
+**A read that fails is not an empty list.** While `host.state.read` rejects, `load()` answers `false` and the stored list is never written, because writing would replace entries nobody has seen. Changes made meanwhile show in `list()` at once, each asks for the read again, and they are replayed onto the stored list when it is read, which is then written. A read answering something other than an array is a read of an empty store. Once a read has succeeded, `load()` does not read again.
+
+Writes run one at a time and the last carries the latest list, so a host answering out of order cannot leave the older list stored. A host with no `state` keeps the list in memory for the session.

package/docs/concepts/building-and-packaging.md

@@ -19,8 +19,8 @@ map. See `.gitignore` — it says so there too, because it is the kind of thing
 Every JavaScript entry in the `exports` map has two conditions: `import`, the
 prebuilt bundle under `dist/`, and `development`, the source barrel at the
 package root (`core.js`, `host.js`, `wm.js`, `widgets.js`, `charts.js`,
-`tiles.js`, `editor.js`, `canvas.js`, `flow.js`), which re-exports `src/`.
-Up to 0.17.0 those nine barrels were missing from `files`, so the published
+`tiles.js`, `editor.js`, `canvas.js`, `flow.js`, `git.js`), which re-exports `src/`.
+Up to 0.17.0 those barrels were missing from `files`, so the published
 package did not contain them and a resolver that took the `development` branch
 (`require.resolve` under `--conditions=development`, for one) got a path to
 nothing. From 0.17.1 they ship, beside the `src/` they import.

package/docs/concepts/packages-and-entry-points.md

@@ -2,26 +2,27 @@
 
 > **Install:** see the [quickstart](../quickstart.md) · **Component pages:** [docs index](../README.md#components) · [All docs](../README.md)
 
-## Nine entry points
+## Ten entry points
 
 Because someone who wants a DataTable should not have to download a window
 manager, and neither of them should drag in a plotting engine or a code editor.
 
 | Entry | Size | What is in it |
 |---|---|---|
-| `@flexdesk/core` | 30 kB | Event bus, settings store, logging, state machine, state guard |
-| `@flexdesk/host` | 5 kB | The [host port](host-port.md) |
-| `@flexdesk/wm` | 166 kB | Tiling window manager: tabs, splits, desktops, command palette, taxonomy, `createShell()` |
-| `@flexdesk/widgets` | 192 kB | DataTable, modals, managed windows, toasts, trees, panels, context menus, menu bars, a document outline, progress, a conversation view |
-| `@flexdesk/charts` | 26 kB | Plotly wrapper, chart types, subplot layouts, downsampling, a plot grid, a plot-config editor, plot windows, injected series transforms |
-| `@flexdesk/tiles` | 67 kB | Draggable/resizable widget grid, tile base class, widget registry, layout persistence, figure, chart and KPI tiles |
-| `@flexdesk/editor` | 62 kB | Monaco loader + factory, multi-file tab bar, search, split panes, undo manager |
-| `@flexdesk/canvas` | 14 kB | The canvas kernel: a pannable, zoomable surface, the edge router, a generic graph layer ([Flow editors](../components/flow-editors.md#flow-editors)) |
-| `@flexdesk/flow` | 381 kB | The flow-editor kit and the canvas, outline and lane editors ([Flow editors](../components/flow-editors.md#flow-editors)) |
+| `@flexdesk/core` | 32 kB | Event bus, settings store, logging, state machine, state guard |
+| `@flexdesk/host` | 18 kB | The [host port](host-port.md) |
+| `@flexdesk/wm` | 403 kB | Tiling window manager: tabs, splits, desktops, command palette, taxonomy, `createShell()` |
+| `@flexdesk/widgets` | 413 kB | DataTable, modals, managed windows, toasts, trees, panels, context menus, menu bars, a document outline, progress, a conversation view, an assistant chat shell, a rich select, a combobox, a popover, a filter builder, a workspace picker |
+| `@flexdesk/charts` | 49 kB | Plotly wrapper, chart types, subplot layouts, downsampling, a plot grid, a plot-config editor, plot windows, injected series transforms |
+| `@flexdesk/tiles` | 133 kB | Draggable/resizable widget grid, tile base class, widget registry, layout persistence, figure, chart and KPI tiles |
+| `@flexdesk/editor` | 49 kB | Monaco loader + factory, multi-file tab bar, search, split panes, undo manager |
+| `@flexdesk/canvas` | 5 kB | The canvas kernel: a pannable, zoomable surface, the edge router, a generic graph layer ([Flow editors](../components/flow-editors.md#flow-editors)) |
+| `@flexdesk/flow` | 480 kB | The flow-editor kit and the canvas, outline and lane editors ([Flow editors](../components/flow-editors.md#flow-editors)) |
+| `@flexdesk/git` | 47 kB | A source-control panel, an SVG commit graph and a diff viewer, over a written adapter contract ([Git panel](../components/git.md)) |
 
-The sizes of `@flexdesk/canvas` and `@flexdesk/flow` are the entry files as
-`node build.mjs` reported them for the flow editors' integration build; like
-every entry they also import shared chunks. The other rows are older figures.
+The sizes are the entry files as `node build.mjs` reports them for 0.18.0,
+unminified. Every entry also imports shared chunks, which load once however many
+entries use them; the build prints their total.
 
 They share code through chunks, so importing two of them does **not** give you two
 event buses — and therefore not two copies of every module-level singleton. A test

package/docs/concepts/state-guard.md

@@ -40,7 +40,7 @@ global; choose strict mode in your own code.
 write, so the shell, dialogs, forms, tooltips, tiles and flow editors run under
 `mode: 'strict'` with no violation. The list also carries keys that FlexDesk
 itself does not write, and it has not been audited key by key
-([what 0.18.0 took out and what stayed](#thirteen-application-keys-leave-the-defaults-0180)).
+([what 0.17.14 took out and what stayed](#thirteen-application-keys-leave-the-defaults-01714)).
 A key that names your application's concepts is yours to add, on top:
 
 ```js
@@ -59,13 +59,13 @@ capital letter becomes `-` plus its lower-case form. So `rowID` is `row-i-d`
 Before 0.17.0 a camelCase entry never matched, and some entries named keys no
 element carries.
 
-### Thirteen application keys leave the defaults (0.18.0)
+### Thirteen application keys leave the defaults (0.17.14)
 
 **Breaking for an application that writes one of these keys under a strict
 guard.** `DEFAULT_STATE_GUARD_CONFIG.allowedDatasetKeys` no longer lists
 thirteen keys that belonged to one embedding application, not to FlexDesk. No
 FlexDesk widget writes any of them, so nothing FlexDesk draws changes; what
-changes is that a write of one is now on no allow-list. Before 0.18.0 the
+changes is that a write of one is now on no allow-list. Before 0.17.14 the
 defaults let it through silently, for every application that used them.
 
 | Group, as the list labelled it | Keys removed |

package/docs/quickstart.md

@@ -14,7 +14,7 @@ The package ships a prebuilt `dist/`. Copy it into your site (the examples below
 mkdir -p vendor && cp -r node_modules/flexdesk/dist vendor/flexdesk
 ```
 
-Under a bundler you need none of that. Import the entries as `flexdesk/core`, `flexdesk/host`, `flexdesk/wm`, `flexdesk/widgets` (and `flexdesk/charts`, `flexdesk/tiles`, `flexdesk/editor`, `flexdesk/canvas`, `flexdesk/flow`), and the stylesheets as `flexdesk/css/tokens`, `flexdesk/css/reset` and `flexdesk/css`. The rest of these docs write the entries as `@flexdesk/wm` and so on, which is the name the import map below gives them.
+Under a bundler you need none of that. Import the entries as `flexdesk/core`, `flexdesk/host`, `flexdesk/wm`, `flexdesk/widgets` (and `flexdesk/charts`, `flexdesk/tiles`, `flexdesk/editor`, `flexdesk/canvas`, `flexdesk/flow`, `flexdesk/git`), and the stylesheets as `flexdesk/css/tokens`, `flexdesk/css/reset` and `flexdesk/css`. The rest of these docs write the entries as `@flexdesk/wm` and so on, which is the name the import map below gives them.
 
 ## The page
 

package/git.js

@@ -0,0 +1,13 @@
+/**
+ * @flexdesk/git — a source-control panel, an SVG swimlane commit graph and a
+ * diff viewer, over a written adapter contract (docs/components/git.md).
+ *
+ * It runs no git and reaches no backend by itself: every repository operation
+ * is a method of the adapter object the application passes in.
+ *
+ * HAND-WRITTEN, not generated. The barrels that say "GENERATED by
+ * scripts/gen_barrels.py" name a script that is not in this repository: add a
+ * module to src/git/index.js when you add one under src/git/.
+ */
+
+export * from './src/git/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flexdesk",
-    "version": "0.17.18",
+    "version": "0.18.1",
     "description": "A tiling window manager and widget set for desktop-class web applications. Zero runtime dependencies.",
     "license": "MIT",
     "repository": {
@@ -27,6 +27,7 @@
         "editor.js",
         "canvas.js",
         "flow.js",
+        "git.js",
         "css",
         "docs",
         "README.md",
@@ -73,6 +74,10 @@
         "./flow": {
             "import": "./dist/flow.js",
             "development": "./flow.js"
+        },
+        "./git": {
+            "import": "./dist/git.js",
+            "development": "./git.js"
         }
     },
     "scripts": {