flexdesk 0.17.17 → 0.18.0

package/docs/README.md

@@ -8,7 +8,7 @@ New here? Start with the [quickstart](quickstart.md). The [README](../README.md)
 
 ## Packages
 
-FlexDesk is nine entry points that share their code, so you load only what you use. [Packages and entry points](concepts/packages-and-entry-points.md) has the sizes and the reasoning.
+FlexDesk is ten entry points that share their code, so you load only what you use. [Packages and entry points](concepts/packages-and-entry-points.md) has the sizes and the reasoning.
 
 | Entry | What is in it | Read |
 |---|---|---|
@@ -21,6 +21,7 @@ FlexDesk is nine entry points that share their code, so you load only what you u
 | `@flexdesk/editor` | Monaco loader, editor factory, tab bar, search, split panes | [Editor](components/editor.md) |
 | `@flexdesk/canvas` | The canvas kernel: a pannable, zoomable surface, the edge router, a graph layer | [Flow canvas editor](components/flow-canvas-editor.md) |
 | `@flexdesk/flow` | The flow-editor kit and the canvas, outline and lane editors | [Flow editors and the flow kit](components/flow-editors.md) |
+| `@flexdesk/git` | A source-control panel, a commit graph and a diff viewer, over a written adapter contract | [Git panel, commit graph and diff viewer](components/git.md) |
 
 ## Components
 
@@ -48,8 +49,10 @@ FlexDesk is nine entry points that share their code, so you load only what you u
 - [Forms and dialogs](components/forms-and-dialogs.md): `openForm`, `openConfirm`, and every field type.
 - [Settings page](components/settings-view.md): a settings store's schema drawn as a page.
 - [Wizard](components/wizard.md): a multi-step flow, inline or in a window.
-- [Input fields: slider and tags](components/input-fields.md): `SliderField` and `createTagInput`.
-- [Menus](components/menus.md): `createMenuBar`, `ActionDropdown` and `CategoryPicker`.
+- [Input fields: slider, tags, select and combobox](components/input-fields.md): `SliderField`, `createTagInput`, `createSelect` and `createCombobox`.
+- [Filter builder](components/filter-builder.md): recursive AND/OR/NOT filters: the model, a mountable builder, a dialog, and the condition tree a server compiles.
+- [Menus](components/menus.md): `createMenuBar`, `ActionDropdown`, `CategoryPicker`, `openPopover` and `positionAnchored`.
+- [Workspace picker](components/workspace-picker.md): the top-bar field, its switcher and the recent-items store.
 
 ### Layout, content and feedback
 
@@ -59,6 +62,7 @@ FlexDesk is nine entry points that share their code, so you load only what you u
 - [Slide-out panel](components/slide-out-panel.md): `SlideOutPanel`, an inline panel that slides in over its host.
 - [Markdown and document outline](components/markdown-and-outline.md): `renderMarkdown` and `createDocumentOutline`.
 - [Conversation view](components/conversation.md): a transcript above a composer.
+- [Assistant chat shell](components/chat-shell.md): `mountChatShell`, tabs, a model picker and streaming replies over a thin transport.
 - [Notifications and progress](components/notifications.md): toasts, history, the alert log, progress bars, lists and phases.
 
 ### Charts, editor and dashboards
@@ -66,6 +70,7 @@ FlexDesk is nine entry points that share their code, so you load only what you u
 - [Charts](components/charts.md): `@flexdesk/charts`, on Plotly.
 - [Editor](components/editor.md): `@flexdesk/editor`, on Monaco.
 - [Dashboard tiles](components/tiles.md): `@flexdesk/tiles`, a draggable widget grid.
+- [Git panel, commit graph and diff viewer](components/git.md): `@flexdesk/git`, over a written adapter contract that any backend can implement.
 
 ### Flow editors
 
@@ -82,7 +87,7 @@ These have no page of their own: `ManagedWindow`, modals, `TreeView`, context me
 
 ## Concepts
 
-- [Packages and entry points](concepts/packages-and-entry-points.md): the nine entries, what they weigh, and why they are separate.
+- [Packages and entry points](concepts/packages-and-entry-points.md): the ten entries, what they weigh, and why they are separate.
 - [Host port](concepts/host-port.md): how FlexDesk reaches storage, dialogs and native windows without touching them.
 - [Domain neutrality](concepts/domain-neutrality.md): storage keys, theme names and MIME types are yours; no application globals.
 - [State guard](concepts/state-guard.md): who wrote that `data-*` attribute.

package/docs/best-practices.md

@@ -8,7 +8,7 @@ The rules the reference pages state, gathered in one place. Each item says what
 
 **2. Start with the smallest host.** Pass `createHost` only the capabilities you have. A capability you leave out is absent and the library degrades instead of throwing: no native window buttons without `window`, a Blob download for CSV without `dialogs`. An in-memory `Map` is a perfectly good `state`, and `NULL_HOST` is a valid host with nothing behind it. See [the host port](concepts/host-port.md#the-host-port).
 
-**3. Load every entry from one copy.** The entries share code through chunks, so importing several does not give you several event buses or several copies of a module-level singleton. Keep it that way: map all entries to the same install or the same import map, rather than mixing a vendored `dist/` with a second bundled copy. See [packages and entry points](concepts/packages-and-entry-points.md#nine-entry-points).
+**3. Load every entry from one copy.** The entries share code through chunks, so importing several does not give you several event buses or several copies of a module-level singleton. Keep it that way: map all entries to the same install or the same import map, rather than mixing a vendored `dist/` with a second bundled copy. See [packages and entry points](concepts/packages-and-entry-points.md#ten-entry-points).
 
 **4. Name your storage before anything reads it.** Every key FlexDesk writes is an option, with a generic default. Set them at boot, before the first read. Tile layouts are the sharp edge: the store is a singleton, and one built before you supply your key uses the default, so every layout your users saved becomes silently invisible, with no error. If users already have data under older keys, pass those keys explicitly and nothing is lost. See [storage keys and names](concepts/domain-neutrality.md#storage-keys-and-names-are-yours-0170) and [layouts are keyed by whatever you key them by](components/tiles.md#layouts-are-keyed-by-whatever-you-key-them-by).
 
@@ -36,7 +36,7 @@ The rules the reference pages state, gathered in one place. Each item says what
 
 **14. Restyle through the tokens.** Every rule reads its values from `tokens.css`, so swapping that one file restyles the shell. Library classes are `twm-` prefixed, and that prefix is stable; the editor components and the help modal keep the class names they were extracted with. Supply the icon font, or accept that icons show their text names. See [theming and CSS](concepts/styling.md#styling).
 
-**15. Run the state guard strictly in your own code.** `StateGuardService` defaults to `mode: 'warn'`. FlexDesk's own widgets run clean under `'strict'`, so choose strict for your code and add your application's keys on top of `DEFAULT_STATE_GUARD_CONFIG`: a key you write that no FlexDesk widget does is yours to list. The defaults also still allow some keys that no widget writes, which a strict guard lets through unless you filter them out ([what 0.18.0 removed and what stayed](concepts/state-guard.md#thirteen-application-keys-leave-the-defaults-0180)). See [state guard](concepts/state-guard.md#the-state-guard-who-wrote-that-attribute-0170) and [the default allow-list](concepts/state-guard.md#the-defaults-cover-flexdesks-own-keys-0170).
+**15. Run the state guard strictly in your own code.** `StateGuardService` defaults to `mode: 'warn'`. FlexDesk's own widgets run clean under `'strict'`, so choose strict for your code and add your application's keys on top of `DEFAULT_STATE_GUARD_CONFIG`: a key you write that no FlexDesk widget does is yours to list. The defaults also still allow some keys that no widget writes, which a strict guard lets through unless you filter them out ([what 0.17.14 removed and what stayed](concepts/state-guard.md#thirteen-application-keys-leave-the-defaults-01714)). See [state guard](concepts/state-guard.md#the-state-guard-who-wrote-that-attribute-0170) and [the default allow-list](concepts/state-guard.md#the-defaults-cover-flexdesks-own-keys-0170).
 
 **16. Dispose what you create.** `shell.dispose()` removes the `?` shortcut and the desktop bar along with the rest of the shell. A `NotificationCenter`'s `dispose()` hands the toast helpers back. Menu bars, tables and lists have `dispose()` too.
 

package/docs/components/chat-shell.md

@@ -0,0 +1,198 @@
+# Assistant chat shell
+
+> **Package:** `@flexdesk/widgets` · [All docs](../README.md)
+
+A whole assistant chat over the [conversation view](conversation.md): conversation tabs, an optional mode toggle, a model picker, a reply that streams, Markdown bodies, time and copy on every message, and a slot for your own controls. It knows no provider and nothing of what a reply is about.
+
+## An assistant chat: `mountChatShell` (0.18.0)
+
+```js
+import { mountChatShell } from '@flexdesk/widgets';
+
+const chat = mountChatShell(el, {
+    transport: {
+        send(request, emit) { backend.ask(request, (e) => emit(toChatEvent(e))); },
+        cancel(request)     { backend.stop(); },
+    },
+    modes: [{ id: 'ask', label: 'Ask' }, { id: 'act', label: 'Act' }],
+    models: { items: [{ id: 'large', label: 'Large' }, { id: 'small', label: 'Small' }], activeId: 'large' },
+    onModelSelect: (item) => chat.setModels({ activeId: item.id }),
+    renderControls: (el, message) => drawMyControls(el, message.meta),
+    conversations: JSON.parse(localStorage.getItem('chat') ?? 'null'),
+    onChange: (snapshot) => localStorage.setItem('chat', JSON.stringify(snapshot)),
+    placeholder: 'Ask anything',
+    welcome: { icon: 'smart_toy', text: 'What can I help you with?' },
+});
+```
+
+The chat fills its host. It needs `flexdesk.css`, and the Material Symbols font for its icons.
+
+| Option | Is |
+|---|---|
+| `transport` | **Required.** `{ send(request, emit), cancel?(request) }`; `cancel` may answer a promise, see [below](#a-backend-with-no-run-id) |
+| `renderControls(el, message, chat)` | Fills the slot on an assistant message |
+| `markdown` | Options for [`renderMarkdown`](markdown-and-outline.md) (`highlight`, `math`, `inlineRules`, ...) |
+| `onChange(snapshot)` | Something worth keeping changed: a message arrived or finished, a conversation or its meta changed. Not called per text delta |
+| `onConversationChange(conversation, reason)` | Another conversation is in front; `reason` is `new`, `switch`, `close` or `reset`. `conversation` is `{ id, title, conversationId, messages }` |
+| `modes`, `mode`, `onModeChange(id)` | `[{ id, label, title? }]`. The labels are yours. No modes, no toggle |
+| `models`, `onModelSelect(item)`, `onModelAction(action, item)` | See [The model picker](#the-model-picker) |
+| `conversations` | A `snapshot()` to restore |
+| `titleFrom(text)` | A new conversation's title, from its first message. Default: the first 30 characters |
+| `formatTime(at, message)` | A message's time; `''` shows none. Default: the locale's hours and minutes |
+| `placeholder`, `welcome: { icon?, text }` | The composer's placeholder; what an empty transcript shows |
+| `labels` | Over `CHAT_SHELL_LABELS`, every text the chat shows |
+| `eventBus`, `logger` | `eventBus` gets `CHAT_BUS_EVENTS` |
+
+### The transport
+
+`send(request, emit)` starts a turn. A request is `{ text, tabId, conversationId, mode, model }`: `tabId` is the conversation's tab, `conversationId` is your backend's id (`null` until you give one), `model` is the picker's `activeId`.
+
+`emit` takes normalised events, one at a time (`CHAT_TRANSPORT_EVENTS`):
+
+| Event | Does |
+|---|---|
+| `{ type: 'text-delta', text }` | Adds to the reply, which re-renders |
+| `{ type: 'tool-use', id?, name, label?, status? }` | Lists a tool call under the reply, or updates the one with that `id`. `status` is `running` (the default), `done` or `error`; `label` is shown instead of `name` |
+| `{ type: 'message-end', text?, conversationId?, meta? }` | Ends the turn. `text` fills the reply only if nothing was streamed; `conversationId` is kept; `meta` is merged into the message's |
+| `{ type: 'error', message }` | Ends the turn with an error message in the transcript |
+
+Every `emit` belongs to its turn, and what it is handed after that turn ended or was cancelled is dropped. A `send` that throws, or answers a promise that rejects, is an `error` event. To tell the chat a backend id before the turn ends, call `setConversationId(request.tabId, id)`.
+
+So a transport that gives each run its own callback, and calls that run's `emit`, needs no filtering of its own.
+
+#### A backend with no run id
+
+A backend that pushes to a global has one place to send a frame, and the frame does not say which run it is from. The adapter holds the latest `emit`, so the chat cannot tell an old run's chunk from the new reply's. Runs must therefore not overlap, and `cancel` is how: it answers a promise that settles when the cancelled run is over and the backend takes a new request. The next turn shows at once, with its typing dots, and its `send` is called when the promise settles. A promise that rejects is logged and counts as settled; one that never settles leaves the next turn waiting until the user stops it.
+
+```js
+let emit = null;
+let runEnded = null;
+const ended = () => { runEnded?.(); runEnded = null; };
+window.myBridge = {
+    onChunk: ({ chunk }) => emit?.({ type: 'text-delta', text: chunk }),
+    onDone: ({ text, id, changes }) => {
+        emit?.({ type: 'message-end', text, conversationId: id, meta: { changes } });
+        ended();
+    },
+    onError: ({ error }) => {
+        emit?.({ type: 'error', message: error });
+        ended();
+    },
+};
+const transport = {
+    async send(request, e) {
+        emit = e;
+        try {
+            const result = await api.ask(request);
+            if (!result.ok) throw new Error(result.error);
+        } catch (error) {
+            ended();
+            throw error;
+        }
+    },
+    cancel: () => new Promise((resolve) => {
+        runEnded = resolve;
+        api.stop();
+    }),
+};
+```
+
+While the run winds down, `emit` is still the cancelled turn's, so its late chunks and its report that it was cancelled are dropped, with no check of yours. The promise must not settle before the backend would accept a request: if the backend sends its last frame and only then frees itself, have it send the end of the run after that, and settle on that instead. A `cancel` that answers no promise says there is nothing to wait for, and `send` is called at once.
+
+### A turn
+
+The user's message goes in, then a streamed assistant message that shows the typing dots while it is empty. While the turn runs, Send is Cancel and Esc cancels, as in the conversation view, and the New and Clear buttons are disabled. A turn ends in one of three ways:
+
+- **`message-end`.** Running tools become `done`. The message gets its controls, its time and its copy button.
+- **Stop.** Cancel, Esc or `chat.cancel()`. What arrived stays, running tools become `stopped`, and `transport.cancel(request)` is called once, unless the turn's `send` was still [waiting](#a-backend-with-no-run-id) and so never called. The chat can send again at once.
+- **`error`.** As Stop without `transport.cancel`, and an error message follows. While it is the last message it carries *Retry*, which sends the user message before it again.
+
+In all three, a reply left with no text, no tool call and no `meta` is taken out. `chat.isBusy()` answers at once.
+
+### Conversations
+
+The chat owns the tabs: one per conversation, with a close mark while there is more than one, double-click or F2 to rename, a New button and a Clear button (which asks first when there is something to clear). A new conversation takes its title from its first message unless you renamed it. While a turn runs, the conversation in front cannot be left, closed or cleared; a switch is refused and the strip stays where it was.
+
+`chat.snapshot()` is plain data to keep, and `conversations` takes it back:
+
+```js
+{ activeId, tabs: [{ id, title, conversationId, messages: [{ id, role, text, at?, tools?, meta? }] }] }
+```
+
+A reply still empty is not in a snapshot, and a tool that was `running` when a snapshot was taken comes back `stopped`.
+
+| Method | Does |
+|---|---|
+| `send(text)`, `cancel()` → bool | As the user would; false when refused |
+| `isBusy()`, `messages()`, `snapshot()` | A turn is running; the messages in front; everything to keep |
+| `activeConversation()`, `newConversation()` → id, `switchTo(id)`, `close(id)`, `rename(id, title)`, `reset()` | The tabs. `reset` empties the one in front. Refused ones answer false (`newConversation`: null) |
+| `setConversationId(tabId, id)` | Your backend's id for a conversation |
+| `setMessages(tabId, messages)` | Replaces a conversation's messages, when your backend knows better. The one a turn is writing to refuses |
+| `updateMeta(id, patch)`, `refreshControls(id)`, `controlsSlot(id)` | A message's controls, below |
+| `mode()`, `setMode(id)`, `setModels(patch)` | The bar |
+| `getText()`, `setText(text)`, `focus()`, `destroy()` | The composer, and teardown. `destroy` cancels a running turn |
+| `root`, `stateMachine` | The element, and the machine below |
+
+### Your controls on a message
+
+Each assistant message has a slot between its tool calls and its footer. `renderControls(el, message, chat)` fills an emptied `el` when the reply has finished, and again when the message comes back on a tab switch or a restore, after `updateMeta(id, patch)`, and on `refreshControls(id)`. It is not called while a reply streams. Whatever it needs to survive goes in `message.meta`, which is kept in snapshots and handed back untouched:
+
+```js
+renderControls(el, message, chat) {
+    if (!message.meta?.changes) return;
+    const button = document.createElement('button');
+    button.textContent = message.meta.undone ? 'Redo' : 'Undo';
+    button.onclick = () => chat.updateMeta(message.id, { undone: !message.meta.undone });
+    el.append(button);
+}
+```
+
+A `renderControls` that throws is logged and the chat carries on.
+
+### The model picker
+
+An [`ActionDropdown`](menus.md) on a button in the bar. It is controlled: choosing an entry calls your callback, and the picker changes when you call `setModels`. `setModels` takes any of these; what you leave out stays.
+
+| Key | Is |
+|---|---|
+| `items` | Entries: `{ id, label, description?, icon? }` (a model), `{ action, label, description?, icon? }` (a command), `{ separator: true }`. Labels and descriptions are text, never markup |
+| `activeId` | The model marked, and `request.model` |
+| `label` | The button's text. Default: the active item's label, then `labels.selectModel` |
+| `status` | `{ state?: 'ready' \| 'pending', label? }`: a dot on the button, its tooltip the label. None without `status` |
+
+A model calls `onModelSelect(item)`; a command calls `onModelAction(action, item)`. You get your own item back, with whatever else you put on it. With no items and no label there is no button; with no modes either there is no bar.
+
+### The state machine
+
+`ChatStateMachine` is the conversation lifecycle with no view in it, exported for a chat of your own. `chat.stateMachine` is the shell's.
+
+| State | Goes to |
+|---|---|
+| `idle` | `waiting` (`sendMessage`) |
+| `waiting` | `streaming` (`streamStart`), `idle` (`streamComplete`, `cancel`, `reset`), `error` (`error`) |
+| `streaming` | `idle` (`streamComplete`, `cancel`, `reset`), `error` (`error`) |
+| `error` | `waiting` (`sendMessage`), `idle` (`reset`) |
+
+`newConversation()` and `loadConversation(id)` go back to `idle` from anywhere. `canSend()`, `isProcessing()`, `mode`, `setMode(mode)`, `conversationId` and `lastError` read and set the rest; a mode is any string of yours.
+
+Calls are queued in order, because text can arrive in the same tick as the request that asked for it, and each answers a promise of `{ transitioned, reason? }`. A transition the state does not have is refused, not thrown. So `getState()` lags a call by some microtasks, and is `null` until the machine has entered `idle`; `settled()` resolves when everything called so far has taken effect.
+
+`new ChatStateMachine({ eventBus, logger, mode, onChange })`: `onChange({ state, conversationId, mode })` hears every state entered. `eventBus` gets `CHAT_BUS_EVENTS`:
+
+| Constant | Event | Payload |
+|---|---|---|
+| `STATE_CHANGED` | `chat:state:changed` | `{ state, conversationId, mode }` |
+| `MESSAGE_SENT` | `chat:message:sent` | `{ conversationId, text, mode }` |
+| `STREAM_COMPLETE` | `chat:stream:completed` | `{ conversationId, text, meta }` from the shell |
+| `MODE_CHANGED` | `chat:mode:changed` | `{ mode }` |
+| `CONVERSATION_NEW` | `chat:conversation:new` | `{}` |
+| `CONVERSATION_LOADED` | `chat:conversation:loaded` | `{ conversationId }` |
+| `ERROR` | `chat:error:raised` | `{ conversationId, message, detail }` |
+
+### Classes
+
+The block is `twm-chat-shell`, around the conversation view's `twm-chat`: `__tab-bar`, `__tabs`, `__tab-btn` (`--clear`), `__rename`, `__conversation`, `__welcome`, `__welcome-icon`, `__welcome-text`, `__typing`, `__tools`, `__tool` (`--running`, `--done`, `--error`, `--stopped`), `__tool-icon`, `__tool-label`, `__controls`, `__footer`, `__time`, `__copy` (`--done`), `__retry`, `__bar`, `__bar-spacer`, `__modes`, `__mode` (`--on`), `__model-btn`, `__model-label`, `__model-chevron`, `__model-menu`, `__status` (`--ready`, `--pending`).
+
+A message's role is the view's modifier, `twm-chat__msg--<role>`; the shell uses `user`, `assistant` and `error`. Every rule reads FlexDesk's tokens. Nothing is stored in a `data-` attribute beyond the tab strip's `data-tab-id` and the dropdown's own keys.
+
+`tests/chat_shell.test.mjs` and `tests/chat_state_machine.test.mjs` cover all of this in jsdom.

package/docs/components/conversation.md

@@ -26,6 +26,7 @@ view.setBusy(false);
 | Method | Does |
 |---|---|
 | `append({ id?, role, text, meta? })` → id | Adds a message; `role` becomes `twm-chat__msg--<role>` |
+| `remove(id)` → bool | Takes one message out ([below](#taking-one-message-out-remove-0180)) |
 | `replaceAll(messages)`, `clear()` | Restores a transcript (and scrolls to its end), or empties it |
 | `beginStream(message?)` → id, `appendChunk(text)`, `endStream()` | A message that grows; each chunk re-renders that message's body and nothing else |
 | `slot(id)` | The element below a message's body, yours to fill (tool output, buttons); a re-render leaves it alone |
@@ -70,3 +71,12 @@ view.setBusy(false);
 
 `tests/conversation_view.test.mjs` drives all of it in jsdom with a fake
 scroll geometry.
+
+## Taking one message out: `remove` (0.18.0)
+
+`view.remove(id)` takes one message out and answers `true`, or `false` for an
+unknown id. Every other message keeps its row and its slot, so it costs no
+re-render and moves no reader, where `replaceAll` of the rest redrew all of them
+and scrolled to the end. An open stream on that message is over: `streamingId()`
+is `null` and later chunks go nowhere. It is how the
+[assistant chat shell](chat-shell.md) takes out a reply that ended empty.

package/docs/components/filter-builder.md

@@ -0,0 +1,246 @@
+# Filter builder
+
+> **Package:** `@flexdesk/widgets` · **See also:** [Forms and dialogs](forms-and-dialogs.md) · [All docs](../README.md)
+
+Recursive AND/OR/NOT filters. `createFilterModel` binds your field catalogue into a matcher, a describer and a validator, with no DOM. `createFilterBuilder` edits an expression anywhere you mount it, and `openFilterDialog` opens the same builder in a modal with a name, an icon and your live preview. FlexDesk knows nothing of what is filtered: fields, values and previews are yours.
+
+## The model: `createFilterModel` (0.18.0)
+
+```js
+import { createFilterModel } from '@flexdesk/widgets';
+
+const model = createFilterModel({
+    noun: 'order',
+    fields: [
+        { key: 'customer', label: 'Customer', type: 'text' },
+        { key: 'state', label: 'State', type: 'enum', options: ['open', { value: 'shut', label: 'Closed' }] },
+        { key: 'total', label: 'Total', type: 'number', get: (row) => row.amount.total },
+        { key: 'placed', label: 'Placed', type: 'date' },
+        { key: 'labels', label: 'Labels', type: 'set' },
+        { key: 'paid', label: 'Paid', type: 'bool' },
+    ],
+});
+
+const expr = {
+    kind: 'group', op: 'AND', children: [
+        { kind: 'clause', field: 'state', op: 'is', value: 'open' },
+        { kind: 'group', op: 'OR', negate: true, children: [
+            { kind: 'clause', field: 'total', op: 'gt', value: 1000 },
+            { kind: 'clause', field: 'labels', op: 'contains', value: 'rush' },
+        ] },
+    ],
+};
+
+rows.filter(model.matcherFor(expr));
+model.describeFilter(expr);  // "State is open AND NOT (Total > 1000 OR Labels contains rush)"
+model.validateFilter(expr);  // { ok: true, errors: [] }
+```
+
+### The expression
+
+A group is `{ kind: 'group', op: 'AND' | 'OR', negate?: true, children: [...] }`, nested to any depth. A condition is `{ kind: 'clause', field, op, value? }`. It is plain JSON: store it as it is, or use `serializeFilter(expr)` and `parseFilter(text)`. `emptyFilter()` is a new empty AND group, and `cloneFilter(expr)` a deep copy. A node of any other kind is kept and never interpreted; it matches nothing and `validateFilter` reports it.
+
+An empty AND matches everything. An empty OR matches everything too, unless the model is created with `emptyOr: 'nothing'`. `negate` flips either. `countConditions(expr)` counts the conditions in an expression; for a condition tree, see [below](#a-consumer-that-keeps-trees).
+
+### Fields
+
+| Property | |
+|---|---|
+| `key`, `label`, `type` | `type` is `text`, `enum`, `number`, `date`, `set` (the value is a list) or `bool`. |
+| `get(row)` | The COMPARABLE value, which need not be the displayed one. Default: `row[key]`. |
+| `options` | An `enum` field's values, and a `set` field's when they are a fixed list: bare values, `{ value, label }` or `{ id, label }`. It may be a getter over live data; it is read at use. `filterOptions(field)` normalises them. |
+| `operators` | Operator ids this field is offered, replacing its type's list. |
+| `editor` | A custom value editor ([below](#a-custom-value-editor-0180)). |
+| `hidden` | Not offered for a new condition. A condition already on it keeps working. |
+| `group` | The field select's `<optgroup>` caption. |
+| `time` | On a `date` field: compare instants and draw a date-and-time box, rather than compare days. |
+
+Text comparison ignores case. A date compares by day: `'YYYY-MM-DD'`, and anything after the 10th character is ignored.
+
+### Operators
+
+`FILTER_OPERATORS` is the catalogue by id, and `FILTER_TYPE_OPERATORS` what each type is offered by default:
+
+| Type | Default operators |
+|---|---|
+| `text` | `is`, `is_not`, `contains`, `not_contains`, `starts_with`, `ends_with`, `one_of`, `none_of`, `is_empty`, `is_not_empty` |
+| `enum` | `is`, `is_not`, `one_of`, `none_of`, `is_empty`, `is_not_empty` |
+| `number` | `is`, `is_not`, `gt`, `lt`, `gte`, `lte`, `between`, `one_of`, `none_of`, `is_empty`, `is_not_empty` |
+| `date` | `is`, `is_not`, `before`, `after`, `between`, `in_last_days`, `is_empty`, `is_not_empty` |
+| `set` | `contains`, `not_contains`, `one_of`, `none_of`, `all_of`, `is_empty`, `is_not_empty` |
+| `bool` | `is_true`, `is_false`, `is_empty` |
+
+Also in the catalogue, for a field's `operators`: `is_null` and `is_not_null` (no value at all, as against empty), `gt`, `gte`, `lt` and `lte` on a date.
+
+The `operators` option of `createFilterModel` adds an operator or relabels one. An id FlexDesk knows keeps what you leave out; a new one needs an `arity` (0 no value, 1 one, 2 a range). `multi: true` makes the value a list. `match(rowValue, clauseValue, row)` is what `matcherFor` runs for it; without one, a condition using it matches nothing here, which is fine for an operator only a server runs:
+
+```js
+const model = createFilterModel({
+    fields: [{ key: 'owner', label: 'Owner', type: 'text', operators: ['is', 'is_me', 'is_empty'] }],
+    operators: [
+        { id: 'is', label: 'equals' },
+        { id: 'is_me', label: 'is me', arity: 0, match: (value) => value === me },
+    ],
+});
+```
+
+A field naming an operator the catalogue lacks throws when the model is created.
+
+### What the model answers
+
+| | |
+|---|---|
+| `matcherFor(expr)` | `(row) => boolean`, compiled once and cached by the expression's JSON. An unknown field or operator matches nothing and warns. |
+| `evaluateFilter(expr, row)` | One row. |
+| `describeFilter(expr, { formatValue })` | One line of words. `formatValue(value, field)` names each value (a key shown as a name, say). An unknown field is said: `⚠ unknown field “gone”`; the `unknownName(key)` option of `createFilterModel` shapes the key shown. |
+| `validateFilter(expr)` | `{ ok, errors }`, listing every problem, not the first. |
+| `unknownFields(expr)` | The keys it names that the catalogue lacks, for a marker wherever a saved filter is listed. |
+| `pruneFilter(expr)` | A copy without empty groups and conditions with nothing to compare against, or null when nothing is left. A condition the catalogue cannot read is kept. |
+| `operatorsFor(key)`, `operatorById(id)`, `newClause(key?)`, `defaultValue(field, op)`, `fieldByKey(key)` | What the builder uses. |
+
+`coerceFilterValue(field, text)` is the one place a control's string becomes a value. A `number` field writes a number when the string is a plain decimal a double holds exactly. It leaves the string alone when converting would change the filter: an empty box, a half-typed `-`, or a decimal wider than a double.
+
+## The condition tree (0.18.0)
+
+A server that compiles conditions usually wants a different spelling. `toConditionTree(expr)` and `fromConditionTree(tree)` convert to and from:
+
+```js
+{ op: 'and', children: [
+    { column: 'state', operator: 'eq', value: 'open' },
+    { op: 'not', children: [{ op: 'or', children: [
+        { column: 'total', operator: 'gt', value: 1000 },
+        { column: 'labels', operator: 'contains', value: 'rush' },
+    ] }] },
+] }
+```
+
+| Expression | Tree |
+|---|---|
+| `{ kind: 'group', op: 'AND', children }` | `{ op: 'and', children }` |
+| `{ kind: 'group', op: 'OR', children }` | `{ op: 'or', children }` |
+| `negate: true` on a group of one child | `{ op: 'not', children: [child] }` |
+| `negate: true` on any other group | `{ op: 'not', children: [{ op, children }] }` |
+| `{ kind: 'clause', field, op, value }` | `{ column, operator, value }` |
+| `{ kind: 'opaque', node }` | `node`, untouched |
+| `is`, `is_not` | `eq`, `ne` |
+| `one_of`, `none_of` | `in`, `not_in` |
+| `is_empty`, `is_not_empty` | `is_blank`, `is_not_blank` |
+| `before`, `after` | `lt`, `gt` (one way: reading back gives `lt`, `gt`) |
+| any other operator id | the same id |
+
+What it preserves:
+
+- **A tree comes back identical.** `toConditionTree(fromConditionTree(tree))` equals `tree`, up to the case of `op` and `operator`, which the conversion lower-cases. That includes an operator nobody knows, a `value` of any shape, keys it has never heard of on a node, and a missing `value`. A node it cannot read (an unknown `op`, a `not` of anything but one child) is carried as `{ kind: 'opaque', node }`, which the builder shows read-only.
+- **An expression comes back the same predicate.** The ids may differ in two ways: `before`/`after` read back as `lt`/`gt`, and a negated group of one child reads back as a negated AND.
+- `fromConditionTree(null)` is the empty filter. To send "no filter" as null: `const kept = model.pruneFilter(expr); return kept && toConditionTree(kept);`.
+
+Nothing else differs, except what an empty OR means: the model's default is "everything", and a compiler following SQL's identities says "nothing", so a model whose expressions go to one is created with `emptyOr: 'nothing'`.
+
+### A consumer that keeps trees
+
+Everything in the model takes expressions. A bare tree is not one, and is not refused: `countConditions({ op: 'and', children: [a, b] })` is 1, as is the same call on an empty group. Convert first:
+
+```js
+const count = (tree) => countConditions(fromConditionTree(tree));   // 2 for that tree, 0 for an empty one or null
+```
+
+**The server's operators stay the consumer's.** `FILTER_OPERATORS` is keyed by FlexDesk's ids (`is`, `one_of`, `is_empty`), not a tree's (`eq`, `in`, `is_blank`), and it knows nothing of operators a server adds. FlexDesk has no list of what your server compiles, so that list, and any check that it agrees with the server, stays with you, under the server's ids. Converting a bare condition gives the id to build the model from:
+
+```js
+const ourId = (id) => fromConditionTree({ column: '', operator: id }).op;   // 'eq' -> 'is'
+
+const model = createFilterModel({
+    fields: columns.map((c) => ({ key: c.name, label: c.title, type: c.type, operators: offeredFor(c).map(ourId) })),
+    operators: Object.entries(SERVER_OPERATORS).map(([id, [label, arity]]) => ({ id: ourId(id), label, arity })),
+    emptyOr: 'nothing',
+});
+```
+
+`toConditionTree` sends each one back under the server's id. An arity that disagrees with FlexDesk's is taken as given, and draws the wrong control, so a consumer's own test should compare `FILTER_OPERATORS[ourId(id)]?.arity` with its list.
+
+## The builder: `createFilterBuilder` (0.18.0)
+
+```js
+import { createFilterBuilder } from '@flexdesk/widgets';
+
+const builder = createFilterBuilder(hostEl, {
+    model,
+    value: expr,                       // copied; omit for an empty group
+    onChange: (next) => apply(next),   // a copy, after each change
+});
+builder.getValue();
+builder.setValue(other);               // does not call onChange
+builder.validate();
+builder.focus();
+builder.destroy();
+```
+
+Each group has an AND/OR toggle, NOT, `+ Condition` and `+ Group`; each condition a field select, an operator select and a value control drawn from the field's type and the operator. Removing the last condition of a nested group removes the group; the root may stay empty. A structural change redraws the tree and puts the focus back on what you were using; typing redraws nothing, so the caret stays.
+
+**It rewrites nothing it cannot read.** A condition on a field the catalogue lacks, an operator it lacks, an operator this field is not offered, an `enum` value no longer offered and a carried node all stay exactly as they are until someone changes or removes them: the selects show them as their own entry (`⚠ unknown field “gone”`, `made_up (unknown)`), and a value it cannot interpret is shown read-only. Opening and closing a builder leaves the expression byte-identical, with one exception: an `enum` condition with no value takes the first option, because a select cannot show nothing.
+
+### A custom value editor (0.18.0)
+
+`field.editor` replaces the value control. It is a factory, called each time the value cell is drawn:
+
+```js
+{
+    key: 'owner', label: 'Owner', type: 'text',
+    operators: ['is', 'is_not', 'is_empty'],
+    editor: ({ field, op, value, label, onChange }) => {
+        const picker = createPersonPicker({ value, ariaLabel: label, onPick: (p) => onChange(p?.id ?? '') });
+        return { el: picker.el, destroy: () => picker.destroy() };
+    },
+}
+```
+
+Return `{ el, destroy? }`; `destroy` is called when the cell is redrawn or the builder destroyed, so an editor with a floating list can take it off the page. Return nothing to get the default control for that operator. It is not called for an operator with no value. For a `multi` or range operator, `value` and `onChange` deal in the whole list. To show a stored key as a name in the description, pass `formatValue` to `describeFilter`.
+
+## The dialog: `openFilterDialog` (0.18.0)
+
+The builder in a [modal](forms-and-dialogs.md#windows-closing-focus-and-esc-01716), so its chrome, focus trap, Esc handling and stacking are every other modal's.
+
+```js
+const result = await openFilterDialog({
+    model,
+    value: saved?.expr,
+    title: saved ? 'Edit filter' : 'New filter',
+    name: { value: saved?.label ?? '', placeholder: 'e.g. Large open orders' },
+    iconChoice: { value: saved?.icon, options: ['flag', 'star', 'bolt'] },
+    confirmDiscard: true,
+    submitLabel: 'Save',
+    onSubmit: (r) => store.save({ id: saved?.id, label: r.name, icon: r.icon, expr: r.expr }),
+    actions: saved ? [{
+        label: 'Delete', value: 'delete', danger: true,
+        confirm: { title: 'Delete this filter?', message: 'This cannot be undone.', confirmLabel: 'Delete', danger: true },
+        run: () => store.remove(saved.id),
+    }] : [],
+    preview: (host, { expr, signal }) => {
+        const hits = rows.filter(model.matcherFor(expr));
+        host.textContent = `${hits.length} of ${rows.length} orders match`;
+    },
+});
+// null when dismissed; else { action: 'submit' | 'clear' | yours, expr, name?, icon? }
+```
+
+| Option | |
+|---|---|
+| `model`, `value` | As the builder's. `value` is copied, so dismissing loses nothing. |
+| `seedField` | A field key: adds a new condition on it, for "filter by this". |
+| `title`, `icon`, `width`, `height` | The window. |
+| `head` | An element drawn above the conditions. |
+| `name` | `{ value, label, placeholder, required }` adds a name box. `required` defaults to true and holds the submit button off until it is filled. The result's `name` is trimmed. |
+| `iconChoice` | `{ value, options }` adds a searchable grid over those Material Symbols names. |
+| `preview` | `(host, { expr, sentence, signal })`: yours to draw into. Called on open and, debounced, after each change, while the expression can be submitted; otherwise the slot is emptied and hidden and the errors are shown. `signal` aborts when this drawing is superseded or the dialog closes, for a preview that asks a server. The dialog shows `sentence` above the slot. |
+| `requireValid` | Default true: the submit button is off, and the errors are listed, while `validateFilter` objects. False submits regardless. |
+| `prune` | Validate, preview and submit `model.pruneFilter(...)`, so a half-built row is dropped rather than refused. `expr` is null when nothing is left. |
+| `confirmDiscard` | Ask before Cancel, Esc or the X throws away a change. |
+| `submitLabel`, `onSubmit` | `onSubmit(result)` may be async: until it settles every button is off and Esc and the X do nothing, so the answer always says what happened. If it throws, the message is shown and the dialog stays. A promise that never settles holds the dialog open, so give a call that can hang its own timeout. |
+| `clearLabel` | Adds a button answering `{ action: 'clear', expr: null }`, for a caller to whom "no filter" and "leave it alone" are different answers. |
+| `actions` | More buttons, before Cancel: `{ label, value, danger, icon, confirm, run }`. `confirm` is `openConfirm`'s options, asked first, and `run` behaves as `onSubmit` does. |
+
+`confirmDiscard` asks through [`openModal`'s `beforeClose`](forms-and-dialogs.md#a-modal-that-can-refuse-to-close-beforeclose-0180).
+
+## Styling
+
+Classes are `twm-filter-builder*` and `twm-filter-dialog*`. Every rule reads tokens; retheme through those.

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

@@ -99,6 +99,20 @@ submit with "onCreate is not a function".
 `tests/open_form.test.mjs` mounts the real `openForm` in jsdom and covers all
 four, plus a plain form submitting as before.
 
+#### It is `createCombobox` (0.18.0)
+
+The field draws with [`createCombobox`](input-fields.md#a-text-box-that-also-offers-a-list-createcombobox-0180)
+instead of an `<input list>` and a `<datalist>`, so its list shows each option's label and
+`description`, and looks like the rest of the app. What it submits has not changed.
+
+- **Enter with the list open closes the list; the next one submits.** Escape closes the list and
+  leaves the form open. No row is active until the arrow keys pick one, so Enter keeps what was typed.
+- The markup differs: no `<datalist>`, and `.twm-combobox__hint` has no `data-for`. Read it
+  under its row, `[data-field-row="kind"] .twm-combobox__hint`. The input is still `[name="kind"]`.
+
+A plain `select` stays a native `<select>`: `selectBox` is shared with the charts,
+the settings page and the flow kit, so drawing a form's with `createSelect` would remove no code.
+
 ### Options: typed, unavailable, grouped, and changed while open (0.17.0)
 
 ```js
@@ -310,6 +324,14 @@ the caller's own DOM.
 `tests/confirm_escaping.test.mjs` opens each of them in jsdom with hostile
 names and labels.
 
+## A modal that can refuse to close: `beforeClose` (0.18.0)
+
+`openModal({ beforeClose })` takes `() => boolean | Promise<boolean>`, as
+`ManagedWindow`'s does. It is asked when Esc or the X would dismiss the modal, and
+answering false keeps it open. An action button does not ask it. A modal it lets
+close resolves `null`, as any dismissal does. `openFilterDialog`'s `confirmDiscard`
+is built on it.
+
 ## Windows: closing, focus and Esc (0.17.16)
 
 Every dialog above is a `ManagedWindow`, and so is any window you build