@peter.prib/renderengine 0.2.4 → 0.2.6

package/README.md

@@ -1,213 +1,215 @@
-# RenderEngine
-
-**An ArchiMate modeller, a diagram editor and a chart library that run in any browser tab, with no install and no
-runtime dependencies.**
-
-Open an Archi model, edit it the way you would in Archi, and save it back to the same `.archimate` file, without
-installing anything. Or put the same editor in your own app: it's a JavaScript library and a set of workbench parts,
-not a desktop application.
-
-![The ArchiMate modeller: a layered view of an online shop, the model tree by layer with each type's picture, and the palette](https://gitlab.com/peter.prib/renderengine/-/raw/master/docs/images/archimate-modeller.png)
-
----
-
-## Try it
-
-```bash
-git clone https://gitlab.com/peter.prib/renderengine.git
-cd renderengine
-npm start          # the ArchiMate modeller
-npm run diagram    # the diagram editor (flowcharts, UML and more)
-```
-
-No server is needed, and nothing needs installing first, because the built bundles are in `dist/`. You can also
-open the pages directly:
-
-- `examples/archimate.html`: the ArchiMate modeller
-- `examples/diagram-editor.html`: the diagram editor
-
-Both 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.
-
----
-
-## The ArchiMate modeller
-
-### Works with Archi
-
-- **Open and save Archi files** (`.archimate`, and archives that include pictures). Save writes back to the file you
-  opened; Save As picks a new one. Unsaved changes are marked (•), and the page asks before you leave or close them.
-- **Import a spreadsheet** into the open model: choose the name, type, id, documentation, property and "related
-  to" columns; existing elements are updated, not duplicated (Archi's elements.csv imports as it is).
-- **draw.io export**: every view a page, in draw.io's ArchiMate shapes, with the elements' properties.
-- **Open Group Exchange Format** import and export, the standard way into Sparx, BiZZdesign and other tools.
-  Checked with Archi 5.8, which validates and opens the files.
-- **Every element Archi receives is a valid ArchiMate 3.2 class.** A type Archi lacks is written as its nearest
-  3.2 type, and its own type is kept so it comes back on the next import.
-- **Canvases, sketches, notes, groups and Archi's canvas templates** come through import and export.
-
-### Modelling
-
-- A **palette** of every element type, grouped by layer and limited by the view's viewpoint.
-- **Connecting two elements offers only the relationship kinds the ArchiMate rules allow** between them.
-- **Nesting**: drop an element inside another and choose what the nesting stands for (composition, aggregation,
-  assignment, realization or specialization). It goes into the model, and the nesting shows it.
-- **Add from text**: paste a list of names, from a document or a spreadsheet's columns, and get an element for
-  each.
-- **Copy and paste** within a model and between models, **Duplicate**, and **Generate View For** an element and
-  what it relates to.
-- **Several models open at once**, a tab each. Each has its own file and its own undo history.
-- **Undo for everything**, one history per model as in Archi: edits on any view, and adding, renaming and deleting
-  views. Undoing an edit made on another view takes you to that view.
-- **Specializations**, custom viewpoints, label expressions (`${name}` and `{name}`), and properties with types.
-
-### Editing
-
-- **Align, distribute and match size**, to the shape you selected last, as in Archi; **automatic layouts** (grid,
-  circle, tree, force-directed, by layer) and **Nest its parts inside**, following composition and aggregation.
-- **Properties of several shapes at once**: colours and text style, the elements' type and specialization, and a
-  property to set on all of them.
-- **Format painter**: copy one shape's look onto others.
-- **Colour by** layer, type, specialization or any property (a heat map, e.g. by lifecycle: invest, maintain,
-  retire), with a legend; or a legend of the element types on the view.
-- **Find and replace** across names, documentation and property values, with match case, whole words and
-  regular expressions; **transform names** (Title Case, split camelCase, ...) and **rename a property** across the
-  model; **fit a shape to its text**.
-- **Groups and locks on any view**, multi-select, a marquee, Archi's tabbed groups, bendpoints, pinned line ends,
-  and orthogonal, curved or straight routing.
-
-### Understanding and sharing a model
-
-- A **model tree** by layer, by type or flat, each element with its type's picture, with search and filters (type, specialization, property) that dim the
-  diagram too.
-- An **analysis panel** for the selected element: which views it's on, and its incoming and outgoing relationships.
-- **Check model** finds relationships the rules don't allow, likely duplicates (by their words, so "System of
-  Order Management" matches "order-management system"), unused elements and relationships, empty views, nested
-  elements with no relationship, and unprintable characters. **Merge…** makes duplicates one element, keeping
-  every relationship and appearance on a view.
-- **Derived relationships**, worked out and shown as dotted lines.
-- **Roadmaps**: generate a view of work packages, plateaus or anything with start and end dates, as bars under
-  the months.
-- An **HTML report** in one self-contained file: a tree, search, a page per element, relationship and view, and
-  diagrams whose elements link to their pages.
-- **Images**: export PNG or SVG, or copy to the clipboard.
-
-### Beyond Archi
-
-It runs in the browser and embeds in other apps. It also has:
-
-- ArchiMate 4 types alongside 3.2;
-- derived relationships without scripts;
-- invalid relationships shown as you choose (highlight, tooltip or hidden), per view, per model or for the tool;
-- groups and locks on every view, not just canvases;
-- a canvas template library shared across models;
-- two drawing backends, SVG and Canvas.
-
----
-
-## The diagram editor
-
-The ArchiMate modeller is built on a general diagram editor, and every editing feature above is part of that
-editor rather than of ArchiMate: align, format painter, properties of several shapes, find and replace, copy and
-paste, groups and locks, undo, HTML report, image export, several models at once. The diagram editor gives you all
-of them for its own palettes:
-
-- basic shapes
-- flowchart and BPMN
-- swimlanes
-- UML: class, sequence, activity, state machine, use case, component, deployment
-- entity-relationship
-- data flow
-- network
-- org chart
-
-Each model can hold several diagrams, with line styles inherited from the diagram, then the model, then the tool.
-
-![The diagram editor: an order flowchart with a decision, labelled lines and the flowchart palette](https://gitlab.com/peter.prib/renderengine/-/raw/master/docs/images/diagram-editor.png)
-
-## The chart library
-
-The engine underneath draws 24 chart types: bar, line, area, pie, scatter, bubble, heatmap, candlestick,
-waterfall, histogram, box plot, violin, radar, funnel, treemap, sunburst, gauges (dial, arc, ring, rings, bar, bullet, thermometer, KPI tiles; with bands, targets, LED segments and animation), 3D bars and others. It also
-draws graph and railroad diagrams, all to SVG or Canvas. `test/charts.html` is the full gallery, and
-`examples/csv-chart-builder.html` builds a chart from a CSV file without code.
-
-![Gauges: a dial with bands, ticks and a target; arc, ring and nested rings; a two-needle dial; LED segments; a thermometer; KPI tiles with sparklines](https://gitlab.com/peter.prib/renderengine/-/raw/master/docs/images/gauges.png)
-
-![Charts from the gallery: bar, grouped bar, line and line with error bars](https://gitlab.com/peter.prib/renderengine/-/raw/master/docs/images/charts.png)
-
----
-
-## Put it in your own page
-
-```bash
-npm install @peter.prib/renderengine
-```
-
-The package is the ES module source and the built bundles:
-
-- `import { ArchimateModel, RenderEngine } from '@peter.prib/renderengine'`: the engine and the models (this also
-  imports under Node).
-- `import '@peter.prib/renderengine/workspace'`: the workbench shell and its parts (browser only).
-- `@peter.prib/renderengine/dist/renderengine-workspace.umd.js`: the same as one classic script.
-
-The modeller is a part in the `<ws-workspace>` workbench shell. One script tag and a JSON spec is the whole host
-page:
-
-```html
-<script src="dist/renderengine-workspace.umd.js"></script>
-<script>
-    const { el, registerBuiltinParts, ArchimateCanvasPart } = RenderEngineWorkspace;
-    const ws = document.body.appendChild(el({ tag: 'ws-workspace', attrs: { label: 'Modeller' } }));
-    registerBuiltinParts(ws);
-    ws.registerPart(ArchimateCanvasPart);
-    ws.addParts([{
-        id: 'models', type: 'models', editorType: 'archimate-canvas',   // several models, a tab each
-        models: [{
-            id: 'shop', name: 'Shop',
-            elements: [{ id: 'c', name: 'Customer', type: 'business-actor' }, { id: 'o', name: 'Order', type: 'business-process' }],
-            relationships: [{ source: 'c', target: 'o', kind: 'assignment' }],
-            views: [{ id: 'v', name: 'Main', elementIds: ['c', 'o'], layout: { c: { x: 100, y: 100 }, o: { x: 320, y: 100 } } }],
-        }],
-    }]);
-    ws.registerPerspective('Modelling', { type: 'part', partId: 'models' });
-    ws.activatePerspective('Modelling');
-</script>
-```
-
-Use `editorType: 'diagram-editor'` with `DiagramEditorPart` for the diagram editor. The model is a plain JavaScript
-API (`ArchimateModel`, `DiagramModel`), so you can also build, check, search, report on and export models with no
-UI at all.
-
----
-
-## Documentation
-
-| Document | What it covers |
-|---|---|
-| `REFERENCE.md` | The API: chart methods and options, the editors, models, commands, file formats |
-| `WORKSPACE_ARCHITECTURE.md` | The `<ws-workspace>` shell: parts, layout, context bus, work area |
-| `ARCHITECTURE.md` | Module layout and the chart-type catalog |
-| `LLM_ARCHIMATE_GUIDE.md` | Generating valid ArchiMate model data, with a prompt template |
-| `tasks.md` | What's still to come |
-
-## Build and test
-
-```bash
-npm install        # dev tools only: Rollup
-npm run build      # dist/renderengine.umd.js and dist/renderengine-workspace.umd.js
-npm test           # Node's built-in test runner, no browser needed
-npm run screenshots  # this README's pictures, from the example pages (headless Chrome)
-```
-
-There are two bundles:
-
-- `renderengine.umd.js` (global `RenderEngine`): the engine.
-- `renderengine-workspace.umd.js` (global `RenderEngineWorkspace`): the workbench shell and its parts, plus the
-  whole engine API, so one script tag is enough.
-
-The source is plain ES modules. `src/index.js` imports under Node, which is how the tests run.
-
-## Licence
-
-MIT. Contributions welcome.
+# RenderEngine
+
+**An ArchiMate modeller, a diagram editor and a chart library that run in any browser tab, with no install and no
+runtime dependencies.**
+
+Open an Archi model, edit it the way you would in Archi, and save it back to the same `.archimate` file, without
+installing anything. Or put the same editor in your own app: it's a JavaScript library and a set of workbench parts,
+not a desktop application.
+
+![The ArchiMate modeller: a layered view of an online shop, the model tree by layer with each type's picture, and the palette](https://gitlab.com/peter.prib/renderengine/-/raw/master/docs/images/archimate-modeller.png)
+
+---
+
+## Try it
+
+```bash
+git clone https://gitlab.com/peter.prib/renderengine.git
+cd renderengine
+npm start          # the ArchiMate modeller
+npm run diagram    # the diagram editor (flowcharts, UML and more)
+npm run datamodel  # a data model at each level, in each notation
+```
+
+No server is needed, and nothing needs installing first, because the built bundles are in `dist/`. You can also
+open the pages directly:
+
+- `examples/archimate.html`: the ArchiMate modeller
+- `examples/diagram-editor.html`: the diagram editor
+- `examples/data-model.html`: a data model (conceptual, logical, physical; Chen, Crow's Foot, UML)
+
+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.
+
+---
+
+## The ArchiMate modeller
+
+### Works with Archi
+
+- **Open and save Archi files** (`.archimate`, and archives that include pictures). Save writes back to the file you
+  opened; Save As picks a new one. Unsaved changes are marked (•), and the page asks before you leave or close them.
+- **Import a spreadsheet** into the open model: choose the name, type, id, documentation, property and "related
+  to" columns; existing elements are updated, not duplicated (Archi's elements.csv imports as it is).
+- **draw.io export**: every view a page, in draw.io's ArchiMate shapes, with the elements' properties.
+- **Open Group Exchange Format** import and export, the standard way into Sparx, BiZZdesign and other tools.
+  Checked with Archi 5.8, which validates and opens the files.
+- **Every element Archi receives is a valid ArchiMate 3.2 class.** A type Archi lacks is written as its nearest
+  3.2 type, and its own type is kept so it comes back on the next import.
+- **Canvases, sketches, notes, groups and Archi's canvas templates** come through import and export.
+
+### Modelling
+
+- A **palette** of every element type, grouped by layer and limited by the view's viewpoint.
+- **Connecting two elements offers only the relationship kinds the ArchiMate rules allow** between them.
+- **Nesting**: drop an element inside another and choose what the nesting stands for (composition, aggregation,
+  assignment, realization or specialization). It goes into the model, and the nesting shows it.
+- **Add from text**: paste a list of names, from a document or a spreadsheet's columns, and get an element for
+  each.
+- **Copy and paste** within a model and between models, **Duplicate**, and **Generate View For** an element and
+  what it relates to.
+- **Several models open at once**, a tab each. Each has its own file and its own undo history.
+- **Undo for everything**, one history per model as in Archi: edits on any view, and adding, renaming and deleting
+  views. Undoing an edit made on another view takes you to that view.
+- **Specializations**, custom viewpoints, label expressions (`${name}` and `{name}`), and properties with types.
+
+### Editing
+
+- **Align, distribute and match size**, to the shape you selected last, as in Archi; **automatic layouts** (grid,
+  circle, tree, force-directed, by layer) and **Nest its parts inside**, following composition and aggregation.
+- **Properties of several shapes at once**: colours and text style, the elements' type and specialization, and a
+  property to set on all of them.
+- **Format painter**: copy one shape's look onto others.
+- **Colour by** layer, type, specialization or any property (a heat map, e.g. by lifecycle: invest, maintain,
+  retire), with a legend; or a legend of the element types on the view.
+- **Find and replace** across names, documentation and property values, with match case, whole words and
+  regular expressions; **transform names** (Title Case, split camelCase, ...) and **rename a property** across the
+  model; **fit a shape to its text**.
+- **Groups and locks on any view**, multi-select, a marquee, Archi's tabbed groups, bendpoints, pinned line ends,
+  and orthogonal, curved or straight routing.
+
+### Understanding and sharing a model
+
+- A **model tree** by layer, by type or flat, each element with its type's picture, with search and filters (type, specialization, property) that dim the
+  diagram too.
+- An **analysis panel** for the selected element: which views it's on, and its incoming and outgoing relationships.
+- **Check model** finds relationships the rules don't allow, likely duplicates (by their words, so "System of
+  Order Management" matches "order-management system"), unused elements and relationships, empty views, nested
+  elements with no relationship, and unprintable characters. **Merge…** makes duplicates one element, keeping
+  every relationship and appearance on a view.
+- **Derived relationships**, worked out and shown as dotted lines.
+- **Roadmaps**: generate a view of work packages, plateaus or anything with start and end dates, as bars under
+  the months.
+- An **HTML report** in one self-contained file: a tree, search, a page per element, relationship and view, and
+  diagrams whose elements link to their pages.
+- **Images**: export PNG or SVG, or copy to the clipboard.
+
+### Beyond Archi
+
+It runs in the browser and embeds in other apps. It also has:
+
+- ArchiMate 4 types alongside 3.2;
+- derived relationships without scripts;
+- invalid relationships shown as you choose (highlight, tooltip or hidden), per view, per model or for the tool;
+- groups and locks on every view, not just canvases;
+- a canvas template library shared across models;
+- two drawing backends, SVG and Canvas.
+
+---
+
+## The diagram editor
+
+The ArchiMate modeller is built on a general diagram editor, and every editing feature above is part of that
+editor rather than of ArchiMate: align, format painter, properties of several shapes, find and replace, copy and
+paste, groups and locks, undo, HTML report, image export, several models at once. The diagram editor gives you all
+of them for its own palettes:
+
+- basic shapes
+- flowchart and BPMN
+- swimlanes
+- UML: class, sequence, activity, state machine, use case, component, deployment
+- entity-relationship
+- data flow
+- network
+- org chart
+
+Each model can hold several diagrams, with line styles inherited from the diagram, then the model, then the tool.
+
+![The diagram editor: an order flowchart with a decision, labelled lines and the flowchart palette](https://gitlab.com/peter.prib/renderengine/-/raw/master/docs/images/diagram-editor.png)
+
+## The chart library
+
+The engine underneath draws 24 chart types: bar, line, area, pie, scatter, bubble, heatmap, candlestick,
+waterfall, histogram, box plot, violin, radar, funnel, treemap, sunburst, gauges (dial, arc, ring, rings, bar, bullet, thermometer, KPI tiles; with bands, targets, LED segments and animation), 3D bars and others. It also
+draws graph and railroad diagrams, all to SVG or Canvas. `test/charts.html` is the full gallery, and
+`examples/csv-chart-builder.html` builds a chart from a CSV file without code.
+
+![Gauges: a dial with bands, ticks and a target; arc, ring and nested rings; a two-needle dial; LED segments; a thermometer; KPI tiles with sparklines](https://gitlab.com/peter.prib/renderengine/-/raw/master/docs/images/gauges.png)
+
+![Charts from the gallery: bar, grouped bar, line and line with error bars](https://gitlab.com/peter.prib/renderengine/-/raw/master/docs/images/charts.png)
+
+---
+
+## Put it in your own page
+
+```bash
+npm install @peter.prib/renderengine
+```
+
+The package is the ES module source and the built bundles:
+
+- `import { ArchimateModel, RenderEngine } from '@peter.prib/renderengine'`: the engine and the models (this also
+  imports under Node).
+- `import '@peter.prib/renderengine/workspace'`: the workbench shell and its parts (browser only).
+- `@peter.prib/renderengine/dist/renderengine-workspace.umd.js`: the same as one classic script.
+
+The modeller is a part in the `<ws-workspace>` workbench shell. One script tag and a JSON spec is the whole host
+page:
+
+```html
+<script src="dist/renderengine-workspace.umd.js"></script>
+<script>
+    const { el, registerBuiltinParts, ArchimateCanvasPart } = RenderEngineWorkspace;
+    const ws = document.body.appendChild(el({ tag: 'ws-workspace', attrs: { label: 'Modeller' } }));
+    registerBuiltinParts(ws);
+    ws.registerPart(ArchimateCanvasPart);
+    ws.addParts([{
+        id: 'models', type: 'models', editorType: 'archimate-canvas',   // several models, a tab each
+        models: [{
+            id: 'shop', name: 'Shop',
+            elements: [{ id: 'c', name: 'Customer', type: 'business-actor' }, { id: 'o', name: 'Order', type: 'business-process' }],
+            relationships: [{ source: 'c', target: 'o', kind: 'assignment' }],
+            views: [{ id: 'v', name: 'Main', elementIds: ['c', 'o'], layout: { c: { x: 100, y: 100 }, o: { x: 320, y: 100 } } }],
+        }],
+    }]);
+    ws.registerPerspective('Modelling', { type: 'part', partId: 'models' });
+    ws.activatePerspective('Modelling');
+</script>
+```
+
+Use `editorType: 'diagram-editor'` with `DiagramEditorPart` for the diagram editor. The model is a plain JavaScript
+API (`ArchimateModel`, `DiagramModel`), so you can also build, check, search, report on and export models with no
+UI at all.
+
+---
+
+## Documentation
+
+| Document | What it covers |
+|---|---|
+| `REFERENCE.md` | The API: chart methods and options, the editors, models, commands, file formats |
+| `WORKSPACE_ARCHITECTURE.md` | The `<ws-workspace>` shell: parts, layout, context bus, work area |
+| `ARCHITECTURE.md` | Module layout and the chart-type catalog |
+| `LLM_ARCHIMATE_GUIDE.md` | Generating valid ArchiMate model data, with a prompt template |
+| `tasks.md` | What's still to come |
+
+## Build and test
+
+```bash
+npm install        # dev tools only: Rollup
+npm run build      # dist/renderengine.umd.js and dist/renderengine-workspace.umd.js
+npm test           # Node's built-in test runner, no browser needed
+npm run screenshots  # this README's pictures, from the example pages (headless Chrome)
+```
+
+There are two bundles:
+
+- `renderengine.umd.js` (global `RenderEngine`): the engine.
+- `renderengine-workspace.umd.js` (global `RenderEngineWorkspace`): the workbench shell and its parts, plus the
+  whole engine API, so one script tag is enough.
+
+The source is plain ES modules. `src/index.js` imports under Node, which is how the tests run.
+
+## Licence
+
+MIT. Contributions welcome.

package/REFERENCE.md

@@ -718,6 +718,78 @@ types — see `ARCHITECTURE.md`):
   renders a dashed line (a non-identifying relationship, in real ERD terms) regardless of notation;
   unset/`true` stays solid. None of the three notations are pixel-perfect renditions of the real, full
   notations (same calibration as `archimateDiagram`'s own icons) — see `src/datamodel.js`'s own doc comment.
+  An entity drawn as a box with its name inside (the conceptual level, and Chen) is `DataModelDiagram.ENTITY_BOX`
+  (140 × 56) unless it gives `width`/`height`; one with its own `shape` (any glyph: `'person'`, `'cube'`,
+  `'cylinder'`, ...) and `labelPosition: 'below'` keeps the shape's size. In Chen a relationship's diamond holds
+  its name and sits midway between its two entities when both have `x`/`y`, or when something is drawn there (an entity, a
+  note, another diamond) the nearest clear spot across the line (`RelationshipAsNodeStrategy.spotFor`,
+  `DataModelDiagram.boxOf`); its lines have no arrowheads.
+  Each level and notation has a `label` for menus (`'Conceptual'`, `"Crow's Foot"`).
+  **Levels of their own, and how they map.** A `DataModel` (`src/charting/datamodel/`, exported from the package
+  root) keeps each level as its own schema, a `LevelSchema` (`model.level('conceptual' | 'logical' | 'physical')`):
+  its entities (`{id, name, description?, attributes?, x?, y?, color?, shape?, labelPosition?}`; `attributes`
+  `[{name, type?, isPK?, isFK?}]`, none for a concept, a physical entity's name its table's) and its relationships.
+  The levels are not one to one: a `LevelMapping` from each level to the next (`model.mapping('conceptual',
+  'logical')`) is pairs of ids, any number either way (a concept realised by several logical entities, several by
+  one table, or many many). `model.realising(level, conceptIds)` gives what realises some concepts at a level;
+  `model.conceptsOf(level, id)` what an entity or table realises. The older form, one entity carrying each level's
+  detail (`{ entities, relationships }`, as `dataModelDiagram` takes them), is read as three levels mapped one to one
+  (`DataModel.levelsFromCombined`).
+
+  **Schema, perspective, context.** On that structure, a `DataModelPerspective` is a stakeholder's viewpoint on the
+  concepts: the concepts it shows (`entities`, all when unset) under its names (`names`, and `relationshipNames` by
+  relationship id), and the context it is read in (`context`); a `DataModelContext` is the meaning, scope and
+  constraints: what concepts mean there (`meanings`), the rules that hold (`constraints: [{id?, text, applies:
+  [concept ids], x?, y?}]`) and where and when (`jurisdiction`, `validFrom`, `validTo`; `context.scope` reads
+  'AU · from 2024-07-01'). `model.view({ perspective, context, level })` (ids, either may be null) gives
+  `{entities, relationships, annotations, links}` for `dataModelDiagram`, the schema itself unchanged: at a level,
+  what realises the concepts shown (the concepts themselves under the perspective's names), each with its level's
+  detail, its `description` the context's meaning of its concepts, and `details` (shown on hover) naming the schema
+  entity behind a renamed concept, the concepts an entity or table realises, the context and the rules on them; the
+  level's relationships between shown entities; and each rule as a note on what realises the concepts it applies
+  to, placed per level (`model.notePlace(level, rule)`: the rule's own `x`, `y` on the concepts, `model.noteLayout`
+  on the others, else in a row below every box). With `level: 'mapping'` (`DataModel.MAPPING`, `model.mappingView()`)
+  it gives the levels side by side, a column each (ids `'level:id'`, each box drawn at its own `level`, where
+  `model.mappingLayout` left it), and a `link` per mapping between shown ones. `dataModelDiagram` draws an entity at
+  its own `level` when it has one; its `annotations` option (`[{id, text, attachTo: [entity ids], x?, y?}]`) draws
+  notes, and its `links` option (`[{source, target, label?}]`) plain lines, both dotted in every notation
+  (`DataModelDiagram.buildLink`); an entity's `details` show on hover, boxes and tables alike.
+
+  ```js
+  const model = new DataModel({
+      levels: {
+          conceptual: { entities: [{ id: 'party', name: 'Party' }], relationships: [] },
+          logical: { entities: [{ id: 'person', name: 'Person', attributes: [{ name: 'id', isPK: true }] },
+              { id: 'org', name: 'Organisation', attributes: [{ name: 'id', isPK: true }] }], relationships: [] },
+          physical: { entities: [{ id: 'party_t', name: 'party', attributes: [{ name: 'party_id', type: 'BIGINT', isPK: true }] }], relationships: [] },
+      },
+      mappings: [
+          { from: 'conceptual', to: 'logical', pairs: [['party', 'person'], ['party', 'org']] },   // one to many
+          { from: 'logical', to: 'physical', pairs: [['person', 'party_t'], ['org', 'party_t']] },   // many to one
+      ],
+      perspectives: [{ id: 'customer', context: 'retail', names: { party: 'Customer' } }],
+      contexts: [{ id: 'retail', jurisdiction: 'AU', meanings: { party: 'Someone who buys from us.' },
+          constraints: [{ text: 'Prices include GST', applies: ['party'] }] }],
+  });
+  const { entities, relationships, annotations, links } = model.view({ perspective: 'customer', context: 'retail', level: 'mapping' });
+  engine.dataModelDiagram(entities, relationships, { annotations, links, level: 'conceptual' });
+  ```
+
+  **Perspectives and contexts of one's own.** `model.addPerspective(spec)` / `updatePerspective(id, spec)` /
+  `removePerspective(id)`, and the same for contexts (an id is made from the name when none is given; a context
+  removed leaves its perspectives in none). Each class defines its own dialog: `DataModelPerspective.fields(model,
+  perspective?)` and `DataModelPerspective.specFrom(values, model)` (what it shows, what it calls each concept);
+  `DataModelContext.fields(model, context?)` and `DataModelContext.specFrom(values, model, context?)` (meanings, dates,
+  and rules a line each, `the rule | the concepts, by name`).
+
+  **In the workbench:** `DataModelPart` (type `data-model`, `RenderEngineWorkspace.DataModelPart`) shows one
+  model: 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
+  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`).
 - `railroadDiagram(diagramString)` — renders an EBNF grammar string as a railroad diagram. No node/edge
   data at all.
 
@@ -1029,15 +1101,22 @@ do, and a folder of one type in the Layers tree too (`typeGlyph(typeName, { size
 `TreeBuilder`'s `iconFor(node)` gives a node a picture in place of its `icon` text.
 
 **Nesting.** In the ArchiMate canvas editor, dropping a box wholly inside an element's box nests it there (Archi's
-nested elements): it moves with its parent, is raised above it, and an Archi file writes it inside it (whatever order
+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
+own parents in turn (`DiagramEditor#fitNesting`, `DiagramEditor.NEST_MARGIN`: room around it, more at the top for
+the parent's name), all in the move's undo step. A nested box moves with its parent, is raised above it, and an Archi file writes it inside it (whatever order
 they were added in). Dragged out again, it is taken out. The move and the nesting are one undo step. On a canvas, a
 block holds boxes the same way. Nesting one element in another then asks which relationship it stands for, among
 Archi's nesting kinds (`NESTING_KINDS`: composition, aggregation, assignment, realization, specialization) that the
 rules allow from parent to child, and none when the two already have one; **Add** puts it in the model, drawn as no
 line (the nesting shows it), as its own undo step; **No relationship** adds none. The shared editor does the
 finding: after a move, `DiagramEditor#nestingChanges(ids)` gives each moved shape's new parent (the innermost shape
-that wholly holds it and `canHold` it), and a subclass supplies `parentOf`, `canHold`, `nestCommand`
-(`NestInstanceCommand`) and `nested(changes)`; the template editor has no nesting. Model checks: **Check model…**
+that wholly holds it and `canHold` it, else the innermost its centre lies on that `nestsOnDrop` it), and a subclass
+supplies `parentOf`, `canHold`, `nestsOnDrop`, `nestCommand` (`NestInstanceCommand`) and `nested(changes)`; the
+template editor has no nesting. As in Archi, a line a nesting stands for (one of `NESTING_KINDS`) from a box to one
+nested in it is not drawn, at any depth (to a box nested in a box nested in it too: `hiddenByNesting`,
+`holdsNested` in `diagrams/nesting.js`); an Archi file's such lines are read in, kept and written back, just not
+drawn. ⚙ Settings ▸ **Lines to nested boxes** (`nodeOptions.showNestedLines`) shows them. Model checks: **Check model…**
 warns of an element drawn inside another with no such relationship (`nested-without-relationship`), and a
 relationship a nesting shows is not reported as unused (`viewNestings(view)`, `nestingRelationships` in
 `diagrams/nesting.js`).
@@ -1103,7 +1182,14 @@ 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`. The analysis names an element's layer as the tree files it (`treeLayerOf`).
+`editor.setElementFilter`. 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
+(`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
+values starts folded, with a box that narrows its values to those containing what is typed; ticking the property
+then ticks only the values shown (`CheckboxTreeSelector`'s `searchAbove`, `search(id, text)`). The analysis names an element's layer as the tree files it (`treeLayerOf`).
 
 **Groups on the canvas.** An Archi group (a model folder with bounds on the view, `view.placedFolders`) is a
 `ViewGroupTemplate`: Archi's box with a name tab (`TabbedBoxGlyph`), placed by its centre while its layout entry
@@ -1671,6 +1757,7 @@ the shared `MenuBar` (see "Toolbars and dialogs" below):
 - **`viewpoint`** — Settings ▸ Viewpoint (every built-in and custom viewpoint) and ▸ Viewpoint mode (fade/hide)
 - **`distinctShapes`** — Settings ▸ Distinct shapes: on/off
 - **`showDerived`** — Settings ▸ Show derived: on/off
+- **`showNestedLines`** — Settings ▸ Lines to nested boxes: hidden (default, Archi's way) / shown
 - **`exportCSV`**, **`importCSV`**, **`exportArchimate`**, **`importArchimate`** — entries in the **File** menu,
   after the view items (New view…, Properties…, Duplicate, Delete)
 
@@ -1940,8 +2027,12 @@ Each ArchiMate relationship type gives its notation as line style values:
 `{ lineStyle: 'solid', startMarker: 'diamond', endMarker: 'none' }`; arrowheads come back as marker keys
 (`realization` ends in `'trianglehollow'`).
 
-`DIAGRAM_TYPES` (19 categories in the groups General, Process, UML, Data, Infrastructure,
-Business, Ideas) decides which templates the palette offers. `editor.initPaletteForDiagramType(container, key)`
+`DIAGRAM_TYPES` (20 categories in the groups General, Process, UML, Data, Infrastructure,
+Business, Ideas) decides which templates the palette offers. An entry may say what it is (`description`), shown
+when the pointer rests on its tile. **Enterprise Ontology** (`'enterprise-ontology'`, in Data) offers the
+universal concepts enterprise data models are built from (after IBM IFW's data concepts), each described: Party,
+Role, Arrangement, Product, Resource, Event, Account / Ledger, Classification, Place, Time, Measure, Business
+Direction and Rule. `editor.initPaletteForDiagramType(container, key)`
 renders a grouped category picker above a grid of draggable tiles. `editor.setPaletteCategory(key)`
 switches category, and `onTemplateTypeChange(key)` (a constructor option) reports the switch.
 Unknown keys fall back to `'generic'` (Basic Shapes).
@@ -1962,7 +2053,8 @@ class ChevronTemplate extends PolygonTemplate {
 
 DIAGRAM_TYPES['value-chain'] = {
     name: 'Value Chain', group: 'Business', description: 'Primary activities in sequence',
-    templates: [{ id: 'activity', name: 'Activity', factory: (id, x, y) => new ChevronTemplate(id, 'Activity', { x, y }) }],
+    templates: [{ id: 'activity', name: 'Activity', description: 'A step that adds value',
+        factory: (id, x, y) => new ChevronTemplate(id, 'Activity', { x, y }) }],
 };
 
 console.log(DIAGRAM_TYPES['value-chain'].templates[0].factory('a1', 100, 50).points().length); // 6