flexdesk 0.17.18 → 0.18.0

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,108 @@ await createShell({
 });
 ```
 
+## 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,149 @@
+# 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.
+
+**The keyboard.** The caret stays in the input. The arrows walk a highlight over the rows, Load more, the action rows, the card's buttons and the footer's, wrapping. Until they move, the highlight is the first row or action row, and Enter takes it, or, while the answer to what was typed is on its way, the first one when it lands. Esc closes and gives focus back to where it was. A press outside closes and leaves focus where it was pressed. Tab goes to the panel's buttons, and out of the panel closes 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.
+
+## 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.0",
     "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": {

package/src/flow/kit/dom.js

@@ -1,27 +1,16 @@
 /**
- * THE KIT'S SMALL DOM HELPERS, AND ITS ONE POPOVER.
+ * THE KIT'S SMALL DOM HELPERS, AND ITS POPOVER.
  *
  * Everything here builds elements; nothing here reads the network, storage or
- * a consumer's vocabulary. The popover is the step picker's and *Insert a
- * value*'s shell (36 §3.5, §3.7):
- *
- *  - it is appended to FlexDesk's modal host (`modalHost()`, C25) or to
- *    `document.body` — the same question a modal and a context menu ask, so a
- *    consumer spanning two browser windows gets it in the window it set;
- *  - it is `position: fixed`, placed under its anchor (above when there is no
- *    room below) and CLAMPED to the viewport;
- *  - it is dismissed by a press outside it, by Escape, or by `close()`, and
- *    **it returns focus to its anchor** when it closes with focus inside it —
- *    a picker that drops focus on `<body>` drops it where an editor's keys
- *    never arrive — except when focus has just left it by Tab, which the
- *    pickers close it for (`'blur'`): that focus is going where it was sent;
- *  - there is ONE at a time: opening a second closes the first, and opening one
- *    from the anchor that holds the open one closes it (a toggle);
- *  - `closeFlowPopovers()` closes whichever is open, which is what an editor's
- *    `destroy()` calls so that nothing it opened outlives it.
+ * a consumer's vocabulary. The popover, the step picker's and *Insert a value*'s
+ * shell (36 §3.5, §3.7), is FlexDesk's `openPopover`, which says how it is placed,
+ * dismissed and toggled and that it returns focus to its anchor: a picker that
+ * drops focus on `<body>` drops it where an editor's keys never arrive. What the
+ * kit adds is `closeFlowPopovers()`, which closes whichever of its own is open:
+ * what an editor's `destroy()` calls so that nothing it opened outlives it.
  */
 
-import { modalHost } from '../../ui/components/modal.js';
+import { openPopover as openAnchoredPopover } from '../../ui/components/popover.js';
 
 /** The category tones (36 §3.1, §3.12); the stylesheet maps each to tokens. */
 export const TONES = Object.freeze(['violet', 'teal', 'amber', 'grey', 'blue', 'indigo']);
@@ -81,118 +70,38 @@ export function uid(stem = 'flow') {
 
 // ── the popover ──────────────────────────────────────────────────────────
 
-const EDGE = 8;
-const GAP = 4;
-let ACTIVE = null;
+/** The kit's open popovers, oldest first. */
+const OPEN = [];
 
-/** Close whichever kit popover is open. */
+/** Close every kit popover that is open. */
 export function closeFlowPopovers() {
-    ACTIVE?.close('closed');
+    OPEN[0]?.close('closed');
 }
 
-/** The open popover's element, or null — for a test. */
+/** The open popover's element (the innermost's), or null — for a test. */
 export function openFlowPopover() {
-    return ACTIVE ? ACTIVE.el : null;
+    return OPEN.length ? OPEN[OPEN.length - 1].el : null;
 }
 
 /**
- * Put `content` in a popover under `anchor`.
+ * FlexDesk's popover (`openPopover` in `ui/components/popover.js`), wearing the
+ * kit's class and remembered so that an editor can close what it opened.
  *
- * @param {object} o
- * @param {HTMLElement} o.anchor     what opened it; focus returns here
- * @param {HTMLElement} o.content    the popover's body
- * @param {string} o.label           its accessible name (`role="dialog"`)
- * @param {string} [o.className]     an extra block class
- * @param {(reason: string) => void} [o.onClose]  after it is gone
- * @param {HTMLElement} [o.focus]    what takes focus on open
- * @returns {{el: HTMLElement, close: (reason?: string) => void, reposition: () => void, toggled: boolean}}
- *          `toggled` is true when the call only CLOSED the popover its anchor held.
+ * @param {object} o  What `openPopover` takes.
+ * @returns {{el: HTMLElement|null, close: (reason?: string) => void, reposition: () => void, toggled: boolean}}
+ *          `el` is null when nothing opened; `toggled` is true when the call only
+ *          CLOSED the popover its anchor held.
  */
-export function openPopover({ anchor, content, label, className = '', onClose = null, focus = null }) {
-    if (ACTIVE && anchor && ACTIVE.anchor === anchor) {
-        ACTIVE.close('toggle');
-        return { el: null, close() {}, reposition() {}, toggled: true };
-    }
-    ACTIVE?.close('replaced');
-
-    const pop = el('div', `twm-flow-popover${className ? ` ${className}` : ''}`);
-    pop.setAttribute('role', 'dialog');
-    pop.setAttribute('aria-label', label || '');
-    pop.tabIndex = -1;
-    pop.appendChild(content);
-    (modalHost() || document.body).appendChild(pop);
-
-    let closed = false;
-    const place = () => {
-        if (closed) return;
-        // The CLIENT width: a page scrollbar is not room to draw in.
-        const view = { w: document.documentElement.clientWidth || window.innerWidth || 1024,
-                       h: document.documentElement.clientHeight || window.innerHeight || 768 };
-        const a = anchor?.getBoundingClientRect?.() || { left: 0, top: 0, bottom: 0, right: 0 };
-        const box = pop.getBoundingClientRect();
-        // Under the anchor, its left edge on the anchor's; an anchor near the
-        // right edge gets the popover's RIGHT edge on its own instead.
-        let left = a.left;
-        if (left + box.width > view.w - EDGE && a.right - box.width >= EDGE) left = a.right - box.width;
-        let top = a.bottom + GAP;
-        if (top + box.height > view.h - EDGE && a.top - GAP - box.height >= EDGE) top = a.top - GAP - box.height;
-        left = Math.max(EDGE, Math.min(left, view.w - box.width - EDGE));
-        top = Math.max(EDGE, Math.min(top, view.h - box.height - EDGE));
-        pop.style.left = `${Math.round(left)}px`;
-        pop.style.top = `${Math.round(top)}px`;
-    };
-
-    const onPress = (ev) => {
-        if (pop.contains(ev.target)) return;
-        if (anchor && anchor.contains?.(ev.target)) return;   // the anchor's own click toggles
-        handle.close('outside');
-    };
-    const onKey = (ev) => {
-        if (ev.key !== 'Escape') return;
-        ev.preventDefault();
-        ev.stopPropagation();
-        handle.close('escape');
-    };
-    const onResize = () => place();
-    // Placed before its content is drawn — a picker fills its list after this
-    // returns — so it is placed again whenever its size changes, or it would
-    // run past the window's edge.
-    const sized = typeof ResizeObserver === 'function' ? new ResizeObserver(() => place()) : null;
-
-    const handle = {
-        el: pop,
-        anchor,
-        toggled: false,
-        reposition: place,
-        close(reason = 'closed') {
-            if (closed) return;
-            closed = true;
-            const held = pop.contains(document.activeElement) || document.activeElement === document.body;
-            document.removeEventListener('pointerdown', onPress, true);
-            document.removeEventListener('mousedown', onPress, true);
-            pop.removeEventListener('keydown', onKey);
-            window.removeEventListener('resize', onResize);
-            sized?.disconnect();
-            pop.remove();
-            if (ACTIVE === handle) ACTIVE = null;
-            // Focus that LEFT the popover (a Tab out of it) is going somewhere the
-            // reader sent it; taking it back to the anchor would fight that move.
-            if (held && reason !== 'blur' && anchor?.isConnected) anchor.focus?.({ preventScroll: true });
+export function openPopover({ className = '', onClose = null, ...rest }) {
+    const handle = openAnchoredPopover({
+        ...rest,
+        className: `twm-flow-popover${className ? ` ${className}` : ''}`,
+        onClose(reason) {
+            OPEN.splice(OPEN.indexOf(handle), 1);
             onClose?.(reason);
         },
-    };
-    ACTIVE = handle;
-    // The press that OPENED it is still being dispatched; listen from the next turn.
-    setTimeout(() => {
-        if (closed) return;
-        document.addEventListener('pointerdown', onPress, true);
-        document.addEventListener('mousedown', onPress, true);
-    }, 0);
-    pop.addEventListener('keydown', onKey);
-    window.addEventListener('resize', onResize);
-    sized?.observe(pop);
-    place();
-    (focus || pop).focus?.({ preventScroll: true });
+    });
+    if (handle.el) OPEN.push(handle);
     return handle;
 }