@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Prib
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,204 @@
-# Temporary Holding Version
+# RenderEngine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**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.
+
+---
+
+## 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 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.
+
+---
+
+## 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
+```
+
+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.