@peter.prib/renderengine 0.4.0 → 0.7.0

package/src/icons/IconSet.js

@@ -0,0 +1,86 @@
+/**
+ * IconSet — named icons as data, built as `<svg>` specs for el().
+ *
+ * An icon is JSON: a viewBox, how it is painted, and its shapes as
+ * `[tag, attrs]` pairs:
+ *
+ *   { viewBox: '0 0 24 24', paint: 'stroke', shapes: [['circle', { cx: 12, cy: 12, r: 10 }]] }
+ *
+ * `paint` is 'stroke' (outlined in currentColor — the default, so an icon
+ * takes its parent's colour), 'fill' (filled in currentColor) or 'none' (the
+ * shapes carry their own colours: a brand mark). No markup is parsed: el()
+ * builds the spec in the SVG namespace.
+ */
+const PAINT = {
+    stroke: { fill: 'none', stroke: 'currentColor', 'stroke-width': 2, 'stroke-linecap': 'round', 'stroke-linejoin': 'round' },
+    fill:   { fill: 'currentColor' },
+    none:   {},
+};
+
+export class IconSet {
+    /** @param {Object<string, Object>} [defs] - Name → icon */
+    constructor(defs = {}) {
+        this.defs = new Map();
+        this.add(defs);
+    }
+
+    /** Add (or replace) icons, name → icon. */
+    add(defs) {
+        for (const [name, def] of Object.entries(defs)) this.define(name, def);
+        return this;
+    }
+
+    /** Add (or replace) one icon; throws when it is not one. */
+    define(name, def) {
+        if (typeof def?.viewBox !== 'string' || !Array.isArray(def.shapes) || !def.shapes.length) {
+            throw new Error(`IconSet: icon "${name}" needs a viewBox and shapes`);
+        }
+        if (def.paint != null && !(def.paint in PAINT)) {
+            throw new Error(`IconSet: icon "${name}" paint is ${Object.keys(PAINT).join(', ')}, not "${def.paint}"`);
+        }
+        for (const shape of def.shapes) {
+            if (!Array.isArray(shape) || typeof shape[0] !== 'string') throw new Error(`IconSet: icon "${name}" shapes are [tag, attrs] pairs`);
+        }
+        this.defs.set(name, def);
+        return this;
+    }
+
+    has(name) { return this.defs.has(name); }
+
+    get(name) { return this.defs.get(name) ?? null; }
+
+    /** Every icon's name, in the order added. */
+    names() { return [...this.defs.keys()]; }
+
+    /** A copy of this set with `defs` added: a host's own icons over these. */
+    with(defs) {
+        return new IconSet(Object.fromEntries(this.defs)).add(defs);
+    }
+
+    /**
+     * The icon as an el() spec.
+     * @param {string} name
+     * @param {Object} [options]
+     * @param {number|string} [options.size] - Width and height (default 24; CSS can override)
+     * @param {string} [options.title] - Its accessible name; without one it is hidden from screen readers
+     * @param {string|string[]} [options.cls] - Extra class names
+     */
+    spec(name, { size = 24, title = null, cls = null } = {}) {
+        const def = this.defs.get(name);
+        if (!def) throw new Error(`IconSet: no icon "${name}"`);
+        return {
+            tag: 'svg',
+            cls: ['re-icon', ...(Array.isArray(cls) ? cls : [cls])],
+            attrs: {
+                viewBox: def.viewBox, width: size, height: size, focusable: 'false',
+                role: title ? 'img' : null, 'aria-hidden': title ? null : 'true',
+                ...PAINT[def.paint ?? 'stroke'],
+            },
+            dataset: { icon: name },
+            children: [
+                ...(title ? [{ tag: 'title', text: title }] : []),
+                ...def.shapes.map(([tag, attrs]) => ({ tag, attrs })),
+            ],
+        };
+    }
+}

package/src/icons/index.js

@@ -0,0 +1,59 @@
+/**
+ * The built-in icons — a shared pool any host draws from (`ICONS.spec('cpu')`,
+ * or `icon('cpu')`), extended with its own (`ICONS.with({ ... })`). Outlined
+ * icons on a 24-unit grid, stroked in currentColor; the brand marks keep their
+ * colours. Names say what the picture is, not where it is used.
+ */
+import { IconSet } from './IconSet.js';
+
+const box = (x, y, width, height, rx = 1) => ['rect', { x, y, width, height, rx }];
+const path = (d) => ['path', { d }];
+
+export const ICON_DEFS = {
+    dashboard: { viewBox: '0 0 24 24', shapes: [box(3, 3, 7, 9), box(14, 3, 7, 5), box(14, 12, 7, 9), box(3, 16, 7, 5)] },
+    zap: { viewBox: '0 0 24 24', shapes: [path('m13 2-2 10h8L11 22l2-10H5L13 2z')] },
+    clock: { viewBox: '0 0 24 24', shapes: [['circle', { cx: 12, cy: 12, r: 10 }], ['polyline', { points: '12 6 12 12 16 14' }]] },
+    'clipboard-list': { viewBox: '0 0 24 24', shapes: [
+        box(8, 2, 8, 4),
+        path('M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2'),
+        path('M12 11h4'), path('M12 16h4'), path('M8 11h.01'), path('M8 16h.01'),
+    ] },
+    book: { viewBox: '0 0 24 24', shapes: [
+        path('M4 19.5A2.5 2.5 0 0 1 6.5 17H20'),
+        path('M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z'),
+    ] },
+    cpu: { viewBox: '0 0 24 24', shapes: [
+        box(4, 4, 16, 16, 2), box(9, 9, 6, 6),
+        ...['M15 2v2', 'M15 20v2', 'M2 15h2', 'M2 9h2', 'M20 15h2', 'M20 9h2', 'M9 2v2', 'M9 20v2'].map(path),
+    ] },
+    memory: { viewBox: '0 0 24 24', shapes: [
+        path('M22 12s-3 1-5 1-3-1-5-1-3 1-5 1-5-1-5-1'), path('M7 21h10'), path('M9 21V10'), path('M15 21V10'),
+        path('M8 3h8a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2Z'),
+    ] },
+    activity: { viewBox: '0 0 24 24', shapes: [['polyline', { points: '22 12 18 12 15 21 9 3 6 12 2 12' }]] },
+    database: { viewBox: '0 0 24 24', shapes: [
+        ['ellipse', { cx: 12, cy: 5, rx: 9, ry: 3 }],
+        path('M3 5v14c0 1.66 4.03 3 9 3s9-1.34 9-3V5'),
+        path('M3 12c0 1.66 4.03 3 9 3s9-1.34 9-3'),
+    ] },
+    google: { viewBox: '0 0 24 24', paint: 'none', shapes: [
+        ['path', { fill: '#4285F4', d: 'M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z' }],
+        ['path', { fill: '#34A853', d: 'M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z' }],
+        ['path', { fill: '#FBBC05', d: 'M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l3.66-2.84z' }],
+        ['path', { fill: '#EA4335', d: 'M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z' }],
+    ] },
+    microsoft: { viewBox: '0 0 21 21', paint: 'none', shapes: [
+        ['rect', { x: 1, y: 1, width: 9, height: 9, fill: '#F25022' }],
+        ['rect', { x: 11, y: 1, width: 9, height: 9, fill: '#7FBA00' }],
+        ['rect', { x: 1, y: 11, width: 9, height: 9, fill: '#00A4EF' }],
+        ['rect', { x: 11, y: 11, width: 9, height: 9, fill: '#FFB900' }],
+    ] },
+};
+
+/** The built-in set. */
+export const ICONS = new IconSet(ICON_DEFS);
+
+/** A built-in icon as an el() spec — `ICONS.spec(name, options)`. */
+export const icon = (name, options) => ICONS.spec(name, options);
+
+export { IconSet };

package/src/index.js

@@ -96,7 +96,7 @@ import { ArchimateSpecializationRegistry } from './archimateSpecializations.js';
 import { ArchimateSpecializationSelector } from './charting/ArchimateSpecializationSelector.js';
 import { ImageSelector } from './charting/ImageSelector.js';
 import { CheckboxTreeSelector } from './charting/CheckboxTreeSelector.js';
-import { SettingsManager, settingsManager } from './charting/SettingsManager.js';
+import { SettingsManager, settingsManager, TREE_SETTINGS_PROPERTIES } from './charting/SettingsManager.js';
 import { showGlobalSettingsDialog } from './charting/SettingsDialog.js';
 import { ArchimateModel, ArchimateView } from './charting/diagrams/ArchimateModel.js';
 import { CanvasView } from './charting/diagrams/CanvasView.js';
@@ -144,6 +144,7 @@ import { PopupMenu } from './charting/PopupMenu.js';
 import { ViewTabStrip } from './charting/ViewTabStrip.js';
 import { EditorShell } from './workspace/EditorShell.js';
 import { FormDialog } from './charting/FormDialog.js';
+import { Dialog } from './charting/Dialog.js';
 import { ColorField } from './charting/ColorField.js';
 import { TextStyle } from './charting/TextStyle.js';
 import { ArchimateModelChecker } from './charting/diagrams/ArchimateModelChecker.js';
@@ -158,6 +159,10 @@ import { PropertiesPanel } from './charting/PropertiesPanel.js';
 import { MenuBar } from './charting/MenuBar.js';
 import { ArchimateDiagramEditor } from './charting/ArchimateDiagramEditor.js';
 import { ModelTree } from './charting/modelTree/ModelTree.js';
+import { TreeBuilder } from './charting/modelTree/TreeBuilder.js';
+import { ContentSource } from './charting/content/ContentSource.js';
+import { ContentSources } from './charting/content/ContentSources.js';
+import { DUPLICATE_OPTIONS, NOISE_WORDS, FILLER_WORDS, duplicateGroups, duplicateKey, wordKey, nameKey } from './charting/diagrams/duplicates.js';
 import { TreeModeRegistry } from './charting/modelTree/TreeModeRegistry.js';
 import { TREE_MODE_CATALOG, treeModeRegistry, getTreeModeCatalogEntry } from './treeModeCatalog.js';
 import { buildModelTreePanel } from './charting/modelTree/ModelTreePanel.js';
@@ -166,7 +171,7 @@ import { buildTypeCategoryTree, buildPropertyTree } from './charting/modelTree/b
 import { DiagramTabs } from './charting/modelTree/DiagramTabs.js';
 import { DataModelNotation, DataModelLevel, AttributedLevel, ConceptualLevel, LogicalLevel, PhysicalLevel, NotationStyle, RelationshipKind, AssociationKind, GeneralizationKind, EntityRole, FactRole, DimensionRole } from './datamodel.js';
 import { DataModel, DataModelPerspective, DataModelContext, LevelSchema, LevelMapping, ServiceDomain, DataModelFileFormat, ServiceLandscape, BianLandscapeReader, BianSemanticApiReader, DataType, EnumerationType, StructuredType, NamingStandard, NameStyle, ClassificationScheme, ClassificationLens, SqlDdl, SqlDdlFileFormat, ModelScorecard, ScorecardCategory, MeasuredCategory } from './charting/datamodel/index.js';
-import { RequirementsModel, RequirementsChecker, RequirementsFileFormat, TrackerExportFileFormat, StoryboardFileFormat, TrackerExport, TRACKERS, Storyboard } from './charting/requirements/index.js';
+import { RequirementsModel, RequirementsChecker, RequirementsFileFormat, TrackerExportFileFormat, StoryboardFileFormat, TrackerExport, TRACKERS, Storyboard, TrackerApi, JiraApi, AzureDevOpsApi, GitLabApi, TRACKER_APIS, trackerApi, trackerConnectionFields } from './charting/requirements/index.js';
 import { EditableModel } from './charting/model/EditableModel.js';
 import { ModelEditCommand } from './charting/model/ModelEditCommand.js';
 import { Benchmark } from './charting/model/Benchmark.js';
@@ -215,20 +220,22 @@ export {
   TREE_MODE_CATALOG, treeModeRegistry, getTreeModeCatalogEntry,
   AXIS_KIND, ENCODING_CHANNEL, COORD_SYSTEM, COLOR_MODE, CAMERA_MODE,
   Command, CompositeCommand, CommandHistory,
-  DiagramEditor, DiagramEditorState, Template, PolygonTemplate, RegularPolygonTemplate, RectangleTemplate, RoundedRectangleTemplate, StadiumTemplate, PredefinedProcessTemplate, ClassTemplate, ComponentTemplate, SwimlaneTemplate, CircleTemplate, FinalStateTemplate, EllipseTemplate, DiamondTemplate, TriangleTemplate, PentagonTemplate, HexagonTemplate, OctagonTemplate, StarTemplate, ParallelogramTemplate, TrapezoidTemplate, ManualInputTemplate, CylinderTemplate, DocumentTemplate, NoteTemplate, CloudTemplate, ActorTemplate, PackageTemplate, BoxTemplate, DataStoreTemplate, LifelineTemplate, TemplateCatalog, Palette, PropertiesPanel, MenuBar, MoveElementCommand, BringToFrontCommand, SendToBackCommand, RaiseCommand, LowerCommand, CreateTemplateCommand, EditPropertyCommand, ResizeCommand, RotateCommand, SetPropertiesCommand, ReorderCommand, DIAGRAM_TYPES, getTemplatesForDiagramType, getAllDiagramTypes, getDiagramTypesByGroup, EdgeMarker, ArrowMarker, DiamondMarker, CircleMarker, CrowsFootMarker, HollowDiamondMarker, HollowTriangleMarker, OpenArrowMarker, HalfArrowMarker, EDGE_MARKERS, getEdgeMarker, Edge, AddEdgeCommand, DeleteEdgeCommand, ReconnectEdgeCommand, EDGE_STYLE_PROPERTIES, LINE_ONLY_PROPERTIES, LINE_STYLE_DASH, EdgeStyleCascade, SetStyleCommand, EdgeStyleDialog, DiagramModel, DiagramView, ViewSetModel, ViewMenu, ViewPropertiesDialog, SettingsViewPropertiesDialog, DiagramViewPropertiesDialog, inheritableFields, readInheritableFields, LocalJsonStore, PopupMenu, ViewTabStrip, EditorShell, FormDialog, ToolbarItem, ToolbarButton, ToolbarMenu, ToolbarSelect, ToolbarCheckbox, ToolbarText, ToolbarSeparator, pickFile, reorderedZ, stackingOrder, MoveWaypointCommand, AddWaypointCommand, DeleteWaypointCommand,
+  DiagramEditor, DiagramEditorState, Template, PolygonTemplate, RegularPolygonTemplate, RectangleTemplate, RoundedRectangleTemplate, StadiumTemplate, PredefinedProcessTemplate, ClassTemplate, ComponentTemplate, SwimlaneTemplate, CircleTemplate, FinalStateTemplate, EllipseTemplate, DiamondTemplate, TriangleTemplate, PentagonTemplate, HexagonTemplate, OctagonTemplate, StarTemplate, ParallelogramTemplate, TrapezoidTemplate, ManualInputTemplate, CylinderTemplate, DocumentTemplate, NoteTemplate, CloudTemplate, ActorTemplate, PackageTemplate, BoxTemplate, DataStoreTemplate, LifelineTemplate, TemplateCatalog, Palette, PropertiesPanel, MenuBar, MoveElementCommand, BringToFrontCommand, SendToBackCommand, RaiseCommand, LowerCommand, CreateTemplateCommand, EditPropertyCommand, ResizeCommand, RotateCommand, SetPropertiesCommand, ReorderCommand, DIAGRAM_TYPES, getTemplatesForDiagramType, getAllDiagramTypes, getDiagramTypesByGroup, EdgeMarker, ArrowMarker, DiamondMarker, CircleMarker, CrowsFootMarker, HollowDiamondMarker, HollowTriangleMarker, OpenArrowMarker, HalfArrowMarker, EDGE_MARKERS, getEdgeMarker, Edge, AddEdgeCommand, DeleteEdgeCommand, ReconnectEdgeCommand, EDGE_STYLE_PROPERTIES, LINE_ONLY_PROPERTIES, LINE_STYLE_DASH, EdgeStyleCascade, SetStyleCommand, EdgeStyleDialog, DiagramModel, DiagramView, ViewSetModel, ViewMenu, ViewPropertiesDialog, SettingsViewPropertiesDialog, DiagramViewPropertiesDialog, inheritableFields, readInheritableFields, LocalJsonStore, PopupMenu, ViewTabStrip, EditorShell, Dialog, FormDialog, ToolbarItem, ToolbarButton, ToolbarMenu, ToolbarSelect, ToolbarCheckbox, ToolbarText, ToolbarSeparator, pickFile, reorderedZ, stackingOrder, MoveWaypointCommand, AddWaypointCommand, DeleteWaypointCommand,
   ebnfAstToDiagram, parseEbnf,
   createDataWindow, GraphDataWindow,
   ArchimateNotation, ArchimateLayer, ArchimateElementType, ArchimateRelationshipType,
   Glyph, GLYPHS, glyphFor, drawGlyph, glyphElement, glyphToSvg, GlyphTemplate, ArchimateElementTemplate, ArchimateEdge, ArchimateCanvasEditor, ArchimatePalette, KIND_PREFERENCE, ARCHIMATE_TYPE_MIME,
   ArchimateModel, ArchimateView, CanvasView, PlaceItemsCommand, RemoveLineCommand, CanvasBoxKind, CANVAS_BOX_KINDS, canvasBoxKind, canvasBoxMenuItems, ArchiHint, HintPanel, EditHintCommand, hintMenuItems, CanvasPalette, CANVAS_BOX_MIME, ViewLineEdge, Arrangement, ItemGroup, BackgroundGroup, GroupCommand, UngroupCommand, LockCommand, BackgroundCommand, arrangeMenuItems, TemplateLibrary, CanvasTemplateLibrary, CanvasTemplateMenu, DEFAULT_CANVAS_TEMPLATES, canvasTemplate, EditViewItemCommand, viewItemChanges, ColorField, TextStyle, ArchimateModelChecker, ViewSetChecker, ViewFit, archiElementType, NEAREST_ARCHI_TYPE, ElementInstance, ViewObjectInstance, RelationshipInstance, ArchimateDiagramEditor,
   ITIconNotation, ITElementType,
-  ArchimateValidator, ArchimateSpecializationSelector, ImageSelector, CheckboxTreeSelector, SettingsManager, settingsManager,
-  ModelTree, TreeModeRegistry,
+  ArchimateValidator, ArchimateSpecializationSelector, ImageSelector, CheckboxTreeSelector, SettingsManager, settingsManager, TREE_SETTINGS_PROPERTIES,
+  ModelTree, TreeBuilder, TreeModeRegistry, ContentSource, ContentSources,
+  DUPLICATE_OPTIONS, NOISE_WORDS, FILLER_WORDS, duplicateGroups, duplicateKey, wordKey, nameKey,
   RadialLayout, DerivedRelationships, EdgeGeometry,
   buildModelTreePanel, buildAnalysisPanel, buildAnalysisData, buildTypeCategoryTree, buildPropertyTree, DiagramTabs,
   DataModelNotation, DataModelLevel, AttributedLevel, ConceptualLevel, LogicalLevel, PhysicalLevel, NotationStyle, RelationshipKind, AssociationKind, GeneralizationKind, EntityRole, FactRole, DimensionRole,
   DataModel, DataModelPerspective, DataModelContext, LevelSchema, LevelMapping, ServiceDomain, DataModelFileFormat, ServiceLandscape, BianLandscapeReader, BianSemanticApiReader, DataType, EnumerationType, StructuredType, NamingStandard, NameStyle, ClassificationScheme, ClassificationLens, SqlDdl, SqlDdlFileFormat, ModelScorecard, ScorecardCategory, MeasuredCategory,
   RequirementsModel, RequirementsChecker, RequirementsFileFormat, TrackerExportFileFormat, StoryboardFileFormat, TrackerExport, TRACKERS, Storyboard,
+  TrackerApi, JiraApi, AzureDevOpsApi, GitLabApi, TRACKER_APIS, trackerApi, trackerConnectionFields,
   EditableModel, ModelEditCommand, Benchmark,
   BianNotation, BianFunctionalPattern, BianActionTerm,
   exportElementsCSV, exportRelationshipsCSV, exportModelCSV,
@@ -250,6 +257,11 @@ export {
  * @class RenderEngine
  * This class decides which renderer to use and provides a unified drawing API.
  */
+// Navigation menus (a sidebar's): DOM built from JSON, safe to import under node.
+export { NavEntry, NavItem, NavGroup, NavSection, NavMenu } from './workspace/nav/index.js';
+// Named icons as data (an <svg> spec each); the built-in pool and its class.
+export { IconSet, ICONS, ICON_DEFS, icon } from './icons/index.js';
+
 export class RenderEngine {
     /** Layout constants for graphDiagram's `shape: 'table'` node type. */
     static TABLE_NODE = NodeGeometry.TABLE_NODE;
@@ -438,8 +450,12 @@ export class RenderEngine {
      * @param {HTMLElement} container The container element for the chart.
      * @param {object} [options]
      * @param {'canvas' | 'svg'} [options.rendererType='canvas']
+     * @param {false|{wheelModifier?: 'ctrl'|'alt'|'shift'}} [options.zoom] - SVG wheel zoom: off, or only
+     *   with a modifier held (so a plain wheel scrolls the page); on, with a plain wheel, by default
      */
     constructor(container, options = {}) {
+        // Kept: the engines refreshChart() makes for other containers are made with the same options.
+        this.options = options;
         if (container) {
             const { rendererType = 'canvas' } = options;
             const width = container.clientWidth;
@@ -447,11 +463,9 @@ export class RenderEngine {
     
             this.container = container; // Store container for event listeners
             this.renderer = RendererFactory.create(rendererType, container, width, height);
-        } else {
-            // Allow initialization without a container for testing
-            this.options = options;
-            console.log('RenderEngine initialized in test mode.');
         }
+        // No container: a test, or an engine keeping a page of registered
+        // charts, each drawn in its own element (refreshChart).
 
         if (this.container) {
             this._interactions = new InteractionManager(this);
@@ -2587,7 +2601,10 @@ export class RenderEngine {
 
     /**
      * Refreshes a registered chart, re-resolving its data and re-invoking
-     * its render method.
+     * its render method, in the element with that id: this engine's own
+     * container, or — so one engine can keep a page of charts — an engine of
+     * its own for that element, made with this engine's options and kept
+     * (so a zoom survives the next refresh) while the element is the same.
      * @param {string} id Chart container ID
      */
     refreshChart(id) {
@@ -2595,7 +2612,46 @@ export class RenderEngine {
         const config = this.registry[id];
         const container = document.getElementById(id);
         if (!container) return;
+        const target = this._engineFor(id, container);
+        if (target !== this) target.fitToContainer();
+        target._drawRegistered(config);
+    }
+
+    /** Every registered chart, refreshed. */
+    refreshAll() {
+        for (const id of Object.keys(this.registry ?? {})) this.refreshChart(id);
+    }
+
+    /**
+     * Set the data registered charts read by `dataPath`, and refresh them all —
+     * a live page's poll: `engine.setData(await fetchMetrics())`.
+     * @param {object} data
+     */
+    setData(data) {
+        this.setGlobalData(data);
+        this.refreshAll();
+    }
+
+    /** The engine that draws into `container` for registered chart `id`. @private */
+    _engineFor(id, container) {
+        if (container === this.container) return this;
+        this._childEngines ??= new Map();
+        let engine = this._childEngines.get(id);
+        if (engine?.container !== container) {
+            engine = this._newEngine(container);
+            this._childEngines.set(id, engine);
+        }
+        engine.globalData = this.globalData;
+        return engine;
+    }
+
+    /** An engine for another container, with this one's options. @private */
+    _newEngine(container) {
+        return new RenderEngine(container, this.options);
+    }
 
+    /** Draw a registration (`{type, options}`) with this engine. @private */
+    _drawRegistered(config) {
         // Catalog keys ('bar', 'heatmap', 'graph', 'archimate', ...) resolve
         // through the registries to their real method name; railroadDiagram
         // isn't a registry entry, so `type` already IS the method name there.
@@ -2612,6 +2668,7 @@ export class RenderEngine {
             this[methodName](config.options.nodes, config.options.edges || [], config.options);
         } else {
             const data = config.options.data || this.resolvePath(config.options.dataPath, config.options.dataMapper);
+            if (data === undefined) return; // registered before its data has arrived
             this[methodName](data, config.options);
         }
     }

package/src/workspace/dom.js

@@ -20,11 +20,20 @@
  *     on:       { click: fn },            // addEventListener
  *     children: [spec | Node | string],   // strings become text nodes
  *     ref:      (element) => {},          // capture the node without querySelector
+ *     ns:       SVG_NS,                   // the element's namespace (see below)
  *   }
  *
  * A bare string spec produces a text node, so `children: ['plain text']` works.
+ *
+ * An `svg` spec, and everything inside it, is built in the SVG namespace
+ * (`createElementNS`) — so a drawing or an icon is a spec too, never parsed
+ * markup — until a `foreignObject`, whose children are HTML again. `ns` sets
+ * a namespace explicitly (a `path` spec built on its own, to append to an
+ * existing <svg>).
  */
-export function el(spec, doc = document) {
+export const SVG_NS = 'http://www.w3.org/2000/svg';
+
+export function el(spec, doc = document, ns = null) {
     if (spec == null) return doc.createTextNode('');
     if (typeof spec === 'string' || typeof spec === 'number') return doc.createTextNode(String(spec));
     // Duck-typed rather than `instanceof Node`: `Node` is a browser global, so
@@ -32,11 +41,15 @@ export function el(spec, doc = document) {
     // substituted document. A spec object never carries either of these.
     if (typeof spec.nodeType === 'number' || typeof spec.appendChild === 'function') return spec;
 
-    const node = doc.createElement(spec.tag ?? 'div');
+    const tag = spec.tag ?? 'div';
+    const space = spec.ns ?? (tag === 'svg' ? SVG_NS : ns);
+    const node = space ? doc.createElementNS(space, tag) : doc.createElement(tag);
 
     if (spec.cls) {
-        const classes = Array.isArray(spec.cls) ? spec.cls : [spec.cls];
-        node.className = classes.filter(Boolean).join(' ');
+        const classes = (Array.isArray(spec.cls) ? spec.cls : [spec.cls]).filter(Boolean).join(' ');
+        // An SVG element's className is an SVGAnimatedString, not a string.
+        if (space) node.setAttribute('class', classes);
+        else node.className = classes;
     }
     if (spec.text != null) node.textContent = String(spec.text);
 
@@ -55,8 +68,9 @@ export function el(spec, doc = document) {
     for (const [event, handler] of Object.entries(spec.on ?? {})) {
         if (typeof handler === 'function') node.addEventListener(event, handler);
     }
+    const childSpace = space && tag !== 'foreignObject' ? space : null;
     for (const child of spec.children ?? []) {
-        node.appendChild(el(child, doc));
+        node.appendChild(el(child, doc, childSpace));
     }
 
     spec.ref?.(node);
@@ -81,40 +95,40 @@ export function render(host, specs, doc = document) {
 function cssProp(key) {
     return key.startsWith('--') ? key : key.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`);
 }
-
-const VOID_TAGS = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr']);
-const escapeHtml = (s) => String(s).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
-
-/**
- * The same spec as el(), written out as HTML text: for a page that is saved
- * rather than shown (a report). Text and attribute values are escaped; `on`
- * and `ref` have no meaning in text and are left out. `script` is the one
- * extra field: the trusted contents of a <script> or <style> (not escaped,
- * but `</` is, so it cannot close its element early).
- */
-export function toHtml(spec) {
-    if (spec == null) return '';
-    if (typeof spec === 'string' || typeof spec === 'number') return escapeHtml(spec);
-    if (Array.isArray(spec)) return spec.map(toHtml).join('');
-    const tag = spec.tag ?? 'div';
-    const attrs = [];
-    if (spec.cls) {
-        const classes = (Array.isArray(spec.cls) ? spec.cls : [spec.cls]).filter(Boolean);
-        if (classes.length) attrs.push(['class', classes.join(' ')]);
-    }
-    for (const [k, v] of Object.entries(spec.attrs ?? {})) {
-        if (v == null || v === false) continue;
-        attrs.push([k, v === true ? '' : String(v)]);
-    }
-    for (const [k, v] of Object.entries(spec.dataset ?? {})) {
-        if (v != null) attrs.push([`data-${cssProp(k)}`, String(v)]);
-    }
-    const style = Object.entries(spec.style ?? {}).filter(([, v]) => v != null).map(([k, v]) => `${cssProp(k)}: ${v}`).join('; ');
-    if (style) attrs.push(['style', style]);
-    const open = `<${tag}${attrs.map(([k, v]) => ` ${k}="${escapeHtml(v)}"`).join('')}>`;
-    if (VOID_TAGS.has(tag)) return open;
-    const inner = spec.script != null
-        ? String(spec.script).replace(/<\//g, '<\\/')
-        : (spec.text != null ? escapeHtml(spec.text) : '') + (spec.children ?? []).map(toHtml).join('');
-    return `${open}${inner}</${tag}>`;
-}
+
+const VOID_TAGS = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr']);
+const escapeHtml = (s) => String(s).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+
+/**
+ * The same spec as el(), written out as HTML text: for a page that is saved
+ * rather than shown (a report). Text and attribute values are escaped; `on`
+ * and `ref` have no meaning in text and are left out. `script` is the one
+ * extra field: the trusted contents of a <script> or <style> (not escaped,
+ * but `</` is, so it cannot close its element early).
+ */
+export function toHtml(spec) {
+    if (spec == null) return '';
+    if (typeof spec === 'string' || typeof spec === 'number') return escapeHtml(spec);
+    if (Array.isArray(spec)) return spec.map(toHtml).join('');
+    const tag = spec.tag ?? 'div';
+    const attrs = [];
+    if (spec.cls) {
+        const classes = (Array.isArray(spec.cls) ? spec.cls : [spec.cls]).filter(Boolean);
+        if (classes.length) attrs.push(['class', classes.join(' ')]);
+    }
+    for (const [k, v] of Object.entries(spec.attrs ?? {})) {
+        if (v == null || v === false) continue;
+        attrs.push([k, v === true ? '' : String(v)]);
+    }
+    for (const [k, v] of Object.entries(spec.dataset ?? {})) {
+        if (v != null) attrs.push([`data-${cssProp(k)}`, String(v)]);
+    }
+    const style = Object.entries(spec.style ?? {}).filter(([, v]) => v != null).map(([k, v]) => `${cssProp(k)}: ${v}`).join('; ');
+    if (style) attrs.push(['style', style]);
+    const open = `<${tag}${attrs.map(([k, v]) => ` ${k}="${escapeHtml(v)}"`).join('')}>`;
+    if (VOID_TAGS.has(tag)) return open;
+    const inner = spec.script != null
+        ? String(spec.script).replace(/<\//g, '<\\/')
+        : (spec.text != null ? escapeHtml(spec.text) : '') + (spec.children ?? []).map(toHtml).join('');
+    return `${open}${inner}</${tag}>`;
+}

package/src/workspace/index.js

@@ -42,7 +42,7 @@ export {
     ContextBus, Part, PartRegistry, PartFactory,
     ContentPart, HtmlPart, ListPart, DetailPart, AdapterPart, ModelsPart,
 };
-export { el, frag, render } from './dom.js';
+export { el, frag, render, SVG_NS } from './dom.js';
 
 // The engine's whole public API, re-exported so the workspace UMD bundle is a
 // superset of the main one: a page that loads renderengine-workspace.umd.js

package/src/workspace/nav/NavEntry.js

@@ -0,0 +1,42 @@
+/**
+ * NavEntry — one entry in a NavMenu: an item, a group of items, or a section
+ * heading. Subclasses return an el() spec; the menu builds every entry from
+ * JSON (NavMenu.entry), so a host writes its navigation as data, not markup.
+ *
+ * `visible` is a boolean or a function of the menu's context (`{ role }`, …),
+ * so one definition serves every user and the menu re-renders when the
+ * context changes (NavMenu#setContext).
+ */
+export class NavEntry {
+    /**
+     * @param {Object} [options]
+     * @param {string} [options.id]
+     * @param {string|string[]} [options.cls] - Extra class names
+     * @param {string} [options.title] - Tooltip
+     * @param {boolean|((context: Object) => boolean)} [options.visible]
+     */
+    constructor({ id = null, cls = null, title = null, visible = true } = {}) {
+        this.id = id;
+        this.cls = cls;
+        this.title = title;
+        this.visible = visible;
+    }
+
+    /** Whether the entry shows, given the menu's context. */
+    isVisible(menu) {
+        return typeof this.visible === 'function' ? !!this.visible(menu.context) : this.visible !== false;
+    }
+
+    /** @returns {Object} el() spec */
+    spec(menu) {
+        throw new Error(`${this.constructor.name} must implement spec()`);
+    }
+
+    /** The entries this one holds (a group's items); none by default. */
+    get children() { return []; }
+
+    /** Extra class names as a list, for el()'s `cls`. */
+    extraClasses() {
+        return Array.isArray(this.cls) ? this.cls : this.cls ? [this.cls] : [];
+    }
+}

package/src/workspace/nav/NavGroup.js

@@ -0,0 +1,43 @@
+import { NavEntry } from './NavEntry.js';
+
+/**
+ * NavGroup — entries under a heading that opens and closes (a `<details>`).
+ * Whether it is open is state the menu keeps (NavMenu#serialize) and reports
+ * (`onToggle`), so a host can remember it. Hidden when none of its entries
+ * shows.
+ */
+export class NavGroup extends NavEntry {
+    /**
+     * @param {Object} options
+     * @param {string} options.group - The heading's text
+     * @param {Array<Object|NavEntry>} options.items - Entries, as JSON or built
+     * @param {boolean} [options.open]
+     * @param {(json: Object) => NavEntry} entry - Builds an entry from JSON (NavMenu.entry)
+     */
+    constructor({ group, items = [], open = false, ...rest }, entry) {
+        super(rest);
+        this.label = group;
+        this.open = !!open;
+        this.items = items.map(entry);
+    }
+
+    get children() { return this.items; }
+
+    isVisible(menu) {
+        return super.isVisible(menu) && this.items.some(e => e.isVisible(menu));
+    }
+
+    spec(menu) {
+        return {
+            tag: 'details',
+            cls: ['ws-nav-group', ...this.extraClasses()],
+            attrs: { open: this.open },
+            dataset: { navId: this.id },
+            children: [
+                { tag: 'summary', cls: 'ws-nav-group-summary', text: this.label, attrs: { title: this.title } },
+                ...menu.specsOf(this.items),
+            ],
+            on: { toggle: (event) => menu.toggled(this, !!event.target.open) },
+        };
+    }
+}

package/src/workspace/nav/NavItem.js

@@ -0,0 +1,53 @@
+import { NavEntry } from './NavEntry.js';
+
+/**
+ * NavItem — a place to go or a thing to do. With `href` it is a link (the
+ * browser navigates, and the address can be opened in a new tab); without, a
+ * button. `action(event, item, menu)` runs on a click either way, and may
+ * call `event.preventDefault()` to keep a link from navigating — e.g. a
+ * modifier-click that opens the target beside the current view instead.
+ */
+export class NavItem extends NavEntry {
+    /**
+     * @param {Object} options
+     * @param {string} options.label
+     * @param {string} [options.icon] - Shown before the label, hidden from screen readers: an icon's
+     *   name in the menu's IconSet (`icons`), or text (an emoji)
+     * @param {string|((context: Object) => string|null)} [options.href] - Or a function of the menu's context (an address known later)
+     * @param {(event: Event, item: NavItem, menu: NavMenu) => void} [options.action]
+     * @param {boolean} [options.selectable] - Whether a click makes it the active item (default: true)
+     */
+    constructor({ label, icon = null, href = null, action = null, selectable = true, ...rest }) {
+        super(rest);
+        this.label = label;
+        this.icon = icon;
+        this.href = href;
+        this.action = action;
+        this.selectable = selectable;
+    }
+
+    spec(menu) {
+        const active = this.id != null && this.id === menu.activeId;
+        const href = typeof this.href === 'function' ? this.href(menu.context) : this.href;
+        return {
+            tag: href != null ? 'a' : 'button',
+            cls: ['ws-nav-item', active && 'ws-nav-item-active', ...this.extraClasses()],
+            attrs: {
+                href,
+                type: href != null ? null : 'button',
+                title: this.title,
+                'aria-current': active ? 'page' : null,
+            },
+            dataset: { navId: this.id },
+            children: [
+                this.icon != null && {
+                    tag: 'span', cls: 'ws-nav-icon', attrs: { 'aria-hidden': 'true' },
+                    ...(menu.icons?.has(this.icon) ? { children: [menu.icons.spec(this.icon, { size: 16 })] } : { text: this.icon }),
+                },
+                { tag: 'span', cls: 'ws-nav-label', text: this.label },
+            ].filter(Boolean),
+            on: { click: (event) => menu.select(this, event) },
+            ref: (n) => menu.nodes.set(this, n),
+        };
+    }
+}