flexdesk 0.17.0 → 0.17.2

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.17.2 (2026-10-22)
+
+A patch release: everything below is additive. Every entry is documented in a
+README section headed "(0.17.2)"; each entry links to it.
+
+### Added and changed
+
+- [An open single instance takes new props: `navigate(props)`](README.md#an-open-single-instance-takes-new-props-navigateprops-0172): opening a `single` kind that is already open with new props reveals it and calls its content's `navigate(props)` hook once; the props are recorded on the tab. An open that names no props only reveals.
+- [A link to a kind nobody registered](README.md#a-link-to-a-kind-nobody-registered-0172): `wm.navigate` to a kind that is not registered logs one warning, changes nothing and returns `false`.
+- [A palette row drawn disabled, with a reason](README.md#a-palette-row-drawn-disabled-with-a-reason-0172): a command with `enabled: () => false` is listed greyed (`aria-disabled`), does nothing when picked, and shows its `disabledReason` as a tooltip.
+- [A catalog source only behind its prefix: `scopedOnly`](README.md#a-catalog-source-only-behind-its-prefix-scopedonly-0172): a catalog source with `scopedOnly: true` is searched only when its prefix is typed, in the flat and the grouped palette.
+- [The settings categories outside the page: `SettingsCategories`](README.md#the-settings-categories-outside-the-page-settingscategories-0172): `SettingsView` can leave out its own category list and filter, and `SettingsCategories` (new export from `@flexdesk/widgets`) shows them anywhere, kept in step with the view.
+- [Toast cards are styled and clickable](README.md#toast-cards-are-styled-and-clickable-0172): toast cards use `twm-notification` and `twm-notification--<severity>`, styled in flexdesk.css and base.css, with their entry animation defined there; cards take pointer events, so their buttons work (BUG-0033). A sheet that targeted `.notification` must target `.twm-notification`.
+
+### Removed or renamed exports
+
+None. Compared with 0.17.1, across every entry point (`core`, `widgets`, `wm`,
+`host`, `canvas`, `flow`, `charts`, `tiles`, `editor`) and the package
+`exports` map, exports were only added: `SettingsCategories` in `@flexdesk/widgets`.
+Not an export but worth knowing: toast cards changed class from `notification`
+to `twm-notification` (see above).
+
+## 0.17.1 (2026-10-21)
+
+A patch release: everything below is additive. Every entry is documented in a
+README section headed "(0.17.1)"; each entry links to it.
+
+### Added and changed
+
+- [Built-in cell editors](README.md#built-in-cell-editors-0171): an editable DataTable column opens the editor for its type (`text`, `multitext`, `number`, `bool`, `choice`, `datetime`), each with a parse that refuses what it cannot read; `editors` replaces one per type or per column, with `editTypes`, `locale` and `editorMessages`. The editors and their parsers (`CELL_EDITORS`, `createNumberEditor`, `parseNumber`, `parseDateTime` and the rest of `cell_editors.js`) are exported from `@flexdesk/widgets`.
+- [Copying cells as tab-separated values](README.md#copying-cells-as-tab-separated-values-0171): in cell mode Ctrl+C copies the selected cell range as the tab-separated text Excel and Google Sheets paste into cells; `toTSV` and `tsvCell` (from `@flexdesk/widgets`) write it.
+- [Pasting a block from Excel](README.md#pasting-a-block-from-excel-0171): `pasteable: true` beside `staged` pastes a tab-separated block at the cursor cell, each value read by its column's editor, staged as one undo entry, with column and row overrun handling; `fromTSV` (from `@flexdesk/widgets`) reads it.
+- [Building a modeler](README.md#building-a-modeler-0171): the canvas editor's modeler options shown working together, with `demo/flow_modeler.html` (linked from `demo/index.html`).
+- [The `development` condition resolves in the installed package](README.md#the-development-condition-resolves-in-the-installed-package-0171): the nine root entry barrels are in `files`, so the `exports` map's `development` targets ship (BUG-0032). An `import` still resolves to `dist/`.
+
+### Removed or renamed exports
+
+None. Compared with 0.17.0, across every entry point (`core`, `widgets`, `wm`,
+`host`, `canvas`, `flow`, `charts`, `tiles`, `editor`) and the package
+`exports` map, exports were only added.
+
 ## 0.17.0 (2026-10-21)
 
 Every feature below is documented in a README section headed "(0.17.0)"; each

package/README.md

@@ -237,6 +237,65 @@ with it. The taxonomy answers `isSingle(kind)`, `instanceKey(kind, props)` and
 `singleReason(kind)`; the window manager answers `isSingleKind(kind)`,
 `findInstance(kind, props)` and `revealInstance(kind, props)`.
 
+### An open single instance takes new props: `navigate(props)` (0.17.2)
+
+Revealing a `single` instance used to drop the props the open asked for: the
+observatory kept showing the planet it was opened with. A content factory that
+returns a `navigate(props)` hook from its mount is now handed them:
+
+```js
+content: {
+    observatory: (el, props) => {
+        const view = mountObservatory(el, props);
+        return {
+            destroy: () => view.destroy(),
+            navigate: (next) => view.focusPlanet(next.planet),   // already open: go there
+        };
+    },
+},
+
+wm.navigate('observatory', { planet: 'mars' });   // open: revealed, then navigate({ planet: 'mars' })
+```
+
+- **Every open path that reveals the instance calls it once**, after the
+  reveal, with a copy of the new props — `navigate`, the top nav,
+  `openInPrimary`, `openInTab*`, `splitLeafWith`, Back. The same props twice
+  are two calls; nothing is deduplicated, and no second instance is mounted.
+- **The props are recorded on the instance's tab** (or its window's), so a
+  top-nav page restore or a reload mounts it with the latest. The tile is not
+  rebuilt by the write.
+- **An open that names no props only reveals** — the top-nav button,
+  `openInPrimary(kind)`, `navigate(kind)`: it asks to see the instance, not to
+  empty it, so the hook is not called and the tab keeps its props.
+- **A content without the hook is revealed as before**: its tab keeps its props
+  and nothing is called. A hook that throws is a console warning.
+
+### A link to a kind nobody registered (0.17.2)
+
+`wm.navigate(kind, props, opts)` returns `true` once it has routed the
+navigation. A `kind` the shell's `content` map has no factory for is refused
+instead, on every destination (`main`, `origin`, a new tab, a window, a split,
+the legacy `target`):
+
+```js
+if (!wm.navigate(link.kind, link.props)) {
+    // nothing opened: tell the user the link is dead
+}
+```
+
+- **One `console.warn` naming the kind**, per call, and `false` back.
+- **Nothing changes**: no tile, tab, window or desktop, no per-tab history, no
+  `onChange` — and no "no factory registered yet" placeholder tile, which is
+  what such a link used to leave behind.
+- **No exception reaches the caller**, whatever `kind` is (`undefined`, `null`
+  and `''` included).
+
+A shell that only navigates to kinds it registered sees no change; the return
+value is new, so code that ignored it is unaffected. A split destination used
+to hand back the new leaf's id; it now returns `true` like the others — call
+`wm.splitLeafWith(...)` for the id. A restored layout that names an
+unregistered kind still draws its placeholder: only `navigate` refuses.
+
 ### A pane that names what it shows: `ctx.setTitle` (0.12.1)
 
 A content factory receives `(hostEl, props, ctx)`, and `ctx` carries, per pane,
@@ -450,6 +509,60 @@ topic.* The fallback comes from `HelpModal.open(id, { fallback })`
 (`@flexdesk/widgets`), and you can pass one yourself. A topic id that nobody
 provides now shows *Help topic not found.* where it used to raise a load error.
 
+### A palette row drawn disabled, with a reason (0.17.2)
+
+A palette row (a command from `commands`, or any other row) may carry
+`enabled: () => boolean` and `disabledReason`. While `enabled()` returns false
+the row is still listed, so it can say why it does nothing:
+
+```js
+palette: {
+    commands: () => [
+        { id: 'save', label: 'Save', action: save,
+          enabled: () => dirty, disabledReason: 'Nothing to save' },
+    ],
+},
+```
+
+- The row gets the class `twm-cmdpal__item--disabled` and `aria-disabled="true"`,
+  and `disabledReason`, when given, is its `title` (the tooltip). The stylesheet
+  greys it.
+- Picking it with a click, Enter, Ctrl+Enter or Shift+Enter runs nothing: not
+  its `action`, not `onPick`. The palette stays open on it.
+- The arrow keys still move onto it and past it.
+- `enabled()` is called again on every draw and every pick, so the row follows
+  your state while the palette is open. An `enabled()` that throws counts as
+  false.
+- A row without `enabled` is drawn and picked as before. Both layouts (flat and
+  `grouped`) behave the same way.
+
+`tests/command_palette_disabled.test.mjs` drives it in jsdom.
+
+### A catalog source only behind its prefix: `scopedOnly` (0.17.2)
+
+A source can be too broad to compete with everything else in the palette: help
+topics, say, which would crowd every query. Mark it `scopedOnly` and its rows are
+listed only once its prefix has made the type chip:
+
+```js
+createEntityCatalog({
+    sources: [
+        { navKind: 'model', list: listModels, shape: toRow },
+        { navKind: 'topic', list: listTopics, shape: toRow, scopedOnly: true },
+    ],
+    aliases: { help: ['topic'] },
+});
+```
+
+A plain typed query (`solver`) lists no `topic` row, in the flat and the grouped
+layout alike: no row, no group header, no *Show all*. `help: solver` or
+`topic: solver` lists its rows as any source's, and `help:` alone lists them all.
+The mark is the palette's business: `loadAll`, `loadGrouped` and the tile menu
+still return every source, a picked row reaches `onPick` as its `shape` made it,
+and commands and `empty()` rows of the same kind are not held back. A source
+without the option, or with `scopedOnly: false`, is searched exactly as in
+0.17.1. A value that is not a boolean is refused with a `TypeError`.
+
 ### Your keys, not the window manager's: `keymap` (0.17.0)
 
 The window manager binds F1..F12, Backspace, Ctrl+K, Ctrl+Tab, Ctrl/Shift+Arrows,
@@ -1324,10 +1437,10 @@ grid.getCellSelection();   // { anchor, focus, range }
 | The keys (focused table) | Arrows move the cursor (Shift extends the range). Ctrl+arrow jumps to the edge of the block of filled cells, as a spreadsheet does. Home/End go to the row's first and last cell (Ctrl: the page's first and last cell). Tab moves right and wraps to the next row (Shift+Tab back); on the last cell (Shift+Tab: the first) the table does not take the key, so focus moves on out of the table. ArrowDown on the last row stays put. Ctrl+A selects every cell of the page; Escape collapses the range onto the cursor. The cursor stays on the page drawn and is scrolled into view; under `virtualize` its row is drawn. |
 | `getCellSelection()` | `{anchor, focus, range}`. A cell is `{row, col, rowIdx}`: `row` is the position in the order shown (as `getDisplayedRows()` lists them, after sort and filter), `col` the data column, `rowIdx` the original row index. `range` is `{top, bottom, left, right, rows, columns}`: positions, the data columns at its edges, and the original row indices and data columns it covers (a hidden column inside it is not one of them). Null outside cell mode. |
 | `setCellSelection(focus, anchor?)` | Puts the cursor on `{row, col}`, or selects from `anchor` to it; `null` clears. The row is brought into view. |
-| `getSelection()`, `setSelection()`, Ctrl+C | Still about rows: `getSelection()` returns the rows the range touches, `onSelectionChange` hears them, and Ctrl+C and the copy menu copy them. `setSelection(indices)` selects the cells of those rows, first to last as shown. |
+| `getSelection()`, `setSelection()` | Still about rows: `getSelection()` returns the rows the range touches and `onSelectionChange` hears them. `setSelection(indices)` selects the cells of those rows, first to last as shown. Ctrl+C and the copy menu copy cells, not rows, from 0.17.1 (below). |
 | `onCellSelectionChange(sel)` | Called with `getCellSelection()` after every change. |
 | `editable` | Which cells open an editor: `true`, an array of data column indices, or `(colIdx, row, rowIdx) => boolean`. Needs cell mode. F2, Enter, a double-click or a printable key opens it on the cursor cell (a printable key replaces the value with that character). In the editor Enter commits and moves down, Tab commits and moves right (Shift: up, left), Escape restores the cell and calls nothing; the focus leaving it commits without moving. `editCell(row, col)` opens one from code; `isEditing()` says whether one is open. |
-| `editors: {[colIdx \| type]: factory}` | The editor for a column, looked up by column index and then by type (`columnTypes`, else the detected `num`/`text`). A factory gets `{value, row, rowIdx, colIdx, column: {index, header, type}, initialText, commit(value), cancel()}` and returns an element or `{el, getValue?, focus?, destroy?}`. An input, select or textarea commits its `value` on Enter and Tab; any other editor calls `commit(value)` itself. The default is a text box (`createTextEditor`). |
+| `editors: {[colIdx \| type]: factory}` | The editor for a column, looked up by column index and then by type (`columnTypes`, else the detected `num`/`text`). A factory gets `{value, row, rowIdx, colIdx, column: {index, header, type}, initialText, commit(value), cancel()}` and returns an element or `{el, getValue?, focus?, destroy?}`. An input, select or textarea commits its `value` on Enter and Tab; any other editor calls `commit(value)` itself. Without one, a column gets the built-in editor for its type, else a text box (`createTextEditor`); see [Built-in cell editors](#built-in-cell-editors-0171) for the editors, the `editTypes`, `locale` and `editorMessages` options and what a factory is told since 0.17.1. |
 | `onCellCommit({rowIdx, colIdx, value, previous})` | Called exactly once per commit; `previous` is the value the row holds, and a value left as the cell showed it is no commit. Return nothing or `{ok: true}` (or a Promise of it) and the value is written into the row the table holds for `rowIdx` when it settles (`rows[rowIdx][colIdx]`, so a row put in by `updateRow` meanwhile keeps its other cells) and drawn. `{ok: false, error}`, a rejection or a throw leaves the typed value in the cell, drawn `twm-dt-cell--error` with the message as its `title` and `data-error`, until a later commit of that cell succeeds, the value the row holds is committed back (no call: nothing to save), or new rows arrive. While the Promise is out the cell is `twm-dt-cell--pending`. The editor always opens with the value the cell shows, a refused or pending one included. |
 | While an editor is open | `render()`, and so `setData`, a sort or a page, waits and runs when the editor closes, so what is being typed is never thrown away. A commit that settles while another editor is open in its row marks its cell at once and draws the row when that editor closes. `updateRow` on the row the editor is in stores the data at once (`config.rows`, the window's row list) and returns `true`, and the row is drawn with it when the editor closes; the editor's cell is left as it is. A row that scrolls out of the virtual window commits its editor first. An editor with no `getValue` (a `{el}` around an element that is not an input, select or textarea) has no value the table can read: Enter, Tab and the focus leaving do nothing, and its row scrolling out cancels it, so what it holds is lost unless it has called `commit(value)` itself. |
 | `headerMenu(colIdx, ctx) => items` | Items for the header's right-click menu, asked for the data column right-clicked (`ctx` is `{colIdx, header, hiddenColumns, table}`). Items are `{label, action, icon?, disabled?, danger?, title?}` or `{separator: true}`. Choosing one calls `onHeaderMenuAction(action, colIdx)`. With `columnChooser` the chooser's items follow behind a separator. `[]` or `null` shows only what would show without the hook: the chooser, or the page's own menu. Works in either selection mode. |
@@ -1338,6 +1451,100 @@ DOM), `CellEditorHost` (one cell's editor, opened and closed exactly once) and
 `createTextEditor` (the default text box). The table's own half of cell mode
 is internal.
 
+#### Built-in cell editors (0.17.1)
+
+An editable column opens the editor for its type: `text`, `multitext`,
+`number`, `bool`, `choice` or `datetime`. Each reads what is typed with a
+parse, and a value that does not parse is refused on the cell. `editors`
+replaces any of them, for its type or its column only.
+
+```js
+const grid = DataTable.mount(host, {
+    headers: ['Item', 'Qty', 'Colour', 'Note'],
+    rows,
+    selectionMode: 'cells',
+    editable: true,
+    editTypes: [null, 'number', { type: 'choice', options: ['red', 'green'] }, 'multitext'],
+    locale: 'de-DE',                        // '1.234,56' is 1234.56
+    editorMessages: { number: 'Keine Zahl' },
+    editors: { 3: myNoteEditor },           // by column index or by type
+    onCellCommit: ({ value }) => save(value),   // Qty commits a Number
+});
+```
+
+| Option | What it does |
+|---|---|
+| The built-in editors | `text` a text box; `multitext` a text area (Enter is a new line, Ctrl/Cmd+Enter commits); `number` a text box that commits a Number; `bool` a checkbox that commits `true`/`false` when ticked or unticked (a space that opens it ticks it over); `choice` an `AutocompleteField` over the column's `options` that commits the option's value; `datetime` a text box that commits a Date. A blank number, date or choice commits `null`. A value opened and left as it was commits nothing. |
+| `editTypes` | Each column's editor type, by position (an array) or by data column index (an object): a name (`'text'`, `'multitext'`, `'number'`, `'bool'`, `'choice'`, `'datetime'`, or any name `editors` is keyed by) or `{type, options?, allowOther?, rows?}`. Unset, it is the column's `columnTypes` type, else the detected one, so a numeric column opens the number editor and a `date` column the datetime editor. `choice` offers `options` (values, or `{value, label}`), filtered as you type; a pick commits its value, and typed text matching an option's label or value (any case) commits that value. Other text is refused unless `allowOther`, when it is the value. With the list open, Escape closes the list only. `rows` is a `multitext` area's height in lines (3). Only editing reads `editTypes`: drawing, sorting and filtering are as without it. |
+| `locale` | The locale the number and datetime editors read and show text in (Intl's; unset: the runtime's). `'1.234,56'` is 1234.56 under `de-DE` and `'1,234.56'` is under `en-US`, and `'1 234,5'` is 1234.5 under `fr-FR` (any space, a no-break one included, where the locale groups with a space); a group separator anywhere but between groups of three digits, or a space inside the number anywhere else, is refused, never misread. Spaces around the text are ignored. A number opens without groups, in the locale's decimal separator. A datetime reads ISO 8601 (`2026-12-31`, `2026-12-31T08:30`, with `Z` or an offset an exact instant) in any locale, and day, month and year in the locale's order with a four-digit year and an optional time (`31/12/2026 08:30` under `en-GB`); when the locale's order makes no date but the day-month swap does, the swap is read. A date with no zone is in `dateTimeZone`'s. It opens as ISO. |
+| A value that does not parse | `abc` in a number, `31/02/2026` in a date, a choice outside the options: Enter and Tab are refused, the editor stays open, and the cell carries the message (`twm-dt-cell--error`, `title`, `data-error`) until the next keystroke. Nothing is committed. If the focus leaves (or the row scrolls out of the window) with it, the editor closes and the cell keeps the text, marked as a refused commit is, and `onCellCommit` is not called. Under `staged` nothing is staged; anything staged into the cell afterwards (a typed value, a fill, the value the row holds) ends the refusal. The words are `EDITOR_MESSAGES`, overridden by `editorMessages: {number, datetime, bool, choice}`. |
+| `editors` (0.17.1) | The editor for a column, looked up by column index and then by type (`editTypes`, else `columnTypes`, else the detected `num`/`text`; as named, then as the built-in editors name it: `num` is `number`, `date` is `datetime`). A factory gets `{value, row, rowIdx, colIdx, column: {index, header, type, ...the editTypes entry}, locale, utc, messages, initialText, commit(value, move?), cancel()}` and returns an element or `{el, getValue?, parse?, multiline?, focus?, destroy?}`. An input, select or textarea commits its `value` on Enter and Tab; any other editor calls `commit(value)` itself. With `parse()` (`=> {ok: true, value} \| {ok: false, error}`) Enter, Tab and the focus leaving commit what it reads, and a refusal is handled as the built-in editors' is. `multiline` keeps Enter for a new line (Ctrl/Cmd+Enter commits). An injected editor replaces the built-in one for its type (or its column) only. Without one, a column gets the built-in editor for its type, else a text box (`createTextEditor`). |
+
+Exported from cell_editors.js for a consumer that builds its own grid or
+reads pasted text: the six editors as `CELL_EDITORS` (`{text, multitext,
+number, bool, choice, datetime}`, each `{create, parse}`: `create` a factory,
+`parse(text, {locale, utc, options, allowOther, messages})` the same reading
+of plain text, for a paste) with their parts: `parseNumber`, `parseDateTime`,
+`parseBool`, `parseChoice`, `formatNumberForEdit`, `formatDateTimeForEdit`,
+`numberSeparators`, `dateOrder`, `normalizeOptions`, `editorTypeOf`,
+`EDITOR_MESSAGES` and `createNumberEditor`, `createMultiTextEditor`,
+`createBoolEditor`, `createChoiceEditor`, `createDateTimeEditor`.
+`CellEditorHost` takes an `onRefuse(session, error, text, reason)` beside
+`onCommit` and `onCancel`, called when an editor closes holding a value that
+does not parse (without it, such a close is a cancel).
+
+#### Copying cells as tab-separated values (0.17.1)
+
+In cell mode Ctrl+C copies the cells selected, as the tab-separated text Excel
+and Google Sheets paste into cells.
+
+| What | What it does |
+|---|---|
+| Ctrl+C, the copy menu, `copyToClipboard()` | With `copyable` (the default), copy the CELLS selected, not their rows: a 3×4 range is 3 lines of 4 tab-separated values, in the order shown after sort and filter, its shown columns only (a hidden column inside it is left out), with no header line. With no range beyond the cursor, the cursor cell's value alone. A cell is its RAW value, not the text it shows: no `formatValue`, typed-column format, rounding or `nullDisplay` (a Price drawn `1,234.50`, value 1234.5, copies as `1234.5`); the value the cell holds now, a staged, pending or refused one included; `null` is empty. Dates copy as ISO 8601: a `Date` as `toISOString()`, in a column declared `'date'` as its day `YYYY-MM-DD` in the table's zone (`dateTimeZone`); a number in a declared `'date'`/`'datetime'` column is read as epoch ms the same way; text is copied as it is. A value holding a tab, a newline or a quote is quoted the way Excel quotes it (`"say ""hi"""`), so Excel and Google Sheets paste it back into one cell. Cell mode has no CSV copy: the right-click menu's copy item is "Copy Cells" alone (the same text as Ctrl+C), Ctrl+Shift+C is not bound (the key is left to the page), and `copyToClipboard('csv')` copies nothing and warns. Without cell mode, Ctrl+C, Ctrl+Shift+C and the copy menu ("Copy Row(s)", "Copy as CSV") copy the selected rows with a header line, as in 0.16. |
+
+`toTSV(matrix)` and `tsvCell(value)` write tab-separated text with Excel's
+quoting (a cell holding a tab, a newline or a quote is quoted and its quotes
+doubled; `null` is empty; no newline after the last row): the writer cell mode
+copies with.
+
+#### Pasting a block from Excel (0.17.1)
+
+With `pasteable: true` beside `staged`, Ctrl+V on the focused table pastes the
+tab-separated block Excel and Google Sheets copy at the CURSOR cell: it fills
+right over the columns shown and down over the rows in the order shown, each
+value read by its column's editor, and every cell is STAGED as one undo entry.
+
+```js
+const grid = DataTable.mount(host, {
+    headers: ['Item', 'Qty', 'When'],
+    rows,
+    selectionMode: 'cells',
+    editable: (colIdx, row) => colIdx !== 0 || !row.locked,
+    editTypes: [null, 'number', 'datetime'],
+    staged: true,
+    pasteable: true,
+    onPasteOverrun: ({ rows }) => confirm(`Add ${rows} row(s)?`),
+    onRowsAppend: ({ rows, errors }) => store.addRows(rows),
+    onCommit: ({ edits }) => api.saveBatch(edits),
+});
+await grid.paste('Bolt\t4\t2026-12-31\nNut\t9\t2027-01-02');   // what Ctrl+V does
+```
+
+| Option or method | What it does |
+|---|---|
+| `pasteable: true` | Needs `staged` (ignored with a warning without it). Ctrl+V on the focused table takes the browser's `paste` event (its `text/plain`, read by `fromTSV`); a paste inside an open editor or another field is that field's. The block lands at the cursor cell; a hidden column is stepped over. Each value is read by the parse of its column's editor: the built-in editor's for its type (`editTypes`, else `columnTypes`, else the detected one; `locale`, the zone and `editorMessages` as an editor reads them), or an injected `editors` factory's own `parse` property (`factory.parse = (text, ctx) => ({ok: true, value} \| {ok: false, error})`), else the text as it is. Every cell that reads is staged as ONE undo entry: one Ctrl+Z takes the whole paste back. A value equal to what the row holds is no change. The range then covers the block, the cursor on the cell it began at. Nothing is pasted while an editor is open, a commit is out or another paste waits. |
+| Columns past the last | Dropped. A console warning and a `'warn'` toast (`toast:show` on `services.eventBus`) name how many: "3 column(s) past the last column were not pasted." |
+| Rows past the last loaded row | The last loaded row is the last row in the order shown (filtered and sorted; for a server's page, the last row it sent). `onPasteOverrun({rows: n})` is asked first, `n` the rows past it. Anything but `true` (or a Promise of `true`) stages NOTHING; without the hook, such a paste stages nothing and warns. `true` hands the extra rows to `onRowsAppend({rows, errors})` and, once that settles, stages the rows that fit: `rows` are data rows (as long as `headers`, every pasted column read by its parse, the others `null`), and `errors` the values that did not read (`{row, colIdx, text, error}`, `row` an index into `rows`; that cell is `null`). Adding them is the consumer's: the table holds no row it was not given. A consumer that adds them with `setData({rows})` (the old rows first, the new ones after) keeps the paste's staged cells, because they are staged after it. Without `onRowsAppend` the extra rows are dropped with a warning. |
+| A value that does not parse | `abc` in a number column: its cell is marked as an editor's refusal is (`twm-dt-cell--error`, the message as `title` and `data-error`, the pasted text kept in the cell) and nothing is staged in it; the rest of the block still stages. Anything staged into the cell afterwards ends the mark. |
+| A cell `editable` refuses | Skipped: nothing is staged in it and its row is untouched. It is drawn `twm-dt-cell--paste-skipped` until the selection moves, the next paste or fill, or new rows. |
+| `paste(text)` | What Ctrl+V does, from code. Resolves `{rows, cols, staged, skipped, refused, droppedColumns, appended}` (`staged` the NUMBER of cells that changed; `skipped` `[{row, col, rowIdx}]`; `refused` the same with `text` and `error`; `appended` the rows handed to `onRowsAppend`), or `null` when nothing was pasted: no `pasteable`, empty text, no cursor, an editor open, a commit or another paste out, an overrun not accepted, or new rows while `onPasteOverrun` was asked. |
+
+`fromTSV(text)` reads tab-separated text as a matrix of strings, as Excel
+writes it: character by character, so a quoted cell holding a tab, a newline
+or doubled quotes is one cell; a quote opens a quoted cell only at its start;
+CRLF lines read as LF ones; the newline after the last row (and any empty
+lines after it) is no row; empty text is `[]`. Exported beside `toTSV`.
+
 #### Staged edits, undo and redo, one commit (0.17.0)
 
 With `staged: true` beside `editable`, a commit from an editor is STAGED
@@ -2086,7 +2293,7 @@ nor is a step whose type the palette does not offer (a start step) or that is
 `unavailable`. What is copied is the graph's own text, `{nodes, connections}`
 as `serialise()` writes it, so a graph from elsewhere pastes too. Ctrl/⌘+V
 gives every pasted step a fresh id (as a new step gets one), keeps the lines
-between them, sets the copy off two grid steps right and down (each further
+between them (data lines too, under `connections` with `dataPorts: 'connect'`, from 0.17.1), sets the copy off two grid steps right and down (each further
 paste of the same text one more), picks it, and is one `flow:paste` entry. A
 paste right after Ctrl/⌘+X puts the steps back where they were; a cut is one
 remove entry. A step whose title the flow already has gets a derived label,
@@ -2168,6 +2375,112 @@ Edge:
   the step between its ends. Above the node limit the strip said so.
 - A real pointer over a step highlighted its lines, and moving off cleared them.
 
+#### Building a modeler (0.17.1)
+
+A typed node modeler (a dataflow, a signal chain, a diagram of blocks) is the
+canvas editor with its modeler options turned on. Every one of them is a
+`createCanvasEditor` option or a key on a catalogue type, off by default: an
+editor that sets none of them draws, binds and serialises exactly as before.
+None of them stores anything: the graph, the viewport and the values shown are
+the host's, handed in and handed back. Each edit they add is on the closed list
+`CANVAS_ACTIONS`, so one gesture is one undo entry. `demo/flow_modeler.html`
+(linked from `demo/index.html`) uses all of them together on a signal-flow
+diagram of sources, gains, a sum and displays.
+
+| Option | What it gives | Details |
+|---|---|---|
+| `render`, `update`, `size`, `accent` (type keys) | A node that draws its own controls and values, at its own size, marked in a tone; `setCatalogue` adds a type while the editor is open | [Node bodies](#node-bodies-0170) |
+| `connections` (`dataPorts`, `policy`) with `accepts` / `provides` (port keys) | Data ports that connect, typed, under the host's rules, by drag or click; an empty drop picks a step that arrives connected | `connections` above |
+| `multiSelect` | Marquee, bulk move and delete, nudge, align and distribute | *Many picked* above |
+| `clipboard`, `prepareCopy` | Copy, cut, paste and duplicate of the picked steps and the lines among them | *Copy and paste* above |
+| `groups`, `notes` | Flat named frames round steps, and free-text notes | *Groups and notes* above |
+| `layout`, `rank` (type key) | Arrange by the kernel's layered layout, sources first and sinks last, or your own | `layout` above |
+| `edgeStyle`, `routing`, `hoverHighlight` | Lines in a tone, dashed, wider, with an arrow or a crow's foot and a label; bent round steps; lit while pointed at | `edgeStyle` above |
+| `viewport`, `onViewportChange`, `zoomControls`, `minimap` | Where the reader looks, kept by you; zoom buttons; an overview | `viewport` above |
+| `renameInPlace`, `inline` (type key) | A step's name and chosen settings edited on the node | [Edited on the node](#edited-on-the-node-0170) |
+| `setNodeValues`, `collapsible` | Values painted on the steps as often as you like; steps folded to their header | [Live values and folded steps](#live-values-and-folded-steps-0170) |
+
+A type draws its own body (`render` once, `update` on every repaint), with its
+own `size` and `accent`; `inline` draws chosen settings on the node, and
+`rank` places it when Arrange runs the layered layout:
+
+```js
+const IN = { name: 'in', direction: 'input', port_type: 'DATA', accepts: ['number'], maxConnections: 1 };
+const OUT = { name: 'out', direction: 'output', port_type: 'DATA', provides: ['number'] };
+const types = [
+    { type_id: 'source', label: 'Source', rank: 'source', inline: ['amplitude'], ports: [OUT],
+      config_schema: { type: 'object', properties: { amplitude: { type: 'number', title: 'Amplitude' } } } },
+    { type_id: 'gain', label: 'Gain', size: { w: 224, h: 132 }, accent: 'amber', ports: [IN, OUT],
+      render(body, node, ctx) {
+          const range = Object.assign(document.createElement('input'), { type: 'range', min: -2, max: 2, step: 0.1 });
+          range.addEventListener('change', () => ctx.setConfig({ k: Number(range.value) }));   // one undo entry
+          body.append(range);
+      },
+      update(body, node, ctx) { body.querySelector('input').value = node.config.k ?? 1; } },
+    { type_id: 'display', label: 'Display', rank: 'sink', ports: [IN],
+      render: (body) => body.append(document.createElement('output')),
+      update: (body, node, ctx) => { body.querySelector('output').textContent = ctx.values?.badge ?? '—'; } },
+];
+editor.setCatalogue(createStepCatalogue([...types, laterType], { categories }));   // a type added after load
+```
+
+The editor's options, each one independent of the others:
+
+```js
+const editor = createCanvasEditor(host, {
+    catalogue: createStepCatalogue(types, { categories }),
+    connections: {                                        // data ports connect, typed by accepts/provides
+        dataPorts: 'connect',
+        policy: ({ connection, graph }) => (closesLoop(graph, connection)
+            ? { ok: false, reason: 'That line would feed a block its own output.' } : null),
+    },
+    multiSelect: true,                                    // marquee, bulk move, align, distribute
+    clipboard: true,                                      // or {read(), write(text)} to hold it yourself
+    prepareCopy: (copy, { from, via }) => { copy.config.phase = 0; },
+    groups: true, notes: true,                            // Ctrl+G frames, free-text notes
+    layout: 'layered',                                    // Arrange: columns by the lines, `rank` hints
+    edgeStyle: (c, { source, target }) => ({ tone: 'teal', marker: 'arrow', width: 2,
+                                             dashed: c.targetPort === 'b', label: source.label }),
+    routing: 'obstacles', hoverHighlight: true,
+    viewport: savedView,                                  // opens there instead of fitting
+    onViewportChange: (view) => { savedView = view; },    // once per finished pan or zoom
+    zoomControls: true, minimap: true,
+    renameInPlace: true,                                  // double-click a title to rename it
+    collapsible: true,                                    // a fold button on every header
+});
+editor.load({ graph }, { viewport: savedView });
+setInterval(() => editor.setNodeValues({ mix: { badge: '0.42', tone: 'teal', ports: { out: '0.42' } } }), 250);
+```
+
+`setNodeValues` records nothing and leaves the focus where it is, so a host
+can paint as often as its values change.
+
+**Where it was checked.** `tests/flow_modeler_demo.test.mjs` mounts the demo
+under jsdom: what it shows, its live badges, and this section's list against
+the options. `tests/flow_kit_vocabulary.test.mjs` §4 holds every flow and
+canvas source the demo imports, and the demo itself, to the vocabulary gate.
+In headless Edge, `demo/flow_modeler_probe.mjs` opens the page by a real click
+on its link in `demo/index.html` and drives it with real input:
+- The bodies were drawn at their own size below their ports; every line left
+  its output dot and its arrowhead ended on its input dot, within 1px; the
+  group frame was round both sources and nothing else; a dashed line had a
+  dash pattern and a label was the element at its own centre.
+- The badges changed in each of three seconds while a settings field, focused
+  by a real click, kept the focus, and nothing was recorded.
+- A real drag from an output to an input added one line, dot to dot, as one
+  undo entry. The gesture line appears above the canvas when a drag starts and
+  moves the canvas down by its height, so the probe aims at the input where it
+  is drawn once the line has started, as a reader would.
+- A real click and Shift+click and a real Ctrl+G drew a second frame round
+  exactly the two steps; real Ctrl+C and Ctrl+V put two copies two grid steps
+  right of and below the originals, with the line between them; a real click
+  on Arrange ran every line left to right, the sources first and the displays
+  last, with no two steps overlapping. Each was one undo entry.
+- A real Ctrl+Z after each, last first, put the steps back where they were on
+  the canvas, took the copies, the second frame and the dragged line away, and
+  left the graph the text it was before each step.
+
+
 ### The outline editor
 
 `createOutlineEditor` draws a logic flow as a list of blocks: *If … otherwise*,
@@ -2834,6 +3147,52 @@ title; default "Settings"). The markup is `.twm-settings` >
 `.twm-settings__row` (`--modified`); `flexdesk.css` styles it from tokens.
 `tests/settings_view.test.mjs` covers it in jsdom.
 
+## The settings categories outside the page: `SettingsCategories` (0.17.2)
+
+A `SettingsView` made with `sidebar: false` draws no sidebar: no heading, no
+filter box, no category list and no *Reset all*, only the chosen category's
+settings (or the filter's matches). `new SettingsCategories({ view })` (in
+`@flexdesk/widgets`) draws those parts for that view wherever it is mounted,
+for example in an app's left navigator:
+
+```js
+import { SettingsView, SettingsCategories } from '@flexdesk/widgets';
+
+const view = new SettingsView({ store, eventBus: bus, sidebar: false });
+view.mount(pageHost);
+const cats = new SettingsCategories({ view });
+cats.mount(navigatorHost);
+
+const off = view.subscribe(({ category, query }) => { /* e.g. a tab title */ });
+// …
+off();
+cats.dispose();
+view.dispose();
+```
+
+It keeps no state of its own. Typing in its filter box is `view.setQuery()`,
+clicking a category is `view.selectCategory()` and its *Reset all* is
+`view.resetAll()`, which asks the view's `confirm` first and changes nothing
+unless it resolves true. It redraws from the view whenever the view's category,
+filter or registered categories change, so the two agree whichever side moved
+them: `view.selectCategory('window')` marks that category in the list, and
+`view.setQuery('shadow')` puts the text in its filter box. As in the view's own
+sidebar, choosing a category clears the filter, and no category is marked while
+the filter is in effect. Its clicks and keystrokes act once the view is mounted.
+
+Two methods on `SettingsView` serve it and anything else that follows the view:
+`subscribe(fn)` calls `fn({ category, query })` after each such change and
+answers the unsubscribe; `isFiltering()` is true while the filter's trimmed
+text is not empty. `settingsViewContent({ …, sidebar: false })` passes the
+option through. A view made without `sidebar` (or with `sidebar: true`) draws
+exactly as in 0.17.1.
+
+The markup is `.twm-settings-categories` > `.twm-settings__search`,
+`.twm-settings__nav` (`button.twm-settings__cat`, `--active`) and
+`.twm-settings__reset-all`, the same parts and classes as the sidebar's;
+`flexdesk.css` styles it, leaving its width and padding to the host.
+`tests/settings_view.test.mjs` §11–§14 cover it.
+
 ## A step wizard: `Wizard` (0.17.0)
 
 `new Wizard({ steps, data, onFinish, onCancel, labels })` (in `@flexdesk/widgets`)
@@ -3229,6 +3588,25 @@ job.on('end', () => nc.update(id, { progress: 1, severity: 'success', message: '
 
 `tests/notification_progress.test.mjs` holds it in jsdom.
 
+### Toast cards are styled and clickable (0.17.2)
+
+A toast card is `.twm-notification` with `.twm-notification--<severity>`
+(`info`, `success`, `warn`, `error`, `fatal`), and the "+N more" summary is
+`.twm-notification.twm-notification--summary`. `flexdesk.css` gives the card its
+background, a left border in the severity's colour (`--color-success`,
+`--color-warning`, `--color-danger`; info keeps the blue) and the entry
+animation `twm-notification-in`, which the sheet now defines. The card sets
+`pointer-events: auto` over the root's `none`, so its buttons and its
+click-to-close work.
+
+Until 0.17.2 the card carried the bare `notification` / `notification--<severity>`
+classes, which no FlexDesk sheet styled: the card had no background and no
+border, and inherited `pointer-events: none`, so its buttons could not be
+clicked. A consumer stylesheet that targeted `.notification` should target
+`.twm-notification` instead. The live region is `.twm-notification-center__live-region`.
+`tests/notification_toast_styles.test.mjs` holds the classes, the cascade and
+the sheets.
+
 ### Alerts with history: a log, a pane, a tab host and a bell (0.14.0)
 
 A toast is the moment. The **alert log** keeps what came in until it is
@@ -4140,6 +4518,24 @@ build so that a consumer with no bundler can load the library through a plain im
 map. See `.gitignore` — it says so there too, because it is the kind of thing someone
 "tidies up" later.
 
+### The `development` condition resolves in the installed package (0.17.1)
+
+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
+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.
+
+Nothing about which file an `import` resolves to has changed: `import` is
+listed first, so an ES import still gets `dist/`, with or without the
+`development` condition.
+
+A suite (`tests/exports_packed.test.mjs`) runs `npm pack --dry-run` and fails
+if any target of any condition in the `exports` map is not in the tarball.
+
 ## Licence
 
 MIT. See [`LICENSE`](LICENSE) and [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md).

package/canvas.js

@@ -0,0 +1,18 @@
+/**
+ * @flexdesk/canvas — the canvas kernel: a pannable, zoomable surface with
+ * marquee selection, the edge router (orthogonal routing, crow's feet, a
+ * loop's return line, a layered Arrange) and a generic graph layer (nodes and
+ * their ports, connection legality with a policy hook, snapshot-free history
+ * over a closed action list).
+ *
+ * It knows nothing about what the nodes ARE. A consumer's own rules — which
+ * ports connect, what a collapsed node shows — are subclasses and policies it
+ * passes in.
+ *
+ * HAND-WRITTEN, not generated. The other barrels say "GENERATED by
+ * scripts/gen_barrels.py", and that script is not in this repository (nor is
+ * scripts/css_extract.py), so this one is kept by hand: add a module here when
+ * you add one under src/canvas/.
+ */
+
+export * from './src/canvas/index.js';

package/charts.js

@@ -0,0 +1,21 @@
+/**
+ * @flexdesk/charts — Plotly-backed charts: the wrapper, the chart types, subplot layouts,
+ * downsampling, the plot grid, the plot-config editor, and the two plot windows.
+ *
+ * Plotly is a PEER dependency — 4.4 MB this bundle deliberately does NOT
+ * contain. Call setPlotlySource() with the path to your copy.
+ *
+ * GENERATED by scripts/gen_barrels.py. Do not hand-edit.
+ *
+ * 9 modules.
+ */
+
+export * from './src/charts/chart_types.js';
+export * from './src/charts/data_series_plot_window.js';
+export * from './src/charts/downsample.js';
+export * from './src/charts/plot_config.js';
+export * from './src/charts/plot_config_editor.js';
+export * from './src/charts/plot_grid.js';
+export * from './src/charts/plot_popout_window.js';
+export * from './src/charts/plotly_wrapper.js';
+export * from './src/charts/series_transforms.js';

package/core.js

@@ -0,0 +1,14 @@
+/**
+ * @flexdesk/core — The kernel: event bus, settings, logging, state machine, state guard.
+ *
+ * GENERATED by scripts/gen_barrels.py. Do not hand-edit.
+ *
+ * 6 modules.
+ */
+
+export * from './src/core/event_bus.js';
+export * from './src/core/logging.js';
+export * from './src/core/settings.js';
+export * from './src/core/state_guard.js';
+export * from './src/core/state_guard_config.js';
+export * from './src/core/state_machine.js';

package/css/base.css

@@ -275,6 +275,28 @@
     flex-direction: column;
     gap: var(--space-lg);
 }
+/* A toast card. The root takes no pointer events (it overlays the page), so the
+ * card takes them back: without this its buttons cannot be clicked (BUG-0033). */
+.twm-notification {
+    pointer-events: auto;
+    background: #1f1f20;
+    border: 1px solid #2f2f31;
+    border-left: 4px solid #4fc1ff;
+    border-radius: var(--radius-lg);
+    padding: var(--space-lg) 14px;
+    box-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
+    animation: twm-notification-in 160ms ease-out;
+    min-width: 280px;
+    cursor: pointer;
+}
+.twm-notification--success { border-left-color: var(--color-success, #3fb950); }
+.twm-notification--warn    { border-left-color: var(--color-warning, #ff9800); }
+.twm-notification--error,
+.twm-notification--fatal   { border-left-color: var(--color-danger, #c74e4e); }
+@keyframes twm-notification-in {
+    from { opacity: 0; transform: translateY(6px); }
+    to { opacity: 1; transform: translateY(0); }
+}
 .twm-notification__header {
     display: flex;
     align-items: center;
@@ -425,7 +447,7 @@
     box-shadow: 0 12px 32px rgba(0, 0, 0, 0.45);
     display: flex;
     flex-direction: column;
-    animation: notification-in 160ms ease-out;
+    animation: twm-notification-in 160ms ease-out;
 }
 .twm-notification-history__header {
     display: flex;