flexdesk 0.17.18 → 0.18.1

package/docs/components/git.md

@@ -0,0 +1,355 @@
+# Git panel, commit graph and diff viewer
+
+> **Package:** `@flexdesk/git` · **Stylesheet:** `flexdesk/css` · [All docs](../README.md)
+
+A source-control panel, an SVG swimlane commit graph and a diff viewer. None of them runs git or reaches a backend: the panel and the graph call the methods of an **adapter** object you pass in, and the [git adapter contract](#the-git-adapter-contract-0180) below says what each method takes and answers, so that a Python, a C# or any other backend can implement it. The diff viewer needs no adapter at all.
+
+`@flexdesk/git` is a separate entry, so an application that does not show a repository does not load it. Add it to your import map beside the others:
+
+```json
+{ "imports": { "@flexdesk/git": "./vendor/flexdesk/git.js" } }
+```
+
+## The panel: `createGitPanel` (0.18.0)
+
+```js
+import { createGitPanel } from '@flexdesk/git';
+
+const panel = createGitPanel(el, {
+    adapter,                                 // the contract below; null shows emptyLabel
+    onCountChange: (n) => setBadge(n),       // how many files have changes
+});
+
+panel.setAdapter(otherRepository);           // another repository, or null
+panel.stopPolling();                         // while its tab is hidden
+panel.startPolling();                        // reads at once, then every pollInterval
+await panel.refresh();                       // read now
+panel.destroy();
+```
+
+From the top, it shows the current branch with its menu (check out, create, delete), ahead and behind counts, Fetch, Pull, Push and a More menu (stash, pop stash, merge, rebase, remotes, tags); a commit box with a Commit button and a menu (amend, commit and push, commit and sync); the changed files, each with Stage or Unstage and, unless it is in conflict, Discard; and the commit graph, collapsed until opened.
+
+| Option | Default | |
+|---|---|---|
+| `adapter` | `null` | The git adapter. `isRepo` and `status` are required: without them it throws a `TypeError` naming what is missing, here and in `setAdapter`. |
+| `onOpenDiff` | a diff window | `({ path, status, staged, renamedFrom?, ref? }) => void`, when a file row or a commit's file is opened (`ref` is the commit). Without it, the file opens in [`openGitDiffWindow`](#a-diff-in-a-window-opendiffwindow-opengitdiffwindow-0180), or nothing happens if the adapter has no `diffFile`. |
+| `onCountChange` | none | `(count) => void`, whenever the number of changed files has been read; 0 when there is nothing to read. |
+| `pollInterval` | `3000` | Milliseconds between status reads. `0` reads only on `refresh()`. A poll that finds the last read still out, or an operation running, waits for the next tick. |
+| `emptyLabel` | `'No repository'` | Shown while there is no adapter. |
+| `changesExpanded` | `true` | |
+| `graphExpanded` | `false` | The graph reads the log only once it has been opened. |
+| `showRemoteRefs` | `false` | As for [`createGitGraph`](#the-commit-graph-creategitgraph-0180). |
+
+**What is on offer is what the adapter can do.** An action whose method the adapter lacks is not drawn: with `isRepo` and `status` alone the panel is a read-only view of the branch and the changed files.
+
+**What you type is yours.** The panel's elements are built once and updated in place, so a status change never touches the commit box. Its text is cleared when a commit succeeds and when `setAdapter` changes the repository; a refused commit leaves it.
+
+**Committing.** With nothing staged, Commit stages everything first (`stage({ paths: 'all' })`). With something staged, it commits that. Amend stages nothing, and an empty message on an amend keeps the old message (`message: null`). Commit and Sync is commit, pull, push, and stops at the first refusal.
+
+**A failed operation** is an error toast carrying the backend's words, through FlexDesk's [toast helpers](notifications.md#notifications-notificationcenter), and the panel reads the repository again either way. An answer with `conflicts: true` is titled "… stopped on conflicts". A failed `isRepo` or `status` is said in the panel itself, and asked again at the next poll.
+
+**A push with no upstream** asks for one (`setUpstream: true`).
+
+**Deleting a branch** the adapter refuses with `notMerged: true` offers to force it, after asking. Any other refusal is an error toast and nothing more.
+
+**One operation at a time.** While one runs, the actions in the bar, the branch menu and the commit box's buttons are disabled; an action that still arrives (a file row's, or one waiting on a dialog) does not run, and a toast says so. A row's menu in the graph is not part of this: the graph can stand alone and has no such lock.
+
+**Another repository mid-operation.** An operation stays with the adapter it started on, through every step and dialog, whatever `setAdapter` has done since: Commit and Sync finishes on the repository it began on. Afterwards the panel reads whichever adapter it now has. A list still being read for a menu (remotes, tags, a commit's files) is dropped if the adapter changed.
+
+**Keyboard.** Ctrl+Enter or Cmd+Enter commits from the box. A file row takes focus, Enter or Space opens it, and its actions show on focus as on hover.
+
+## The commit graph: `createGitGraph` (0.18.0)
+
+```js
+import { createGitGraph } from '@flexdesk/git';
+
+const graph = createGitGraph(el, {
+    adapter,                                  // needs `log`; the rest is used when present
+    onOpenDiff: ({ path, status, ref }) => {},
+    onChanged: () => refreshTheRestOfMyPage(),
+});
+graph.setAdapter(otherRepository);
+await graph.refresh();
+graph.destroy();
+```
+
+The panel holds one of these; it also stands alone. Give `el` a height: the graph scrolls inside it and asks for the next page when the last row comes into view. Rows are 22 pixels and each draws its own SVG: lines passing through it, the commit's node, and curves to its parents.
+
+| Option | Default | |
+|---|---|---|
+| `adapter` | `null` | The git adapter. `log` is what it draws. |
+| `onOpenDiff` | a diff window | As for the panel; `ref` is always the commit's hash. |
+| `onChanged` | none | Told after a menu operation, so the rest of your page can follow. |
+| `pageSize` | `50` | Commits a page. |
+| `showRemoteRefs` | `false` | Draw remote branches' pills as well. A narrow panel leaves them out; a wide graph has the room. |
+
+`refresh()` re-reads as many commits as are loaded and redraws only if something differs, so it costs no scroll position and is safe to call on every status change. A row's context menu (right-click, Shift+F10 or the Menu key) offers what the adapter can do: Checkout, Create Branch, Copy Commit Hash, Cherry-pick, Create Tag and View Changes, which opens the file if the commit changed one and lists them if it changed several.
+
+Two pure functions are exported for your own drawing or tests:
+
+**`computeGraphLanes(commits)`** answers `{ rows, laneCount }` for commits newest first, children before parents. A row is `{ lane, hasChild, outputLanes: [{ lane, parentHash }], passLanes }`. The rows for a list are the same as the first rows for any longer list that starts with it.
+
+**`parseGitRefs(refs)`** reads a `refs` string (below) into `[{ name, type }]`, with `type` one of `'head'`, `'tag'`, `'branch'`, `'remote'`, and `name` short: `refs/remotes/origin/main` is `{ name: 'origin/main', type: 'remote' }`. The full names are what tell it from a local branch called `origin/main`. A ref of any other kind, such as `refs/stash`, is left out, and so is a short name: an adapter that forgets `--decorate=full` gets no pills.
+
+The lane colours are the tokens `--twm-git-lane-0` to `--twm-git-lane-7`; a lane past the last takes them round again.
+
+## The diff viewer: `createDiffViewer` (0.18.0)
+
+```js
+import { createDiffViewer } from '@flexdesk/git';
+
+const viewer = createDiffViewer(el, { before, after });
+
+viewer.update({
+    before: committedText,
+    after: currentText,
+    diff: rawDiffText,                                   // optional
+    fields: [{ name: 'Priority', from: 'low', to: 'high' }],   // optional; you parse them
+});
+viewer.setView('raw');         // 'fields', 'text', 'raw', or null to hand the choice back
+viewer.view();                 // what is showing
+viewer.showMessage('Loading…');
+viewer.destroy();
+```
+
+It has three views, and offers one only when its data is there. The buttons that switch between them are drawn only when there are two or more.
+
+| View | Offered when | Draws |
+|---|---|---|
+| Fields | `fields` is an array | Each `{ name, from, to }` as the name, the old value, an arrow and the new value. An absent or empty value reads as a dash. It knows nothing of where the values came from: the consumer parses them. |
+| Text | `before` or `after` is a string; or `diff` has something to read | Line by line with old and new line numbers and no diff headers. `before`/`after` are compared here; without them `diff` is read. Unchanged lines beyond the context are one row saying how many. |
+| Raw | `diff` is a string | The text as it came. |
+
+Which view shows: the one set by the `view` option, `setView` or a click, while it stays on offer; else Fields if a field changed; else Text; else Raw.
+
+| Option or data | Default | |
+|---|---|---|
+| `before`, `after`, `diff`, `fields` | | As above. `update` takes these too, and replaces all of them. |
+| `beforeStart`, `afterStart` | `1` | The line number of `before`'s and `after`'s first line, when you compare only part of a file. `update` takes these too. |
+| `context` | `3` | Unchanged lines kept around each change. `Infinity` keeps them all. |
+| `maxLines` | `1500` | Past this many differing lines a side, the texts are not compared, and it says so. Unchanged lines at the start and the end do not count, so a long file with a small edit is compared. |
+| `view` | | The view to show while it is on offer. |
+| `labels` | | Words to replace: `fields`, `text`, `raw`, `noChanges`, `noFields`, `tooLong`, and `gap: (hidden) => string`. |
+| `onViewChange` | none | `(view) => void`, when a click changes the view. |
+
+Text is always drawn as text, never as markup. Colours are the tokens `--twm-diff-add-bg`, `--twm-diff-add-fg`, `--twm-diff-del-bg` and `--twm-diff-del-fg`.
+
+### The line diff, without the viewer (0.18.0)
+
+**`computeLineDiff(before, after, { context, maxLines, beforeStart, afterStart })`** answers an array of lines, `[]` when the texts have the same lines (CRLF and LF are the same line end, and a final line end makes no line), or `null` when they are too long to compare.
+
+**`parseUnifiedDiff(text)`** reads a unified diff into the same lines. It leaves out the `diff --git`, `index`, `---` and `+++` headers, and draws a `file` line before each file only when the diff has several.
+
+**`diffStats(lines)`** answers `{ added, removed }`, for a one-glance summary such as "+2 lines". **`splitLines(text)`** and **`LINE_DIFF_LIMIT`** are exported too.
+
+A line is one of:
+
+```js
+{ kind: 'context' | 'add' | 'del', oldLine, newLine, text }     // numbers are 1-based; null on the side it is not on
+{ kind: 'gap', oldLine: null, newLine: null, text: '', hidden } // `hidden` unchanged lines left out
+{ kind: 'hunk' | 'meta' | 'file', oldLine: null, newLine: null, text }
+```
+
+## A diff in a window: `openDiffWindow`, `openGitDiffWindow` (0.18.0)
+
+```js
+import { openDiffWindow, openGitDiffWindow } from '@flexdesk/git';
+
+await openDiffWindow({
+    title: 'notes.txt',
+    load: async () => ({ before, after }),   // what `update` takes, or { ok: false, error }
+});
+
+await openGitDiffWindow({ adapter, path: 'src/a.txt', status: 'M' });
+await openGitDiffWindow({ adapter, path: 'src/a.txt', status: 'M', ref: hash });   // that commit's change
+await openGitDiffWindow({ adapter, path: 'new.txt', status: 'R', renamedFrom: 'old.txt' });
+```
+
+A modal holding a viewer, showing "Loading…" until `load` answers. A refusal or a throw is shown in the window. `openDiffWindow` also takes `icon`, `width` (880), `height` (600) and `labels`. The promise settles when the window closes.
+
+## The git adapter contract (0.18.0)
+
+An adapter is a plain object. It knows which repository it is for, so no payload names one: to show another repository, pass another adapter to `setAdapter`. Every method may answer directly or with a promise.
+
+**Every answer** is a JSON object with `ok`:
+
+```js
+{ ok: true, /* the method's own fields */ }
+{ ok: false, error: 'what the backend said' }
+{ ok: false, error: 'what git said', conflicts: true }   // merge, rebase, pull, stash pop, cherry-pick: stopped on conflicts
+{ ok: false, error: 'what git said', notMerged: true }   // deleteBranch, unforced: the branch is not fully merged
+```
+
+A method that throws or rejects is treated as `{ ok: false, error: e.message }`. Field names are exactly as written here, camelCase, for a C# or Python backend as well. A method with no payload below is called with no argument.
+
+**Required:** `isRepo` and `status`. **Everything else is optional:** leave a method out and its action is not offered.
+
+### Reading
+
+| Method | Payload | Answer, besides `ok` |
+|---|---|---|
+| `isRepo()` | | `isRepo: boolean`. `ok: false` is for when it could not ask, such as git not being installed. |
+| `status()` | | [`StatusResult`](#statusresult) |
+| `branches()` | | `branches: Branch[]` |
+| `log(payload)` | `{ count: number, skip: number }` | `commits: Commit[]`, newest first, children before parents. `[]` for a repository with no commits, not a refusal. |
+| `commitFiles(payload)` | `{ hash: string }` | `files: [{ path: string, status: FileStatus, renamedFrom?: string }]`, what that commit changed against its first parent: `git diff-tree --no-commit-id -r --root -M --name-status --diff-merges=first-parent <hash>`. A copy is `A`. |
+| `diffFile(payload)` | `{ path: string, status?: FileStatus, renamedFrom?: string, ref?: string }` | [`DiffResult`](#diffresult) |
+| `tags()` | | `tags: [{ name: string, hash: string }]` |
+| `remotes()` | | `remotes: [{ name: string, url: string }]` |
+
+#### StatusResult
+
+```js
+{
+    ok: true,
+    branch: 'main',                    // the short name; on a detached HEAD, what `git rev-parse --abbrev-ref HEAD` says
+    files: [
+        { path: 'src/a.txt', status: 'M', staged: false },
+        { path: 'new_name.txt', status: 'R', staged: true, renamedFrom: 'old_name.txt' },
+    ],
+    ahead: 2,                          // commits the upstream does not have; 0 without an upstream
+    behind: 1,                         // commits the upstream has and this does not; 0 without an upstream
+    hasUpstream: true,
+    rebasing: false,                   // optional: a rebase has stopped; offers Continue and Abort
+}
+```
+
+One entry a path, so a file with both staged and unstaged changes is one entry. `path` is relative to the repository, with forward slashes, as plain text: not the quoted form `--porcelain=v1` gives a name with a space unless it is run with `-z`. `staged` is true when the index has a change for the path, whether or not the working copy has another.
+
+`FileStatus` is one letter, the first row here that matches the two columns of `git status --porcelain=v1`:
+
+| | Meaning | Columns |
+|---|---|---|
+| `C` | Conflicted | `DD`, `AA`, or `U` in either |
+| `U` | Untracked | `??` |
+| `R` | Renamed; the entry has `renamedFrom` | `R` in either |
+| `A` | Added (a copy too) | `A` in either, or `C` in the index column |
+| `D` | Deleted | `D` in either |
+| `M` | Modified | anything else |
+
+The panel compares answers to decide whether to redraw, so answer the same fields in the same order when nothing has changed.
+
+#### Branch
+
+```js
+{
+    name: 'feature/x',        // what `checkout` takes; a remote branch as `origin/main`, without `remotes/`
+    hash: 'a1b2c3d',          // short
+    isCurrent: false,
+    isRemote: false,          // its full name starts refs/remotes/; a `/` in the name says nothing
+    upstream: 'origin/x',     // '' when it has none
+}
+```
+
+`git for-each-ref --format='%(refname)%09%(objectname:short)%09%(HEAD)%09%(upstream:short)%09%(symref)' refs/heads refs/remotes` gives all of it. Leave out a ref with a `%(symref)`: `refs/remotes/origin/HEAD` is only another name for a branch that is listed anyway, and `git branch -a` calls it `origin`, which reads as a local branch.
+
+#### Commit
+
+```js
+{
+    hash: 'a1b2c3d4e5f6…',           // full. git log --format: %H
+    shortHash: 'a1b2c3d',            // %h
+    author: 'A Person',              // %an
+    email: 'a.person@example.org',   // %ae
+    timestamp: 1700000000,           // seconds since the epoch, %at
+    subject: 'Name the steps',       // %s
+    refs: 'HEAD -> refs/heads/main, tag: refs/tags/v1, refs/remotes/origin/main',   // %D with --decorate=full, one string; '' when none
+    parentHashes: ['b2c3d4e5f6a7…'], // full, %P split on spaces; [] for a root commit
+}
+```
+
+`log` must list all branches in `--topo-order` for the lanes to be right, and full ref names for the pills to be right: `git log --all --topo-order --decorate=full -n<count> --skip=<skip>`. Without `--decorate=full`, `%D` writes `origin/main` and a local `feature/x` the same way, and nothing can tell them apart.
+
+#### DiffResult
+
+```js
+{ ok: true, before: 'old text', after: 'new text', diff: '@@ -1 +1 @@\n…', language: 'python' }
+```
+
+Answer `before` and `after`, or `diff`, or all three; a missing side of a new or deleted file is `''`. Without `ref`, the comparison is the last commit against the working copy, that is everything not yet committed, staged or not. With `ref`, it is that commit's first parent against that commit, and the working copy plays no part. With `renamedFrom`, the old side is read at that path, `path` being the new one.
+
+| Asked for | `diff` | `before` / `after` |
+|---|---|---|
+| No `ref` | `git diff HEAD -- <path>` | `git show HEAD:<path>` / the file on disk |
+| No `ref`, `U` | none: git has nothing to compare | `''` / the file on disk |
+| No `ref`, `R` | `git diff HEAD -M -- <renamedFrom> <path>` | `git show HEAD:<renamedFrom>` / the file on disk |
+| No `ref`, `C` | as for `M`: the file on disk holds the conflict markers | as for `M` |
+| `ref` | `git diff -M <ref>^ <ref> -- [<renamedFrom>] <path>`; for a root commit, `git show --format= <ref> -- <path>` | `git show <ref>^:<renamedFrom or path>` / `git show <ref>:<path>` |
+
+`language` is optional and FlexDesk does not read it: it is there for an `onOpenDiff` of yours that opens a code editor's diff view.
+
+### Changing the working copy
+
+Each answers `{ ok: true }` unless it says otherwise.
+
+| Method | Payload | What it does |
+|---|---|---|
+| `init()` | | `git init` |
+| `stage(payload)` | `{ paths: string[] \| 'all' }` | `git add -- <paths>`; `'all'` is `git add -A` |
+| `unstage(payload)` | `{ paths: string[] }` | `git reset HEAD -- <paths>`. A rename comes as both its paths. |
+| `discard(payload)` | `{ path: string, status: FileStatus, renamedFrom?: string }` | Takes the path back to the last commit, in the index and on disk alike, by `status` as below. The panel asks first. |
+| `commit(payload)` | `{ message: string \| null, amend: boolean }` | `git commit -m <message>`, with `--amend` when asked. `message: null` comes only with `amend: true` and keeps the last message (`--no-edit`). Answers `hash: string`, the new commit. The panel stages before calling; this does not. |
+| `stash(payload)` | `{ message?: string }` | `git stash push`, with `-m` when given |
+| `stashPop()` | | `git stash pop`. May answer `conflicts`. |
+
+`discard` by status. The panel never sends `C`: a conflict is resolved or the merge aborted.
+
+| `status` | Command | |
+|---|---|---|
+| `M`, `D` | `git restore --source=HEAD --staged --worktree -- <path>` | `git checkout -- <path>` is not enough: it restores from the index, so a staged change survives. |
+| `R` | `git restore --source=HEAD --staged --worktree -- <renamedFrom> <path>` | Puts the old name back and removes the new one. |
+| `A` | `git rm -f -- <path>` | There is no last commit to go back to: the file goes. The panel's dialog says so. Works before the first commit too, when `git restore --source=HEAD` cannot. |
+| `U` | Remove the file from disk | The panel's dialog says so. |
+
+### Branches and history
+
+| Method | Payload | What it does |
+|---|---|---|
+| `checkout(payload)` | `{ ref: string }` | `git checkout <ref>`: a branch, a remote branch or a commit's full hash |
+| `createBranch(payload)` | `{ name: string, from?: string }` | `git checkout -b <name> [<from>]`: makes it and switches to it |
+| `deleteBranch(payload)` | `{ name: string, force: boolean }` | `git branch -d <name>`, or `-D` when forced. Answers `notMerged: true` with `ok: false` only when `-d` refused because the branch is not fully merged (git's message, in the C locale, has `not fully merged`), and only then does the panel offer to force it. |
+| `merge(payload)` | `{ branch: string }` | `git merge <branch>`. May answer `conflicts`. |
+| `rebase(payload)` | `{ onto: string }` or `{ continue: true }` or `{ abort: true }` | `git rebase <onto>`, `--continue` or `--abort`. May answer `conflicts`. |
+| `cherryPick(payload)` | `{ hash: string }` | `git cherry-pick <hash>`. May answer `conflicts`. |
+| `createTag(payload)` | `{ name: string, hash?: string }` | `git tag <name> [<hash>]`, on HEAD without one |
+| `deleteTag(payload)` | `{ name: string }` | `git tag -d <name>` |
+
+### Remotes
+
+| Method | Payload | What it does |
+|---|---|---|
+| `fetch()` | | `git fetch --all` |
+| `pull()` | | `git pull`. May answer `conflicts`. |
+| `push(payload)` | `{ setUpstream: boolean }` | `git push`; with `setUpstream`, `git push -u <remote> <current branch>` |
+| `addRemote(payload)` | `{ name: string, url: string }` | `git remote add` |
+| `removeRemote(payload)` | `{ name: string }` | `git remote remove` |
+
+### Writing an adapter
+
+Over a pywebview bridge whose methods take the repository in the payload:
+
+```js
+const adapter = {
+    isRepo:  () => api.git_is_repo({ repoPath }),
+    status:  () => api.git_status({ repoPath }),
+    log:     (p) => api.git_log({ repoPath, ...p }),
+    stage:   (p) => api.git_stage({ repoPath, ...p }),
+    discard: ({ path, status, renamedFrom }) => api.git_discard({ repoPath, path, status, renamedFrom }),
+    // …
+};
+```
+
+Over HTTP, with the answers already in this shape:
+
+```js
+const call = (name) => (payload) => fetch(`/api/git/${name}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(payload ?? {}),
+}).then((r) => r.json());
+
+const adapter = Object.fromEntries(['isRepo', 'status', 'branches', 'log', 'stage', 'unstage', 'commit', 'push']
+    .map((name) => [name, call(name)]));
+```
+
+`demo/git.js` is a complete adapter over a repository in memory, and `demo/git.html` shows it.

package/docs/components/input-fields.md

@@ -1,8 +1,8 @@
-# Input fields: slider and tags
+# Input fields: slider, tags, select and combobox
 
 > **Package:** `@flexdesk/widgets` · **More fields:** the toggle and colour fields are in [Forms and dialogs](forms-and-dialogs.md) · [All docs](../README.md)
 
-Two stand-alone inputs. `SliderField` draws a range input, with an optional number box, readout, default and enable toggle. `createTagInput` draws a list of short strings as removable chips followed by a text box.
+Stand-alone inputs. `SliderField` draws a range input, with an optional number box, readout, default and enable toggle. `createTagInput` draws a list of short strings as removable chips followed by a text box. `createSelect` is a select drawn in the DOM, and `createCombobox` a text box that also offers a list.
 
 ## SliderField: a number box, a readout, a default and an enable toggle (0.17.0)
 
@@ -70,3 +70,192 @@ tags.dispose();
 The handle is `{ element, input, getValue, setValue, focus, dispose }`
 (`input` is `null` when read-only). The styles are the `twm-tag-input` block in
 `flexdesk.css`. `tests/tag_input.test.mjs` covers each of the above in jsdom.
+
+## Suggestions and one spelling for tags: `suggestions`, `normalise` (0.18.0)
+
+`createTagInput` takes two more options. Neither changes a tag input that does
+not pass them.
+
+```js
+createTagInput(host, {
+    value: ['baseline'],
+    suggestions: ['baseline', 'stress', 'path-finding'],     // or async (query, { signal }) => [...]
+    normalise: (s) => s.toLowerCase().replace(/\s+/g, '-'),
+    onChange: save,
+});
+```
+
+- **`suggestions`** offers known tags under the text box: strings, or
+  `{ value, label?, description?, icon?, hint? }`. Focus shows them and typing
+  narrows them. Whatever their source, a row is in the one spelling, says a tag once and is not
+  a tag already in the list. An array is filtered here with the earliest match first and then
+  alphabetically. A function is asked with what is in the box, keeps its own order and may
+  return a promise, as in [`createCombobox`](#a-text-box-that-also-offers-a-list-createcombobox-0180).
+- The arrow keys walk the rows, and **Enter** or a **comma** takes the active one. With no row
+  active, which is how it starts, both still commit what was typed, and so does a blur:
+  a list of known tags never stops you adding a new one.
+- **`normalise(text)`** is the one spelling of a tag, handed the trimmed text and applied to the
+  value it opens with, to what is typed, to the suggestions and to `setValue`. With it
+  `Path Finding` and `path-finding` cannot both exist.
+
+Since 0.18.0 the list a tag input opens with, and `setValue`'s, drop a repeat
+unless `allowDuplicates` is set, as typing always did.
+
+## A select drawn in the DOM: `createSelect` (0.18.0)
+
+A native `<select>` styles down to its closed box: the list belongs to the
+operating system. `createSelect` draws the list itself, so a row can have a glyph,
+a second line, a hint and a reason, under group headings, with a search box and a
+way to type a value nobody listed. `selectBox`, the native one, stays for a list with
+nothing to say in a tight strip.
+
+```js
+import { createSelect } from '@flexdesk/widgets';
+
+const phase = createSelect({
+    value: 'review',
+    allowNew: true,
+    options: [
+        { value: 'draft', label: 'Draft', icon: 'edit', description: 'Not ready for anyone', hint: 'D' },
+        { group: 'In progress', options: [
+            { value: 'review', label: 'Review', icon: 'rate_review' },
+            { value: 'held', label: 'Held', disabled: true, reason: 'needs an owner' },
+        ] },
+    ],
+    onChange: (value, option) => save(value),
+});
+toolbar.appendChild(phase.el);
+```
+
+| Option | What it does |
+| --- | --- |
+| `options` | Bare values, `{ value, label?, icon?, description?, hint?, keywords?, disabled?, reason? }`, or `{ group, options }`. `keywords` is searched and never drawn. A function is read each time the list opens and the trigger is painted, for a list that grows while the page lives |
+| `value`, `onChange(value, option)` | `onChange` hears the reader choosing a different value, with the entry as you gave it (`null` for a new value). A value keeps its type: an option whose value is 4 gives 4 |
+| `search` | The search box. By default it is there with `allowNew` or more than seven options; `true`, `false` or `{ placeholder }` decides. It narrows on the label, the value, the description and `keywords`, is emptied on every open, and takes focus |
+| `allowNew`, `newLabel(typed)` | A typed text no option has as its value or label is offered as a last row, "Use “…”" by default, and is the value when chosen |
+| `placeholder` | Shown while nothing is chosen: `null`, `undefined` or `''`, with no option of its own. `setPlaceholder(text)` changes it, for a list that is being fetched |
+| `notFound(value)` | How a value in no option reads on the trigger; as itself by default |
+| `loose` | A stored `'2'` names option `2` |
+| `showIcon` | Draw the chosen option's glyph on the trigger too. On by default |
+| `name` | A hidden input of this name carries the value as text, for a surrounding form, and fires a bubbling `change` when the reader chooses. `el` is then a wrapper round the trigger and the input |
+| `carrier` | That hidden input, yours, instead of `name`: a form template's field that something finds by `[data-f]` or an id. Its attributes are left as they are |
+| `className`, `panelClassName`, `title`, `ariaLabel`, `disabled`, `align` | Extra classes on the trigger and on the list's panel, its tooltip and name, whether it is disabled, and which trigger edge the list lines up with |
+| `emptyText(typed)` | What a list with no rows says |
+
+The handle is `{ el, input, value, isOpen, setOptions(options, value?), setPlaceholder(text), setDisabled(on), open(), close(), focus(), destroy() }`.
+`value` reads and writes, and writing does not call `onChange`; so does `setOptions`, which
+leaves the value alone unless you pass one.
+
+**The value is never silently changed.** A value in none of the options, or naming a
+disabled one, stays the value and is shown. A list that arrives late or has moved on
+does not turn it into something else on the next save.
+
+**Keys.** ArrowDown, ArrowUp, Enter or Space open the list; the arrows walk the rows
+that may be chosen and wrap; Enter takes the active row (Space too, with no search box).
+With no search box Home and End go to the ends and a printable key walks to the
+label it begins. Tab closes the list and goes on from the trigger. Escape closes
+the list and nothing else, so the dialog around it stays open. Focus stays on the
+trigger, or in the search box, and `aria-activedescendant` names the active row.
+
+The list is on an [anchored layer](menus.md#an-anchored-layer-positionanchored-openanchoredlayer-0180):
+it is on the page only while open, and `destroy()` takes everything away. The classes are `.twm-select`
+(`--empty`, `.twm-is-open`), `.twm-option-panel` and `.twm-option-list__row` (`--active`;
+`aria-selected` marks the current value). No state is held in a `data-*` attribute.
+
+## A text box that also offers a list: `createCombobox` (0.18.0)
+
+The text in the box is the value; the list only suggests. For a value that may be
+anything but usually is one of a few known ones: a code, a unit, a name. A field
+whose value is an opaque id with a separate name is `createSelect`'s.
+
+```js
+import { createCombobox } from '@flexdesk/widgets';
+
+const code = createCombobox({
+    value: 'gbp',
+    options: [
+        { value: 'GBP', label: 'GBP · £', description: 'Pound sterling' },
+        { value: 'CAD', label: 'CAD · $', description: 'Canadian dollar', keywords: 'loonie' },
+    ],
+    normalise: (text) => text.toUpperCase(),
+    isCandidate: (text) => /^[A-Z]{3}$/.test(text),
+    validate: (value) => (/^[A-Z]{3}$/.test(value) ? null : 'Three letters.'),
+    onChange: (value, option) => { model.code = value; },
+});
+form.appendChild(code.el);
+```
+
+- **The box holds the value.** `label` is what the list shows; choosing a row puts its
+  `value` in the box.
+- **`onChange(value, option)`** fires on every keystroke and pick (`option` is the
+  entry you gave when one was picked, else `null`), so "type a value, click Save"
+  cannot save the previous one.
+- **`normalise(text)`** applies to what is reported every time, and rewrites the box
+  only when the text is settled (a pick, Enter, Tab or blur), because rewriting
+  an input moves the caret. A handed value it changes is reported once at
+  construction, so your model does not keep what the box no longer shows.
+- **`autoHighlight`** (on by default) makes the first surviving row active as you
+  type, so Enter completes it; the row whose value IS the typed text wins. Since the
+  list also searches labels, descriptions and `keywords`, a complete code typed in full
+  can sit inside another row's words: **`isCandidate(text)`** says the text is already a
+  well-formed value, so that nothing is made active and Enter keeps it.
+- **`validate(value)`** warns under the box once the text is settled, and `error` reads it.
+  It does not refuse: the value is still reported.
+- **Enter and Escape** are swallowed while the list is open, and only then: they close
+  the list and not the dialog around it.
+
+**Options found as the reader types.** `options` may be a function:
+
+```js
+createCombobox({
+    options: async (query, { signal }) => {
+        const res = await fetch(`/people?q=${encodeURIComponent(query)}`, { signal });
+        return res.json();                // [{ value, label, description? }]
+    },
+    debounce: 200,                        // ms before it is asked; 150 by default
+});
+```
+
+It does its own filtering and is asked with `''` when the list opens without typing. An
+answer that is no longer the latest is dropped, and `signal` aborts when a newer
+one is asked for. While the first answer is coming the list says `loadingText`; rows
+already drawn stay until the next answer; no rows closes the list; a rejection is logged
+and the list says `errorText`. An answer after Escape does not reopen it.
+
+The handle is `{ el, input, value, error, isOpen, setOptions(options), open(text?), close(), focus(), destroy() }`.
+It also takes `name`, `placeholder`, `title`, `ariaLabel`, `disabled`, `className` and `panelClassName`. A pick
+fires a bubbling `change` on the input, for a form around it.
+
+**`attachInputOptions(input, options)`** is the list on its own, under a text box of yours.
+`createCombobox` and the tag input's suggestions are this. It takes `options`,
+`onPick(option)` (the entry you gave is `option.source`), `anchor`, `isCurrent`, `autoHighlight`,
+`isCandidate`, `normalise`, `openOnFocus`, `passEnter`, `loadingText`, `errorText`, `debounce`,
+`panelClassName` and `onSettle`, and answers `{ isOpen, open, close, takeActive, setOptions, destroy }`.
+`takeActive()` chooses the active row and says whether there was one, for a key of your own that
+also means "this one", such as the tag input's comma.
+
+`tests/select_combobox_popover.test.mjs` covers these and the tag input's options in jsdom.
+
+## A list under a name being edited: `attachInlineRenamer` (0.18.1)
+
+`attachInlineRenamer`'s `onStart` now runs before the renamer adds its own key listeners, and is handed the input as `{ value, triggerEvent, input }`. So what it attaches hears each key first, which is what [`attachInputOptions`](#a-text-box-that-also-offers-a-list-createcombobox-0180) asks for:
+
+```js
+const renamer = attachInlineRenamer({
+    label,
+    onStart: ({ input }) => {
+        list = attachInputOptions(input, {
+            options: names,
+            onPick: (option) => {
+                input.value = option.value;
+                renamer.commit('pick');
+            },
+        });
+    },
+    onCommit: (name) => save(name),
+    onFinish: () => list.destroy(),
+    onCancel: () => list.destroy(),
+});
+```
+
+Enter on an arrow-highlighted row commits the row; with no row highlighted it commits what was typed. Esc with the list open closes only the list, and the next one cancels. Taking the field off the page ends the edit first, so the blur a browser fires for it commits nothing after a commit or an Esc.

package/docs/components/keymap.md

@@ -4,6 +4,14 @@
 
 The window manager binds a set of keyboard chords: F1 to F12, Backspace, Ctrl+K, Ctrl+Tab, Ctrl/Shift+Arrows, the Alt chords, `?` and Esc. `keymap.bindings` takes any of them back or rebinds it. The same page covers what depends on those keys and on how a user moves around: what Back and the breadcrumb do, the content zoom control (`chrome.zoom`), and the shell options `backToOpenList`, `floatActiveTab` and `tabLayout`.
 
+## F1..F12 and a page rail (0.18.0)
+
+F1..F12 press the Nth page button. With no `navSelector` they now find the
+buttons of a [page rail](shell.md#the-pages-as-a-vertical-rail-chromerail-0180)
+(`chrome.rail`, `mountPageRail`) as well as those of `chrome.topNav`, so a rail
+needs no selector of yours. Pass `navSelector` only for page buttons in markup of
+your own; it still replaces the default.
+
 ## The digit chords follow the key's position, not its character (0.17.14)
 
 Alt+1..9 switch to desktop N and Alt+Shift+1..9 move the focused tile to desktop