@peter.prib/renderengine 0.5.0 → 0.8.0

package/README.md

@@ -29,6 +29,10 @@ open the pages directly:
 - `examples/diagram-editor.html`: the diagram editor
 - `examples/data-model.html`: the data modeller
 
+The models they open come from [modelengine](https://gitlab.com/peter.prib/modelengine), kept apart from the tools: with
+it checked out beside renderengine, the pages open on its models (File ▸ Open from ▸ modelengine lists them by domain);
+without it they start empty.
+
 All work in current Chrome, Edge, Firefox and Safari. Save writes back to the file you opened in Chrome and Edge;
 other browsers download the file instead.
 

package/REFERENCE.md

@@ -88,6 +88,7 @@ catalog `key` for you.
 | `treemap` | `treemapChart(data, opts)` | `Array<{label, value?, children?}>` (hierarchical) | squarified layout, palette by top-level branch |
 | `sunburst` | `sunburstChart(data, opts)` | same hierarchical shape as `treemap` | nested rings by depth |
 | `outline` | `outlineChart(data, opts)` | same hierarchical shape as `treemap`/`sunburst` | `onNodeClick`; collapsible indented list |
+| `table` | `tableChart(data, opts)` | `Array<object>` — a row per object, a column per key | `columns` (names or `{key, label?, align?}`), `maxRows`, `nullText` (`'—'`); values exact, numeric columns right-aligned; drawn with the renderer's primitives, so SVG or canvas |
 | `gauge-dial` | `dialGauge(value, opts)` | `number`, `{value, target?}`, or `[{value, label?, color?}]` for a needle each (0–100 unless `min`/`max`) | the gauge options below; `cx`, `cy`, `r`, `thickness`, `startAngle`, `sweep`, `needleColors`; several needles get a legend, the first fills the arc |
 | `gauge-bar` | `barGauge(value, opts)` | `number` or `{value, target?}` (0–100 unless `min`/`max`) | the gauge options below; `x`, `y`, `width`, `height`, `orientation: 'vertical'` |
 | `gauge-arc` | `arcGauge(value, opts)` | `number` or `{value, target?}` | the gauge options below; `cx`, `cy`, `r`, `thickness`, `startAngle`, `sweep` (a half circle by default), `cap` |
@@ -812,6 +813,22 @@ types — see `ARCHITECTURE.md`):
   is not there. Model ▸ **Check model…** lists the findings in the `ModelCheckDialog` the diagram editors' check uses;
   choosing one shows it (the entity's level, the service domain seen through, the mapping view).
 
+  **Likely duplicate entities.** **Find likely duplicates…** (Model ▸, Tools ▸ and the model's tab; the part's
+  `modelMenuItems()`) asks for a level (the one in front first) and how to compare, with the form the ArchiMate
+  modeller uses (`duplicateSearchFields`): names, definitions or attributes (their names together), exactly or by their
+  words, and the noise to leave out. The groups found are listed as the ArchiMate modeller lists them
+  (`DuplicatesDialog`, below), and merging shows the entities side by side first (`model.entityComparison(level, ids)`:
+  name, definition, each attribute, relationships, what each is mapped to; `MergeCompareDialog`): choose the entity
+  kept and, when their definitions differ, which (or all joined); entities alike merge without asking. The kept one takes the
+  attributes it lacks (by name, any case), their relationships (one left joining it to itself, or doubling one there,
+  goes) and their mapping pairs; the others go, perspectives and contexts forgetting them, one undo step
+  (`model.duplicateEntities(level, options)`, `model.mergeEntitiesCommand(level, keepId, otherIds, { description })`).
+
+  ```js
+  model.duplicateEntities('logical', { by: 'attributes' });   // [{ code: 'possible-duplicate', level, ids, message }]
+  part.runModelEdit(model.mergeEntitiesCommand('logical', 'customer', ['client']));
+  ```
+
   **Checked as DMBOK2 reviews a model.** The check also finds, at the logical and physical levels: an entity with
   attributes and no primary key (`no-primary-key`); a foreign key whose `references` (an entity, or `entity.attribute`,
   by id or name) is not there (`reference-missing`) or has no relationship with its entity either way
@@ -949,8 +966,9 @@ types — see `ARCHITECTURE.md`):
   service domains.
   `model.serviceDomainsCommand(specs, source)` brings them in as one undo step: a new one is added; one already
   there (by id, else by name) keeps its control record, qualifiers and the rest, taking its area and domain from
-  the landscape, and its asset and pattern where it has none. `examples/bian-landscape-sample.xml` is a small
-  excerpt in that shape to try it with (not BIAN's landscape, which is BIAN's to publish).
+  the landscape, and its asset and pattern where it has none. modelengine's banking domain has a small excerpt in
+  that shape to try it with (`test/fixtures/bian-landscape-sample.xml` here; not BIAN's landscape, which is BIAN's to
+  publish).
 
   ```javascript
   const specs = new BianLandscapeReader().read(BianLandscapeReader.parse(xml));
@@ -1045,7 +1063,8 @@ types — see `ARCHITECTURE.md`):
   and Redo; Tools ▸ Compare with and Merge from (the other open models and the bases; a merge is one undo step); Model ▸ New / Edit / Delete perspective and context (those dialogs), Perspective and Context selects (when
   it has some; a perspective brings its context, and the context's scope shows beside them), Level (Conceptual,
   Logical, Physical, and Mapping), Notation, and Export ▸ PNG / SVG. A box or note dragged stays on the level it
-  was dragged on (the mapping view's in its own layout). `examples/data-model.html` (`npm run datamodel`) uses every
+  was dragged on (the mapping view's in its own layout). modelengine's enterprise ontology, which
+  `examples/data-model.html` (`npm run datamodel`) opens when modelengine is checked out beside renderengine, uses every
   feature above. A data model can also be registered like a chart:
   `engine.register(id, 'dataModel', { entities, relationships, level })` then `engine.refreshChart(id)` (each
   diagram catalog entry names its data options, `args`).
@@ -1062,6 +1081,50 @@ this to `line`/`area`/`stackedBar`/etc. is the same three-line change: call
 `this._drawYAxisTicks(x, y, width, height, rawMax)` before drawing marks, and scale against its
 return value instead of the raw max — not done yet for the rest, tracked as a follow-up.
 
+### Choosing a chart for result rows — `ChartChooser`
+
+`new ChartChooser().choose(rows, columns?, { complete? })` says which chart types fit a set of result rows (a query
+answer, a CSV), best first, each with the rows already shaped as that type's `dataShape` — so
+drawing the best one is `engine.renderChartType(best.key, best.data)`. A `table` always fits and is
+always offered, last.
+
+```javascript
+import { RenderEngine, ChartChooser } from '@peter.prib/renderengine';
+
+const rows = [{ Region: 'West', Revenue: 200 }, { Region: 'East', Revenue: 405 }];
+const choices = new ChartChooser().choose(rows, [{ name: 'Region' }, { name: 'Revenue', measure: 'additive' }]);
+// → bar, pie, donut, table — each { key, label, data, reason }
+const [best] = choices;
+new RenderEngine(container).renderChartType(best.key, best.data, { title: best.reason });
+```
+
+`columns` are optional hints, `{ name, kind?, measure? }`: `kind` is `'categorical'`, `'numeric'`
+or `'time'` (without a hint, a column whose values are all numbers is numeric, else categorical);
+`measure` is the data model's measure kind (`'additive'`, `'semi-additive'`, `'non-additive'`).
+`complete: false` says the rows are only part of the answer (a top N, a first page).
+
+| Rows look like | Offered, best first |
+|---|---|
+| one number, one row | `kpi-tile` |
+| one category, one number | `bar`; also `pie`, `donut` when the measure is additive, the rows are complete, no value is negative and there are 2–8 categories |
+| one time column, one number | `line`, `area`, `bar` — in time order |
+| one category, several numbers | `groupedBar`, `line` (a series per number); with time, `line` first |
+| two categories, one number | `groupedBar`, `heatmap`; with a time column, `line` (a line per category) first |
+| anything else | `table` only |
+
+Three rules keep a choice from misleading: only an **additive** measure is offered as shares of a
+whole (a slice of an average or a balance means nothing); only **complete** rows are (three
+customers' slices of a top 3 would claim to be the whole); and a **missing value is never drawn as
+0** — a result with a hole in a series is not offered as series charts (the heatmap, which draws
+only the cells present, still is), and a bar chart simply has no bar for a null.
+
+A table has no axes, so it takes none of a chart's axis margins. `TableChart.heightFor(rowCount,
+{ title?, maxRows? })` is the height it will draw, for sizing its container first.
+
+Every suggestion is checked against the registry the chooser is given (`chartRegistry` by default):
+a type is offered only if the catalog has it and every axis it marks `required` is one the result's
+shape provides, so the catalog stays the single source of truth for what each chart needs.
+
 ## Common options
 
 Not every method takes every option below — the table above calls out what's notable per type —
@@ -1077,6 +1140,13 @@ but these recur across most 2D chart types:
 }
 ```
 
+- **Legend placement** (`Legend.beside`, every chart with a legend): to the right of the plot when there is
+  room in the drawing; otherwise, since the plot usually fills it, inside the plot's top-right corner on a
+  light backing. A chart of points (scatter, bubble) marks its entries with circles, the others with squares.
+- **Category labels** (line, area, bar, stacked bar, candlestick, waterfall, streamgraph): as many as fit.
+  When they would overprint, every n-th is drawn, n from the longest label and the plot width
+  (`Axis.categoryLabelStep(labels, width, { fontSize })`).
+
 Data-resolution options (used with `register()`/`refreshChart()`, see below):
 
 ```javascript
@@ -1112,6 +1182,8 @@ engine.setGlobalData(data)              // set a global object referenceable by
 engine.resolvePath(path, mapper?)       // e.g. resolvePath('metrics.sales.0.value')
 engine.register(id, type, options)      // remember a {type, options} pair for a container id
 engine.refreshChart(id)                 // re-invoke it — resolves options.data or dataPath+dataMapper fresh each time
+engine.refreshAll()                     // every registered chart
+engine.setData(data)                    // setGlobalData(data), then refreshAll(): a live page's poll
 engine.niceTicks(maxVal, count=4)       // readable axis tick values
 engine.formatValue(v)                   // 1234567 -> "1.23M"
 engine.bindTooltip(element, text)
@@ -1120,7 +1192,24 @@ engine.adjustColor(hex, amount)         // lighten/darken, used internally for 3
 ```
 
 `register`/`refreshChart` is the registration mechanism `addDataPoint`/`addGraphNode` (next section)
-build on.
+build on. **One engine keeps a page of charts:** each registered id is drawn in the element with that id, by
+the engine itself when it is its own container, otherwise by an engine of its own for that element, made with
+this engine's options and kept while the element is the same, so a zoom survives the next refresh. A chart
+whose `dataPath` resolves to nothing yet is not drawn.
+
+```javascript
+const charts = new RenderEngine(null, { rendererType: 'svg', zoom: { wheelModifier: 'ctrl' } });
+charts.register('cpu-gauge', 'gauge-dial', { dataPath: 'cpuPercent' });
+charts.register('perf-chart', 'line', {
+    dataPath: 'history',
+    dataMapper: (h) => [{ name: 'CPU', values: h.map(x => ({ label: x.t, value: x.cpu })) }],
+});
+setInterval(async () => charts.setData(await (await fetch('/api/metrics')).json()), 2000);
+```
+
+**Zoom.** An SVG chart zooms with the mouse wheel. The engine option `zoom: { wheelModifier: 'ctrl' }`
+(or `'alt'`, `'shift'`; `ctrl` also takes ⌘) zooms only with that key held, so a plain wheel scrolls a page of
+charts; `zoom: false` turns it off.
 
 ## Interactivity
 
@@ -1359,6 +1448,24 @@ do, and a folder of one type in the Layers tree too (`typeGlyph(typeName, { size
 `archimate/typeGlyph.js`, the one drawing both use; a 3.2 type under ArchiMate 4 is drawn as 3.2 draws it).
 `TreeBuilder`'s `iconFor(node)` gives a node a picture in place of its `icon` text.
 
+**Tree rows and long folders.** A tree row is one compact line: a label too long for the panel ends in an ellipsis,
+with the whole of it as the row's tooltip. A folder shows its first `leafLimit` leaves (8 in the model tree,
+`ModelTree.LEAF_LIMIT`, set per tree by `new ModelTree(model, { leafLimit })` or `setOptions({ leafLimit })`), then
+a "▸ N more" row that shows the rest; the folders inside it always show. A folder asked for more keeps showing all
+when the tree is redrawn (`TreeBuilder`'s `shownAll`, a Set of node ids the caller keeps, as it keeps `openState`).
+`TreeBuilder`'s `filter(node)` says which leaves to show: a folder shows when a leaf under it does, and opens while
+filtering (without changing what `openState` remembers); one with nothing kept inside is left out, whatever its own
+name.
+
+```js
+const tree = new TreeBuilder(document, {
+    container, rootNodes, getNodeChildren: (node) => node.kids ?? [],
+    leafLimit: 8, shownAll: new Set(),
+    filter: (node) => node.label.toLowerCase().includes('order'),   // null: every node
+});
+tree.render();
+```
+
 **Nesting.** In the ArchiMate canvas editor, dropping a box wholly inside an element's box nests it there (Archi's
 nested elements); so does dropping an element with its centre on another element's box when a relationship a
 nesting stands for is allowed between them (`nestsOnDrop`), and the parent then grows to show it whole, with its
@@ -1441,9 +1548,15 @@ there (`editor.addImage(dataURL, point)`, one undo step, selected; the base edit
 relationships) under the palette, for an element chosen on the canvas or in the tree. The tree's own filters (its
 "Filters…" dialog: text, types, specializations, properties) dim what they leave out on the canvas too:
 `modelTree.matchingElementIds()` (null with no filter on) and `modelTree.onFilterChange(fn)` feed
-`editor.setElementFilter`. Under the search box, **In:** chooses what the search covers, the whole model or only
+`editor.setElementFilter`. The search text filters from 3 characters on (`ModelTree.MIN_FILTER_CHARS`; per tree,
+`minFilterChars` or `setOptions({ minFilterChars })`); shorter, nothing is filtered (`modelTree.filterText` is the
+text in effect, `getFilterText()` the text typed). While it filters, the box is marked (`data-filtering`, a blue
+border) and a line under it says what was found ("Filtering: 3 elements, 1 view found"); with fewer characters it
+says how many more to type. It finds views, templates and folders by name as well as
+elements, and leaves out the folders with nothing found in them (`modelTree.textMatches(name, documentation)`; type,
+specialization and property filters are the elements' only). Under the search box, **In:** chooses what the search covers, the whole model or only
 the diagram in front (`modelTree.setSearchScope('model' | 'view')`, `ModelTree.SEARCH_SCOPES`), and
-**Descriptions** looks for the text in elements' and relationships' documentation too
+**Descriptions** looks for the text in elements', relationships' and views' documentation too
 (`modelTree.setSearchInDescriptions(true)`). The Filters… dialog opens showing the filters on now
 (`getTypeFilter()`, `getSpecializationFilter()`, `getPropertyFilter()`). Its properties start unticked (no property
 filter; `OptInCheckboxTreeSelector`: a value is ticked to keep what has it), and a property with more than 10
@@ -1470,7 +1583,11 @@ leaves it alone). Any `Edge` can say so (`editable`, default true) and add to it
 
 **Selecting several shapes.** In the base editor (so the template editor and the ArchiMate canvas alike): drag a
 box on empty canvas to select the shapes wholly inside it (Ctrl or Cmd adds them to the selection;
-`editor.templatesInside(rect)`, `editor.selectTemplates(ids, { extend })`); Shift- or Ctrl-click adds one;
+`editor.templatesInside(rect)`, `editor.selectTemplates(ids, { extend })`); Shift- or Ctrl-click adds one, and so
+does a right-click with Shift or Ctrl, before the menu opens for the whole selection; a plain right-click on a shape
+outside the selection selects it alone (`editor.selectForMenu(id, { extend })`). The last shape chosen has the
+handles; every other selected shape is marked by a dashed, tinted outline set off its border
+(`DiagramEditor.SELECTION_OUTLINE`: `pad`, `stroke`, `strokeWidth`, `dash`, `fill`);
 **Ctrl+A** selects every shape that is drawn (`selectableIds()`). Whatever is selected acts together, each as one
 undo step: dragging any of them moves them all (with their groups and what they hold); the arrow keys nudge
 them a grid step, one pixel without a grid, ten times as far with Shift (`nudgeSelection(dx, dy)`); **Delete**
@@ -1634,6 +1751,28 @@ whose schema changed) gives them afresh with `models.setBases(specs)`; what is o
 (`models.viewBase(i)`) opens a base to look at: a tab of its own copy, named "… (view)", that can be laid out and
 moved about but is never kept (`part.keepOff`).
 
+**Content: models kept apart from the tools.** Models, data models and user stories by domain live apart from the
+modellers (modelengine, or any collection laid out like it): a `manifest.json` listing items by domain, each a file in
+a format a modeller already reads. A `ContentSource` reads one, fetched from its address (`url`: a folder holding
+`manifest.json`, or the manifest itself) or given whole (`bundle`: `{ manifest, files }`, what modelengine's
+`dist/modelengine.js` puts on `globalThis.ModelEngineContent` for a page opened off disk; `ContentSource.fromPage()`).
+Nothing in the tools lists what a collection has: `source.items({ formats })` offers the items a modeller's file
+formats read, each matched by its file's whole ending (`ContentSource.formatFor(item, formats)`: the one format
+accepting all after the name's first dot, so `.requirements.json` is not any `.json`), and `source.open(item,
+formats)` opens one through that format. A `ModelsPart` offers its sources (`ContentSources`: the page's bundle, its
+spec's `content: [{ label?, url }]`, the host's `contentSources` service, and those added with **Add a source…**,
+kept in this browser) under File ▸ **Open from** ▸ *source* ▸ *domain* ▸ *item* (`models.contentItems()`); a source
+not read says why there. An item opens in a tab of its own (`models.openContent(source, item)`) remembering where it
+came from (`part.contentOrigin`), so its tab menu and Tools offer **Update from *source*…**: the item read again and
+its changes reviewed as a merge, one undo step, keeping what was changed here (`models.updateFromContent(part)`).
+`openContent: 'first'` (or an item's id) in the spec opens that item on a first visit, in the empty model's place.
+
+```js
+const source = new ContentSource({ url: 'https://example.org/modelengine/' });
+const [item] = await source.items({ formats: [new DataModelFileFormat()] });   // what the data modeller reads
+const { model } = await source.open(item, [new DataModelFileFormat()]);
+```
+
 **Kept in this browser, and backed up.** With `keep: true` in its spec, a `ModelsPart` keeps every model it holds
 in this browser, so work outlives the page without saving a file: a moment after each edit (`ModelsPart.KEEP_DELAY`)
 and at once when imported, each in its editor's own file format (`part.keepEntry()`: the file's format, else the
@@ -1840,20 +1979,56 @@ template editor (the testbed) and both ArchiMate editors have them. The **View**
 (`editor.viewMenuItems()`) has **Zoom to fit** (`editor.zoomToFit()`: everything drawn in sight, in the
 drawing's own units; `ViewFit` computes it, as a viewBox for the graph engine or a scale and pan for the
 template editor), **Reset zoom**, **Highlight…** (below), and, when the editor has a `model`, **Check model…**
-(`editor.showModelCheck()`). The checks are the model's own (`model.checker(options)`): a `ViewSetChecker` for
+(`editor.showModelCheck()`; `showFindings(findings, { title, empty })` shows any findings in its dialog). The checks are the model's own (`model.checker(options)`): a `ViewSetChecker` for
 any view set (empty views; an empty template is not one), and for an ArchiMate model an `ArchimateModelChecker`
 that adds relationships the specification does not allow, likely duplicates (elements of one type whose names
-have the same words, ignoring case, punctuation, word order and filler words such as "of" and "the":
+have the same words, ignoring case, punctuation, word order, plurals ("Customers" is "Customer", `singular(word)`)
+and filler words such as "of" and "the":
 `nameKey(name)` and `duplicateGroups(elements)` in `diagrams/duplicates.js`), elements and relationships on no
 view, nested elements with no relationship, and names or documentation with unprintable characters (control
 characters, zero-width spaces; tabs and line breaks are fine in documentation). Each check is a method listed by
 `checks()`, so a subclass changes the set; choosing a finding shows it (`editor.revealFinding(finding)`: its view,
 its shape, or in the ArchiMate tree), and a finding can offer actions beside it (`editor.findingActions(finding)`).
-On the ArchiMate canvas, likely duplicates have **Merge…**: choose the element to keep (each choice says how many
-views and relationships use it) and the others are merged into it, one undo step (`model.mergeCommand(keepId,
-otherIds)`, a `MergeElementsCommand`). The kept element takes their relationships, their boxes on every view, the
-documentation and properties it lacks and a specialization if it has none; a relationship left joining it to
-itself, or the same as another, goes, its lines drawn as the other. The **File** menu (`EditorPart`'s, and the ArchiMate editor's) exports the current view
+On the ArchiMate canvas, likely duplicates have **Merge…**, and **Find likely duplicates…**, a tool for the whole
+model, is on the model's tab menu and in **Tools** (a part's `modelMenuItems()`, the editor's for an `EditorPart`;
+in its **Edit** menu when no `ModelsPart` hosts it). It asks where to look (the whole model, this view, the elements
+selected: `editor.duplicateScopes()`) and how to compare, then lists the groups found (a `DuplicatesDialog`, one for
+every modeller): each with a box to tick, its message (choosing it shows it) and **Merge…**; **Merge selected** merges
+the ticked groups one after another. The list stays open while they are merged, found again after each merge, so what
+was merged leaves it (`editor.askDuplicates()`, `editor.showDuplicates(options, { within })`, `checker.possibleDuplicates(options, { within })`).
+Its form is one for every modeller (`duplicateSearchFields({ scope, compare, properties, specializations })`,
+`duplicateSearchOptions(values)`, `validateDuplicateSearch`). The options are the jArchi dedupe scripts' (`DUPLICATE_OPTIONS`,
+`duplicateGroups(elements, options)`, `duplicateKey(element, options)`, `wordKey(text, options)`): compare the
+names, the documentation (an element with none, or only noise, is left out) or a property's value (an application
+id); leave out noise words (`NOISE_WORDS`: filler, "tbc", "tba" …), numbers and version numbers ("2", "v2",
+"1.2.3"), one-letter words and words matching a pattern (`^[Aa][0-9A-Fa-f]{5}$` for id codes); take a plural as its
+word; look across types; leave out a specialization (Decommissioned). **Match** `exact` compares the text as it is,
+case and spacing aside; `words` (the default) by its words, as above. Any other field can be compared by naming it
+(`by: 'attributes'`; a list is its items' names together). The model check compares names by their words with the
+filler words only.
+
+```js
+editor.showDuplicates({ by: 'documentation', noiseWords: NOISE_WORDS, ignoreNumbers: true });
+editor.showDuplicates({ by: 'property', property: 'AppId', acrossTypes: true });
+```
+
+With two or more elements selected, a shape's menu has **Merge N elements…** for them
+(`editor.elementIdsOf(boxIds)`: each box's element, once). Merging (`editor.askMerge(ids)`, resolving to the command
+or null) shows the elements side by side first (a `MergeCompareDialog`, one for every modeller: a column each, a row
+each for name, type, specialization, documentation, each property, relationships and views, the rows where they
+differ marked ≠; `editor.mergeComparison(elements)`), and under it asks which element to keep (each choice says how
+many views and relationships use it) and, where they differ, what it ends with: the documentation (all of it joined,
+the default, or one element's), the value of each property they have with different values, the specialization
+(`editor.mergeChoices(elements)`). **OK, merge** merges; Cancel leaves them. Elements that differ only in the views
+they are on merge into the first without asking. The others are merged into it, one undo step (`model.mergeCommand(keepId,
+otherIds, { documentation, properties, specialization })`, a `MergeElementsCommand`). The kept element always takes
+their relationships and their boxes on every view, and the properties it lacks; a relationship left joining it to
+itself, or the same as another, goes, its lines drawn as the other.
+
+**View ▸ Remove repeated boxes (N)** takes off the view each box that only repeats another of its element: the same
+label shown, in the same box (or none), with the same lines drawn (each relationship, or connection, to the same
+thing at the other end), as one undo step with its lines (`view.repeatedBoxes()`, `editor.removeRepeatedBoxes()`).
+The first box stays; a box holding others is never taken off. The **File** menu (`EditorPart`'s, and the ArchiMate editor's) exports the current view
 as an image: PNG, SVG or a copy to the clipboard (`editor.exportImage('png' | 'svg' | 'copy')`, without the grid
 or selection; the ArchiMate editor's is off with `features.exportImage: false`). **Generate View For This**, on
 an element's menu in the diagram or the tree, makes a view of the element with everything related to it
@@ -1894,7 +2069,8 @@ changed: `editor.model.duplicateView(id)` opens and shows the copy, deleting a v
 
 **Canvases and templates.** As in Archi, the model tree's **Views** holds every view, canvases (`CanvasView`)
 and sketches included, in the sub-folders the Archi file kept it in (`view.archiFolder`; `viewFolderNodes(views,
-depth)` makes a level of them); templates are apart (`model.diagramViews()`, `model.canvases()`,
+depth, emptyFolders)` makes a level of them). A sub-folder with no view in it is kept too, as its path
+(`model.emptyViewFolders`, read from an Archi or Exchange Format file and written back to either); templates are apart (`model.diagramViews()`, `model.canvases()`,
 `model.templates()`). The **Templates** folder holds the model's own templates (canvases
 marked `template`, saved in the `.archimate` file) and a **Library** of templates kept across models: a
 `CanvasTemplateLibrary` (a `TemplateLibrary`, the base any kind of view's library extends: entries, built-ins
@@ -2307,7 +2483,7 @@ for something else in ArchiMate, each as one undo step:
 
 `ArchimatePalette({version, onPick, document})` renders the element types grouped by layer
 (`ArchimatePalette.groups(version)`: the notation's layers, then ArchiMate 4's common behaviour types),
-each tile only its notation glyph in its layer colour, four to a row (`ArchimatePalette.TILE`; the name shows on hover); drag a tile onto the canvas or click it (`onPick`).
+each tile only its notation glyph in its layer colour, six to a row at 12px (`ArchimatePalette.TILE`; the name shows on hover); drag a tile onto the canvas or click it (`onPick`).
 
 `ArchimateCanvasPart` (workspace bundle, type `archimate-canvas`; `examples/archimate.html`, and the testbed
 `test/archimate-canvas-testbed.html`) is the
@@ -2421,7 +2597,11 @@ model's, then the tool's, then the default (`cascade(view, modelId)`; `getModelO
 what the model level itself sets, `getModelSettings(modelId)` the model's resolved values). Global
 Settings sets the tool's value and the model's (which may inherit the tool's); a view's Properties sets
 the diagram's (which may inherit the model's). "Invalid relationships" (`invalidRelationships`:
-`highlight`, `tooltip`, `off`) is set this way.
+`highlight`, `tooltip`, `off`) is set this way. Global Settings also sets how the model tree searches and shows, for
+every model (tool level, `TREE_SETTINGS_PROPERTIES`): the leaves a folder shows before "more" (`treeLeafLimit`, 8)
+and the characters a search needs (`treeSearchMinChars`, 3). `settingsManager.treeOptions()` gives them as
+ModelTree's options (`{ leafLimit, minFilterChars }`); the canvas part makes its tree with them and redraws it when
+they change.
 
 ```js
 settingsManager.saveToolSettings({ invalidRelationships: 'tooltip' });   // every model, unless it says otherwise
@@ -2670,6 +2850,11 @@ diagram). After an item acts, the bar re-renders. Items with live labels (the zo
 | `ToolbarText(text, style)` | Live text |
 | `ToolbarSeparator()` | Divider |
 
+`PopupMenu.show(x, y, items)` is the one popup or context menu (a toolbar menu's, an editor's, a host's
+right-click): items `{ label, action, danger?, checked?, disabled? }`, `{ label, items }` for a submenu, or
+`{ separator: true }`. One is open at a time; it moves back inside the window near an edge, and closes on a
+choice, a click elsewhere, Escape, or a scroll.
+
 ```javascript
 new MenuBar({ container, editor, items: [
     new ToolbarMenu('File', [{ label: 'Export', action: exportIt }]),
@@ -2677,6 +2862,19 @@ new MenuBar({ container, editor, items: [
 ] }).render();
 ```
 
+`Dialog` is the one dialog frame, which `FormDialog` (a `<form>`) and any host's own dialog share: a title
+(drag it to move the dialog), an optional ✕ (`closeButton`), a body that scrolls between the title and the
+buttons, which stay in view, and Escape or a click outside to close. `buttons` are
+`[{ label, action(dialog), primary? }]`, `size` is `'tall'` or `'wide'`, and `onClose(applied)` is told once.
+`open()` shows it over the page; `open(host)` places it in `host` with no backdrop and no ✕, to show a dialog's
+content as a pane or a tab. A subclass gives its content as `content()` specs; a host fills `dialog.body` after
+`open()`, and adds to `dialog.titleBar` (a link) or `dialog.footer` (a pager).
+
+```javascript
+const rows = new Dialog({ title: 'orders', closeButton: true, size: 'tall' }).open();
+rows.body.append(table);
+```
+
 `FormDialog` is the one modal form: `fields` of type `text`, `textarea`, `number`, `color`, `select`
 or `checkbox`. A field with `inherit: { text, short? }` may be left unset; it then reads as `undefined` (a select
 offers `text` as its first choice; any other field, a checkbox too, gets a checkbox named `short`, default
@@ -2747,6 +2945,88 @@ to it) / `deleteEdgeCommand(id)`. A subclass whose shapes and lines stand for so
 overrides those factories (ArchimateCanvasEditor does). A template class says whether the editor
 offers it a rotate handle (`static rotatable`, true by default; ArchiMate's templates are not). `pickFile(accept)` resolves with the chosen `File` (or `null`).
 
+## Navigation menus
+
+`NavMenu` is a vertical navigation menu (a sidebar's), written as data: no markup. Each entry is
+one of three kinds, built from its JSON by `NavMenu.entry`:
+
+| JSON | Class | Renders |
+|---|---|---|
+| `{ label, id?, icon?, href?, action?, selectable?, title?, cls?, visible? }` | `NavItem` | A link (`<a href>`) with `href`, otherwise a button |
+| `{ group, items, id?, open?, title?, cls?, visible? }` | `NavGroup` | A heading that opens and closes (`<details>`) over its items |
+| `{ section, title?, cls?, visible? }` | `NavSection` | A heading between entries |
+
+```javascript
+import { NavMenu } from '@peter.prib/renderengine';
+
+const menu = new NavMenu({
+    label: 'Workbench',
+    context: { role: 'analyst' },
+    open: { devtools: true },
+    items: [
+        { section: 'Notebooks' },
+        { id: 'new-nb', label: '+ New Notebook', action: newNotebook, selectable: false },
+        { group: 'Dev Tools', id: 'devtools', items: [
+            { id: 'datamodel', icon: '◫', label: 'Data Model', href: '#', action: (event) => {
+                event.preventDefault();
+                openTool('datamodel', { beside: event.altKey });
+            } },
+        ] },
+        { id: 'admin', icon: '⚙', label: 'Admin', href: '/admin', visible: (ctx) => ctx.role === 'admin' },
+    ],
+    onToggle: (groupId, open) => save(menu.serialize()),
+}).render(document.getElementById('nav'));
+```
+
+- **A click** runs the item's `action(event, item, menu)`, then makes the item the active one (unless it
+  has no `id`, or `selectable: false`), then calls `onSelect(item, event)`. A link still navigates unless
+  the action calls `event.preventDefault()`.
+  `href` may be a function of the context, for an address known only later (`setContext({ adminUrl })`). The active item has the class `ws-nav-item-active` and
+  `aria-current="page"`; `setActive(id)` moves it in place (`null`: none).
+- **`visible`** is a boolean or a function of the menu's `context`. A group none of whose items shows is
+  hidden too. `setContext({ role })` merges into the context and re-renders.
+- **State:** `serialize()` returns `{ activeId, open: { groupId: boolean } }` (groups with an `id`), and
+  the constructor takes `activeId` and `open` back; `onToggle(groupId, open)` reports a group opened or
+  closed.
+- `find(id)` returns an entry anywhere in the menu; `all()` lists them depth first.
+- **Styles** are the workspace's (`ensureStyles`): `ws-nav`, `ws-nav-item`, `ws-nav-icon`, `ws-nav-label`,
+  `ws-nav-group`, `ws-nav-group-summary`, `ws-nav-section`. Colours are inherited, so the menu suits a
+  dark sidebar and a light one; `cls` adds a host's own classes to an entry.
+
+`NavMenu` imports nothing from the browser at module scope, so it is exported from the node entry
+(`src/index.js`) as well as the workspace bundle.
+
+## Icons
+
+`IconSet` holds named icons as data, and builds each as an `<svg>` spec for `el()`, so nothing is parsed. An
+icon is JSON: a `viewBox`, its `paint`, and its shapes as `[tag, attrs]` pairs.
+
+```javascript
+import { ICONS, icon, IconSet } from '@peter.prib/renderengine';
+
+el(icon('cpu'));                                     // the built-in pool
+el(ICONS.spec('database', { size: 16, title: 'Catalog' }));
+const mine = ICONS.with({                            // a host's own icons over the built-in ones
+    ring: { viewBox: '0 0 24 24', shapes: [['circle', { cx: 12, cy: 12, r: 10 }]] },
+});
+```
+
+- **`paint`:** `'stroke'` (the default) outlines the shapes in `currentColor`, so an icon takes its parent's
+  colour. `'fill'` fills them in `currentColor`. `'none'` leaves the colours the shapes carry, as a brand mark does.
+- **`spec(name, { size = 24, title, cls })`:** returns an `<svg class="re-icon" data-icon="name">` spec. Without
+  a `title` it is `aria-hidden`; with one it is `role="img"` and carries a `<title>`. An unknown name throws.
+- **Methods:** `define(name, icon)` checks the icon as it is added; `add(defs)`, `has(name)`, `get(name)` and
+  `names()` work on the set; `with(defs)` returns a copy with `defs` added, leaving the original unchanged.
+- **The built-in icons** (`ICONS`, defined by `ICON_DEFS`): `dashboard`, `zap`, `clock`, `clipboard-list`,
+  `book`, `cpu`, `memory`, `activity`, `database`, and the brand marks `google` and `microsoft`. They are named
+  for the picture, not for where they are used.
+- **In a `NavMenu`:** an item's `icon` that names an icon in the menu's `icons` (default `ICONS`) is drawn as
+  that icon; any other text, such as an emoji, is shown as it is.
+
+`el()` builds an `svg` spec, and everything inside it, in the SVG namespace (`SVG_NS`, exported with `el` from
+the workspace bundle), until a `foreignObject`, whose children are HTML again. A spec's `ns` sets the namespace
+explicitly.
+
 ## Where to go next
 
 - **`ARCHITECTURE.md`** — module layout, the chart-type catalog mechanics, how to add a new chart type.