@peter.prib/renderengine 0.2.5 → 0.2.7

package/README.md

@@ -1,213 +1,219 @@
-# 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.
+- **Kept in the browser, backed up to the cloud.** Every model is kept in the browser as you edit it, and those open
+  reopen next time, with no file saved. File ▸ This browser backs them all up to a folder you choose once: pick one
+  that OneDrive, Google Drive or Dropbox syncs and the backups reach the cloud (each named with the date and time,
+  plus one under its plain name); browsers that cannot write to a folder download them instead.
+- **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.