@peter.prib/renderengine 0.14.0 → 0.15.1

package/documentation/REFERENCE.md

@@ -2640,6 +2640,8 @@ end. Waypoints and style are kept, and that end's side pin resets to automatic.
 empty canvas, or on the shape at the other end, cancels. This is one undo step
 (`ReconnectEdgeCommand`).
 
+**Container nesting and hierarchy.** Shapes such as `PackageTemplate`, `SwimlaneTemplate`, and `BoxTemplate` are containers (`isContainer = true`). When an element is dropped inside a container (`nestsOnDrop(parentId, childId)`), it is parented via `NestElementCommand` (setting `child.parentId`). Moving a container recursively moves all nested descendants (`moversFor(templateId)`). Containers can automatically expand their bounds to fit their contents via `fitNesting(changes, { padding })`. Ancestor loops are prevented (`isAncestor(childId, parentId)`).
+
 **Line style levels.** A line's style resolves through `EdgeStyleCascade`: the line itself,
 then each level in `editor.edgeStyleLevels` (most specific first, `[{ key, label, style }]`),
 then the schema default. A value a level doesn't set is inherited. `EDGE_STYLE_PROPERTIES` is the
@@ -3200,6 +3202,56 @@ 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`).
 
+## Decision Workbench (`DecisionWorkbench`)
+
+The views of a SADIS recommendation made by decisionengine (`gitlab.com/peter.prib/decisionengine`),
+drawn with this library's charts. It reads decisionengine's JSON, not decisionengine: a workbench
+document
+
+```js
+{ kind: 'sadis-workbench', report, plan?, before? }   // report.toJSON(), plan.toJSON(), an earlier report.toJSON()
+```
+
+which decisionengine's SADIS Explorer downloads ("Download for the Decision Workbench").
+
+```js
+import { DecisionWorkbench } from '@peter.prib/renderengine';
+const workbench = DecisionWorkbench.from(doc, { start: '2026-11-02', periodDays: 14 });
+for (const view of workbench.views()) {
+    view.id, view.title;          // 'executive', 'Executive', …
+    view.charts();                // [{ title, chartType, data, options }] — chartType is a CHART_CATALOG key
+    view.notes();                 // plain lines for what the charts cannot show
+}
+```
+
+| View | Needs | Charts |
+|---|---|---|
+| Executive | a report | `kpi-tile` (what to build next; half the value delivered by), `stackedBar` (score part by part), `line` (value delivered by period) |
+| Architecture | a report | `scatter` (visible rating against basin position: foundations sit high and left), `lollipop` (share each frees) |
+| Delivery | a plan | `gantt` (the plan on a calendar), `stackedBar` (capacity used per period, per team when planned by team) |
+| Portfolio | a report with perspectives | `heatmap` (rank by perspective), `dumbbell` (best and worst rank, most contested first) |
+| Replay | an earlier report | `slopegraph` (rank then → now); notes say what entered, left (and why) and moved |
+
+A view the document cannot fill is not offered. `from()` refuses what is not a workbench document,
+saying why. The delivery plan's periods are put on a calendar: period 1 starts at `start` (default:
+the report's as-of business time, else today), each `periodDays` long (default 14). Each view is a
+`WorkbenchView` subclass (`WORKBENCH_VIEWS`); a new view is a new subclass.
+
+In a workspace the workbench is one part, `DecisionWorkbenchPart` (type `decision-workbench`), a
+`ViewsPart` that reads workbench documents: a tab per view, its charts and notes, a toolbar that opens a
+file and sets the calendar.
+
+```js
+const { registerBuiltinParts, ChartPart, DecisionWorkbenchPart } = RenderEngineWorkspace;
+ws.registerParts([ChartPart, DecisionWorkbenchPart]);
+ws.addParts([{ id: 'workbench', type: 'decision-workbench', document /* optional */, start, periodDays }]);
+```
+
+`ViewsPart` (type `views`) is the general part underneath: any `{ views: [{ id, title, charts, notes }] }`
+document, or views given in its spec, shown the same way — see `documentation/WORKSPACE_ARCHITECTURE.md`
+for why it is one part and why a new kind of document is a subclass. `examples/decision-workbench.html`
+is a thin host of the workbench part (it is in the package).
+
 ## Navigation menus
 
 `NavMenu` is a vertical navigation menu (a sidebar's), written as data: no markup. Each entry is
@@ -3311,6 +3363,160 @@ const bar = RenderEngine.askBar(document.getElementById('ask-bar'), {
 - **For a host:** `bar.setSuggest(fn)` swaps where suggestions come from, for example when the user picks another model or ontology. `bar.setValue(text)` sets the question without suggesting. `bar.focus()` puts the cursor in the question, and `bar.destroy()` removes the bar and cancels any pending close.
 - **Accessible:** the input is a WAI-ARIA combobox over a `listbox` of `option`s. `aria-expanded` follows the popup and `aria-activedescendant` follows the active item. Each bar's list has its own id, so several bars can share a page.
 
+## Navigator & Relationship Explorer (`NavigatorModel` / `NavigatorPanel`)
+
+`NavigatorModel` (`src/charting/modelTree/NavigatorModel.js`) and `NavigatorPanel` (`src/charting/modelTree/NavigatorPanel.js`) provide interactive graph traversal and relationship exploration for models. It enables navigating through connected elements step-by-step to arbitrary depth with cycle detection, navigation history (back/forward), direction filters, path-finding, and transitive impact analysis.
+
+```javascript
+import { NavigatorModel, NavigatorPanel, buildNavigatorPanel } from '@peter.prib/renderengine';
+
+// 1. Create a pure, DOM-free traversal model:
+const nav = new NavigatorModel(archimateModel, {
+    rootId: 'billing-app',
+    direction: 'both', // 'both' | 'outgoing' | 'incoming'
+    allowedKinds: ['serving-relationship', 'composition-relationship'],
+});
+
+nav.focus('crm-app');
+nav.canGoBack;     // true
+nav.back();        // returns to 'billing-app'
+
+// Find all paths between two elements (up to maxDepth):
+const paths = nav.findPaths('billing-app', 'ledger-db', 5);
+
+// Trace transitive downstream or upstream impact:
+const impact = nav.findImpact('billing-app', { maxDepth: 4, direction: 'outgoing' });
+
+// 2. Build or render the Navigator UI panel:
+const panel = new NavigatorPanel({
+    model: archimateModel,
+    navigator: nav,
+    onSelectElement: (elId) => editor.selectElement(elId),
+    onOpenView: (viewId) => editor.openView(viewId),
+});
+```
+
+- **DOM-free engine:** `NavigatorModel` operates completely without DOM dependencies, making it directly testable in Node.js and reusable across diverse UI shells.
+- **Cycle detection and path tracking:** Tracks visited nodes along active branches to prevent infinite recursion in cyclic relationship graphs, annotating cycles in tree outputs.
+- **Directional filters:** Traversal can follow outgoing relationships, incoming relationships, or bidirectional connections (`setDirection('outgoing' | 'incoming' | 'both')`).
+- **History stack:** Maintains full forward and backward navigation stacks (`focus(id)`, `back()`, `forward()`, `canGoBack`, `canGoForward`).
+- **Impact and path finding:** Built-in BFS/DFS algorithms find connecting pathways (`findPaths(fromId, toId, maxDepth)`) and downstream dependency cascades (`findImpact(elementId, { maxDepth, direction })`).
+
+## Templated Reports (`TemplatedReport`)
+
+`TemplatedReport` (`src/charting/report/TemplatedReport.js`) provides multi-format, template-driven report generation matching Archi's Jasper-style reporting capabilities. It extracts model metadata, viewpoints, diagrams (SVG/PNG), elements, properties, and relationships into document formats.
+
+```javascript
+import { TemplatedReport, REPORT_TEMPLATES } from '@peter.prib/renderengine';
+
+const report = new TemplatedReport(archimateModel, {
+    title: 'Enterprise Architecture Overview',
+    template: REPORT_TEMPLATES.DETAILED, // 'executive' | 'detailed' | 'tabular'
+    pictures: { 'view-1': 'data:image/svg+xml;utf8,...' },
+});
+
+// Generate various formats:
+const htmlDoc = report.toHtml({ printable: true }); // PDF-ready HTML with @media print CSS
+const wordDoc = report.toWord();                    // Microsoft Word (.doc HTML format)
+const excelXml = report.toExcel();                  // Excel SpreadsheetML (.xml)
+const csvData = report.toCsv('elements');           // RFC 4180 CSV ('elements' | 'relationships')
+const markdown = report.toMarkdown();               // GitHub-flavored Markdown
+```
+
+- **Output formats:** Generates printable PDF-ready HTML with page-break controls, Word-compatible HTML documents (`.doc`), Excel SpreadsheetML workbooks (`.xml`) with styled headers and filters, RFC 4180 CSV tables, and GitHub-flavored Markdown (`.md`).
+- **Built-in templates:** Includes `REPORT_TEMPLATES.EXECUTIVE` (high-level summary with diagrams), `REPORT_TEMPLATES.DETAILED` (full catalog of views, elements, relationships, and user properties), and `REPORT_TEMPLATES.TABULAR` (matrix-focused presentation).
+- **Embedded diagram pictures:** Accepts rendered SVG data URIs or base64 raster images in the `pictures` dictionary keyed by view ID to embed high-resolution diagrams directly into generated documents.
+
+## Sketch Views & Palettes (`SketchView` / `sketchBoxKinds`)
+
+`SketchView` (`src/charting/diagrams/SketchView.js`) implements freeform sketching views (corresponding to Archi's `archimate:SketchModel`). It supports sticky notes, stick-figure actors, groups, freehand lines, and customizable palettes on grid or lined canvas backgrounds.
+
+```javascript
+import { SketchView, SKETCH_BOX_KINDS, DEFAULT_SKETCH_PALETTE } from '@peter.prib/renderengine';
+
+const sketch = new SketchView(model, {
+    name: 'Brainstorming Session',
+    background: SketchView.BACKGROUNDS.GRID, // NONE (0), GRID (1), LINES (2)
+    palette: DEFAULT_SKETCH_PALETTE,
+});
+
+// Custom palette management:
+sketch.addPaletteItem({ id: 'custom-note', name: 'Critical Note', fill: '#ffcccc' });
+const jsonConfig = sketch.exportPalette();
+sketch.importPalette(jsonConfig);
+```
+
+- **Sketch box types:** Native support for sticky notes (`sketch-model-sticky`) and stick figures (`sketch-model-actor`) via `SKETCH_BOX_KINDS`.
+- **Background styles:** Configurable canvas backgrounds including plain (`NONE`), grid paper (`GRID`), and lined notebook paper (`LINES`).
+- **Palette customization:** Dynamically add, remove, reset, export, and import custom sticky colors and presets as JSON configurations.
+- **Archi XML compatibility:** Full bi-directional fidelity with `.archimate` sketch model XML representations (`archimate:SketchModel`, `archimate:Sticky`, `archimate:Actor`).
+
+## Cross-Model Data Lineage & ArchiMate Linking
+
+`ModelMapping` (`src/charting/datamodel/ModelMapping.js`), `DataLineage` (`src/charting/datamodel/DataLineage.js`), and `ArchimateDataLink` (`src/charting/datamodel/ArchimateDataLink.js`) extend the data modeling subsystem (`src/charting/datamodel/`) with enterprise cross-model data lineage and architectural traceability aligned with DMBOK2 and TOGAF.
+
+```javascript
+import { DataModel, ModelMapping, DataLineage, ArchimateDataLink } from '@peter.prib/renderengine';
+
+// 1. Cross-model mapping with attribute-level transformation rules:
+const mapping = new ModelMapping({
+    name: 'Core Banking to EDW',
+    sourceModel: 'OLTP-Core',
+    targetModel: 'EDW-Analytical',
+    entityMappings: [{ sourceEntityId: 'account', targetEntityId: 'dim_account', rule: 'SCD Type 2' }],
+    attributeMappings: [
+        { sourceEntityId: 'account', sourceAttribute: 'bal', targetEntityId: 'dim_account', targetAttribute: 'current_balance', transformation: 'ROUND(bal, 2)' }
+    ],
+});
+
+dataModel.addModelMapping(mapping);
+
+// 2. Trace end-to-end lineage and downstream impact:
+const lineage = dataModel.crossModelLineage();
+const upstreamHops = lineage.traceLineage('dim_account', 'current_balance'); // Upstream provenance
+const downstreamImpact = lineage.traceImpact('account', 'bal');              // Downstream impact
+
+// 3. Connect Data Model entities to ArchiMate enterprise architecture:
+const link = new ArchimateDataLink({
+    dataModelEntityId: 'account',
+    level: 'conceptual',
+    archimateElementId: 'business-obj-account',
+    archimateType: 'business-object',
+});
+dataModel.addArchimateLink(link);
+```
+
+- **DMBOK2 integration:** Enables tracking provenance across conceptual, logical, and physical models, including disparate source and target data stores.
+- **Multi-hop traversal:** Traces multi-hop transformations forwards (`traceImpact`) and backwards (`traceLineage`) across complex data pipelines.
+- **ArchiMate alignment:** Bridges data model entities to ArchiMate Business Objects (Business Layer), Data Objects (Application Layer), and Artifacts (Technology Layer).
+
+## Multi-View Chart Dashboards (`ViewsPart` / `DecisionWorkbenchPart`)
+
+`ViewsPart` (`src/workspace/parts/ViewsPart.js`) and `DecisionWorkbenchPart` (`src/workspace/parts/DecisionWorkbenchPart.js`) render multi-tab dashboards of coordinated charts and note cards inside the `<ws-workspace>` application shell.
+
+```javascript
+// Declarative view specification for a workspace layout node:
+const layout = {
+    type: 'part',
+    part: 'views',
+    views: [
+        {
+            id: 'executive-summary',
+            title: 'Executive Summary',
+            charts: [
+                { title: 'System Health', chartType: 'gauge dial', data: [{ score: 94 }], options: { min: 0, max: 100 } },
+                { title: 'Revenue Trend', chartType: 'area', data: [...] }
+            ],
+            notes: ['All latency thresholds met', 'Quarterly SLA target achieved']
+        }
+    ]
+};
+```
+
+- **Self-contained workbench part:** Embeds cleanly into tabs, split panes, or WorkArea documents alongside diagram modellers and data tables without hijacking global workspace perspective state.
+- **Catalog-driven composition:** Composes existing `ChartPart`s driven by `CHART_CATALOG` keys alongside `ListPart` note cards. Small gauge charts automatically tile along the top banner.
+- **Decision Workbench:** Specialized `DecisionWorkbenchPart` reads SADIS analysis reports and optimization plans (`viewsFrom(doc)`), projecting trade-off curves, capability radars, and decision matrices directly into tabs.
+
 ## Where to go next
 
 - **`ARCHITECTURE.md`** — module layout, the chart-type catalog mechanics, how to add a new chart type.

package/examples/decision-workbench.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Decision Workbench</title></head>
+<body style="margin:0;height:100vh;display:flex;font:14px system-ui">
+<!--
+  The Decision Workbench: decisionengine's SADIS recommendation, drawn. A thin host, as data-model.html is:
+  everything it does is DecisionWorkbenchPart's (reading a workbench file, the calendar) and ViewsPart's
+  (a tab per view, its charts and notes, opening a file). Open a workbench file — decisionengine's SADIS
+  Explorer downloads one ("Download for the Decision Workbench"). Runs straight off disk.
+-->
+<script src="../dist/renderengine-workspace.umd.js"></script>
+<script>
+    const { el, registerBuiltinParts, ChartPart, DecisionWorkbenchPart } = window.RenderEngineWorkspace;
+    const ws = document.body.appendChild(el({
+        tag: 'ws-workspace',
+        attrs: { label: 'Decision Workbench', theme: 'light' },
+        style: { flex: '1 1 auto', minHeight: '0' },
+    }));
+    registerBuiltinParts(ws);
+    ws.registerParts([ChartPart, DecisionWorkbenchPart]);
+    ws.addParts([{ id: 'workbench', type: 'decision-workbench', title: 'Decision Workbench' }]);
+    ws.registerPerspective('Decision Workbench', { type: 'part', partId: 'workbench' });
+    ws.activatePerspective('Decision Workbench');
+</script>
+</body>
+</html>

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@peter.prib/renderengine",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "ArchiMate modeller, data modeller, diagram editor, OLAP cube & pivot chart studio, and 50+ type chart library for the browser, with no runtime dependencies.",
   "type": "module",
   "main": "src/index.js",
   "module": "src/index.js",
   "browser": "dist/renderengine.umd.js",
+  "bin": {
+    "renderengine": "./bin/renderengine.mjs"
+  },
   "exports": {
     ".": "./src/index.js",
     "./workspace": "./src/workspace/index.js",
@@ -14,16 +17,19 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "bin/*.mjs",
     "src/",
     "dist/*.umd.js",
     "examples/archimate.html",
     "examples/diagram-editor.html",
     "examples/data-model.html",
+    "examples/decision-workbench.html",
     "README.md",
     "documentation/REFERENCE.md",
     "LICENSE"
   ],
   "scripts": {
+    "cli": "node bin/renderengine.mjs",
     "start": "node scripts/open.mjs examples/archimate.html",
     "archimate": "node scripts/open.mjs examples/archimate.html",
     "diagram": "node scripts/open.mjs examples/diagram-editor.html",