@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/datamodel.js

@@ -0,0 +1,122 @@
+// Copyright 2026 Jaroslav Peter Prib, Purveyor of Excellence
+/**
+ * Data-modelling notation — deliberately its own file/OO module, same split
+ * as src/archimate.js: keeps this domain's vocabulary (levels, notation
+ * styles, cardinality) out of RenderEngine itself, queried through the
+ * `DataModelNotation` registry rather than flat string-keyed maps.
+ *
+ * **Three levels, one entity.** A conceptual/logical/physical data model
+ * isn't three unrelated diagrams — it's the same entities and relationships
+ * shown at increasing fidelity. `dataModelDiagram` (see RenderEngine)
+ * expresses that as ONE entity object carrying per-level detail
+ * (`entity.logical.attributes`, `entity.physical.attributes`, ...) under a
+ * shared `name`/`description` — the same "object" (level-agnostic identity)
+ * vs "visual/detail" (this level's own presentation) split archimateDiagram
+ * already draws between an element and its diagram — with `options.level`
+ * picking which one's on screen. That's the cross-mapping: switching level
+ * re-renders the SAME entities/relationships, not a second, separately
+ * maintained diagram, so a conceptual entity, its logical attributes, and
+ * its physical column types can never drift out of correspondence.
+ *
+ * **Three notations, one cardinality vocabulary.** A relationship's
+ * cardinality at each end is stored once, as a UML-style multiplicity
+ * string (`'0..1'|'1'|'0..*'|'*'|'1..*'`) — CARDINALITIES below — and each
+ * `NotationStyle` renders it its own way: Chen turns the relationship
+ * itself into a diamond-shaped node with a plain text label ('1'/'N') on
+ * each connecting edge; Crow's Foot renders it as an arrowhead-style glyph
+ * at the entity end (fork for "many", tick for "one", circle for
+ * "optional" — see the `crowsfoot-*` markers in SVGRenderer.js); UML shows
+ * the multiplicity string itself as a text label near that end
+ * (`edge.sourceLabel`/`targetLabel`, a plain graphDiagram feature, not
+ * data-model-specific). None of these are pixel-perfect renditions of the
+ * real notations' full rule set (Chen's own attribute-oval convention,
+ * every crow's-foot optionality combination, UML's aggregation/composition
+ * diamonds) — they're a representative, genuinely-readable version of each,
+ * the same calibration archimateDiagram's own icons use.
+ */
+
+/** One data-modelling abstraction level. See DataModelNotation.levels(). */
+export class DataModelLevel {
+    constructor(name, description) {
+        this.name = name;
+        this.description = description;
+    }
+}
+
+/** The canonical cardinality vocabulary every NotationStyle renders
+ *  differently — UML-style multiplicity strings, since they're the only one
+ *  of the three notations expressive enough to BE the canonical form
+ *  without losing information (Chen/Crow's Foot each collapse some of these
+ *  distinctions on purpose). */
+const CARDINALITIES = new Set(['0..1', '1', '0..*', '*', '1..*']);
+
+function chenCardinalityLabel(cardinality) {
+    return cardinality === '1' || cardinality === '0..1' ? '1' : 'N';
+}
+
+const CROWSFOOT_ARROWHEADS = {
+    '1': 'crowsfoot-one',
+    '0..1': 'crowsfoot-one-optional',
+    '1..*': 'crowsfoot-many-mandatory',
+    '0..*': 'crowsfoot-many',
+    '*': 'crowsfoot-many',
+};
+
+/**
+ * One drawing technique for entities/relationships — Chen, Crow's Foot, or
+ * UML (class-diagram style). `entityShape` picks the graphDiagram node shape
+ * (`'rect'` for a plain box, `'table'` for a header + attribute-rows card);
+ * `relationshipAsNode` (Chen only) turns a relationship into its own
+ * diamond-shaped node with two plain edges instead of one direct edge;
+ * `cardinalityArrowhead`/`cardinalityLabel` (each `(cardinality) => value or
+ * undefined`) pick how a relationship's own cardinality at one end renders
+ * — at most one of the two is ever set for a given notation, the other
+ * always returns undefined.
+ */
+export class NotationStyle {
+    constructor(name, { entityShape, relationshipAsNode, cardinalityArrowhead, cardinalityLabel }) {
+        this.name = name;
+        this.entityShape = entityShape;
+        this.relationshipAsNode = relationshipAsNode;
+        this.cardinalityArrowhead = cardinalityArrowhead;
+        this.cardinalityLabel = cardinalityLabel;
+    }
+}
+
+const LEVELS = {
+    conceptual: new DataModelLevel('conceptual', 'Entities and their relationships only — no attributes, no keys, no types.'),
+    logical: new DataModelLevel('logical', 'Attributes and keys, still database-agnostic — no column types or engine specifics.'),
+    physical: new DataModelLevel('physical', 'Real column types, keys, and constraints as they exist in an actual database.'),
+};
+
+const NOTATIONS = {
+    chen: new NotationStyle('chen', {
+        entityShape: 'rect',
+        relationshipAsNode: true,
+        cardinalityArrowhead: () => undefined,
+        cardinalityLabel: chenCardinalityLabel,
+    }),
+    crowsfoot: new NotationStyle('crowsfoot', {
+        entityShape: 'table',
+        relationshipAsNode: false,
+        cardinalityArrowhead: (cardinality) => CROWSFOOT_ARROWHEADS[cardinality],
+        cardinalityLabel: () => undefined,
+    }),
+    uml: new NotationStyle('uml', {
+        entityShape: 'table',
+        relationshipAsNode: false,
+        cardinalityArrowhead: () => undefined,
+        cardinalityLabel: (cardinality) => cardinality,
+    }),
+};
+
+export const DataModelNotation = {
+    levels() { return Object.values(LEVELS); },
+    levelNames() { return Object.keys(LEVELS); },
+    level(name) { return LEVELS[name]; },
+    notations() { return Object.values(NOTATIONS); },
+    notationNames() { return Object.keys(NOTATIONS); },
+    notation(name) { return NOTATIONS[name] || NOTATIONS.crowsfoot; },
+    isCardinality(value) { return CARDINALITIES.has(value); },
+    cardinalities() { return [...CARDINALITIES]; },
+};

package/src/datawindow/BoundedWindow.js

@@ -0,0 +1,36 @@
+/**
+ * Abstract base for "own a bounded collection, push one more item, drop the
+ * oldest once past a cap" — the one behavior every streamable chart data
+ * shape shares, however differently each stores its collection(s). See
+ * ARCHITECTURE.md's "Data windows — streaming" section for the concrete
+ * subtypes and why each exists as its own class rather than a branch here.
+ */
+export class BoundedWindow {
+  constructor({ max = 0 } = {}) {
+    this.max = max;
+  }
+
+  /**
+   * Template method: append via `_append`, then trim via `_trim` — but only
+   * when `max` is truthy, so `max: 0` means "unbounded" without every
+   * subclass needing its own guard.
+   * @returns {*} the window's current `data` after the push.
+   */
+  push(...args) {
+    this._append(...args);
+    if (this.max) this._trim();
+    return this.data;
+  }
+
+  _append() {
+    throw new Error('_append must be implemented by a subclass');
+  }
+
+  _trim() {
+    throw new Error('_trim must be implemented by a subclass');
+  }
+
+  get data() {
+    throw new Error('data must be implemented by a subclass');
+  }
+}

package/src/datawindow/FlatDataWindow.js

@@ -0,0 +1,34 @@
+import { BoundedWindow } from './BoundedWindow.js';
+
+/**
+ * A single flat array of points — the shape behind `bar`, `pie`, `scatter`,
+ * `bubble`, `candlestick`, `funnel`, `waterfall`, `histogram`, `qq`, `lag`,
+ * `treemap`, `sunburst`, `outline`, `stackedBar`, `bar3D`, `bubble3D` (see
+ * `streamShape: 'flat'` in `chartCatalog.js`). One new record is appended to
+ * the outer array per push; trimming drops the oldest records FIFO.
+ */
+export class FlatDataWindow extends BoundedWindow {
+  constructor(initialData, options = {}) {
+    super(options);
+    this._data = initialData;
+  }
+
+  get data() {
+    return this._data;
+  }
+
+  /**
+   * @param {*|function(Array):*} pointOrFactory A literal point, or a
+   *   function of the current data array — needed by shapes like
+   *   `candlestick`, where the next bar continues from the previous bar's
+   *   `close`.
+   */
+  _append(pointOrFactory) {
+    const point = typeof pointOrFactory === 'function' ? pointOrFactory(this._data) : pointOrFactory;
+    this._data = [...this._data, point];
+  }
+
+  _trim() {
+    this._data = this._data.slice(-this.max);
+  }
+}

package/src/datawindow/GraphDataWindow.js

@@ -0,0 +1,40 @@
+import { BoundedWindow } from './BoundedWindow.js';
+
+/**
+ * A nodes+edges pair — the shape behind `graphDiagram`/`graphDiagram3D`.
+ * Not a `CHART_CATALOG` entry (see ARCHITECTURE.md), so it isn't dispatched
+ * through `createDataWindow`/`streamShape`; `RenderEngine.addGraphNode`
+ * constructs it directly. Trimming drops the oldest nodes FIFO, then any
+ * edge left dangling off a removed node — dropping nodes without this would
+ * leave edges pointing at ids that no longer exist.
+ */
+export class GraphDataWindow extends BoundedWindow {
+  constructor({ nodes, edges }, options = {}) {
+    super(options);
+    this._nodes = nodes;
+    this._edges = edges;
+  }
+
+  get data() {
+    return { nodes: this._nodes, edges: this._edges };
+  }
+
+  get nodes() {
+    return this._nodes;
+  }
+
+  get edges() {
+    return this._edges;
+  }
+
+  _append(node, newEdges = []) {
+    this._nodes = [...this._nodes, node];
+    this._edges = [...this._edges, ...newEdges];
+  }
+
+  _trim() {
+    this._nodes = this._nodes.slice(-this.max);
+    const keepIds = new Set(this._nodes.map((n) => n.id));
+    this._edges = this._edges.filter((e) => keepIds.has(e.source) && keepIds.has(e.target));
+  }
+}

package/src/datawindow/GroupedSampleDataWindow.js

@@ -0,0 +1,16 @@
+import { SeriesDataWindow } from './SeriesDataWindow.js';
+
+/**
+ * Same storage shape as `SeriesDataWindow` (`Array<{label, values:[]}>`) but
+ * only ONE randomly-chosen group grows per push — the shape behind
+ * `boxPlot`, `density`, `violin` (see `streamShape: 'grouped-sample'` in
+ * `chartCatalog.js`). A new sample observation belongs to one group, unlike
+ * `line`/`area`/`pipe`'s shared time axis where every series advances
+ * together — the entire behavioral difference from the base class is which
+ * indices get targeted, so that's the only method this subclass overrides.
+ */
+export class GroupedSampleDataWindow extends SeriesDataWindow {
+  _targetIndices() {
+    return this._data.length ? [Math.floor(Math.random() * this._data.length)] : [];
+  }
+}

package/src/datawindow/SeriesDataWindow.js

@@ -0,0 +1,42 @@
+import { BoundedWindow } from './BoundedWindow.js';
+
+/**
+ * `Array<{name|label, values:[]}>` — the shape behind `line`, `area`, `pipe`
+ * (see `streamShape: 'series'` in `chartCatalog.js`). Every targeted series'
+ * own `values` grows by one point per push; the outer array (series count)
+ * is never trimmed by `max`, only each series' own `values`.
+ *
+ * `_targetIndices()` is the one seam a subtype overrides — see
+ * `GroupedSampleDataWindow`, which is this same storage shape but grows
+ * exactly one random series per push instead of all of them.
+ */
+export class SeriesDataWindow extends BoundedWindow {
+  constructor(initialData, options = {}) {
+    super(options);
+    this._data = initialData;
+  }
+
+  get data() {
+    return this._data;
+  }
+
+  /** Which series indices receive the new point this push. Default: all of them. */
+  _targetIndices() {
+    return this._data.map((_, i) => i);
+  }
+
+  /**
+   * @param {*|function(object,number,Array):*} pointOrFactory A literal
+   *   point (used for every targeted series), or a factory called once per
+   *   targeted series as `(series, index, data)`.
+   */
+  _append(pointOrFactory) {
+    const make = typeof pointOrFactory === 'function' ? pointOrFactory : () => pointOrFactory;
+    const targets = new Set(this._targetIndices());
+    this._data = this._data.map((s, i) => (targets.has(i) ? { ...s, values: [...s.values, make(s, i, this._data)] } : s));
+  }
+
+  _trim() {
+    this._data = this._data.map((s) => ({ ...s, values: s.values.slice(-this.max) }));
+  }
+}

package/src/datawindow/index.js

@@ -0,0 +1,31 @@
+/**
+ * `createDataWindow` is the Strategy/Factory that turns a `CHART_CATALOG`
+ * entry's `streamShape` into the right window instance — adding a future
+ * shape is one new class (see the others in this directory) plus one map
+ * entry here, not a new branch scattered through `RenderEngine`.
+ */
+import { FlatDataWindow } from './FlatDataWindow.js';
+import { SeriesDataWindow } from './SeriesDataWindow.js';
+import { GroupedSampleDataWindow } from './GroupedSampleDataWindow.js';
+
+export { BoundedWindow } from './BoundedWindow.js';
+export { FlatDataWindow, SeriesDataWindow, GroupedSampleDataWindow };
+export { GraphDataWindow } from './GraphDataWindow.js';
+
+const WINDOW_CLASSES = {
+  flat: FlatDataWindow,
+  series: SeriesDataWindow,
+  'grouped-sample': GroupedSampleDataWindow,
+};
+
+/**
+ * @param {string} streamShape One of `CHART_CATALOG`'s `streamShape` values.
+ * @param {*} initialData The chart's current data array.
+ * @param {{max?: number}} [options]
+ * @returns {import('./BoundedWindow.js').BoundedWindow|null} `null` for
+ *   `'none'` (or any other unrecognized shape) — not streamable.
+ */
+export function createDataWindow(streamShape, initialData, options) {
+  const Ctor = WINDOW_CLASSES[streamShape];
+  return Ctor ? new Ctor(initialData, options) : null;
+}

package/src/diagramCatalog.js

@@ -0,0 +1,30 @@
+/**
+ * Single source of truth for "what diagram types does RenderEngine support".
+ *
+ * Mirrors src/chartCatalog.js: the registry is the object-oriented lookup
+ * layer over the flat catalog, and `getDiagramCatalogEntry` is the legacy-style
+ * helper kept for backward compatibility.
+ */
+
+import { DiagramRegistry } from './charting/DiagramRegistry.js';
+import { GraphDiagram } from './charting/diagrams/GraphDiagram.js';
+import { GraphDiagram3D } from './charting/diagrams/GraphDiagram3D.js';
+import { ArchimateDiagram } from './charting/diagrams/ArchimateDiagram.js';
+import { DataModelDiagram } from './charting/diagrams/DataModelDiagram.js';
+import { EbnfDiagram } from './charting/diagrams/EbnfDiagram.js';
+
+export const DIAGRAM_CATALOG = [
+    { key: 'graph', method: 'graphDiagram', DiagramClass: GraphDiagram },
+    { key: 'graph3d', method: 'graphDiagram3D', DiagramClass: GraphDiagram3D },
+    { key: 'archimate', method: 'archimateDiagram', DiagramClass: ArchimateDiagram },
+    { key: 'dataModel', method: 'dataModelDiagram', DiagramClass: DataModelDiagram },
+    { key: 'ebnf', method: 'ebnfDiagram', DiagramClass: EbnfDiagram },
+];
+
+/** Canonical registry instance seeded with the built-in diagram types. */
+export const diagramRegistry = new DiagramRegistry(DIAGRAM_CATALOG);
+
+/** Look up one catalog entry by key, or undefined if the key is unknown. */
+export function getDiagramCatalogEntry(key) {
+    return diagramRegistry.get(key);
+}

package/src/ebnfDiagram.js

@@ -0,0 +1,57 @@
+// Converts an already-parsed EBNF AST (the shape sibling project `bnfengine`
+// produces — see its `_parseExpression`/`_parseTokens`) into a
+// railroadDiagram.js Diagram-node tree, for rendering via
+// RenderEngine.railroadDiagram()/.ebnfDiagram(). Rendering only — this file
+// does no text parsing of its own, by design; it consumes a tree that was
+// already built elsewhere.
+//
+// bnfengine's 7 node shapes (confirmed by reading its parser source, not
+// guessed):
+//   Terminal     {type:'Terminal', value}
+//   NonTerminal  {type:'NonTerminal', value}
+//   Sequence     {type:'Sequence', items:[...]}
+//   Choice       {type:'Choice', options:[...]}
+//   Optional     {type:'Optional', content}      -- from [ ... ]
+//   Repetition   {type:'Repetition', content}     -- from { ... }
+//   Group        {type:'Group', content}          -- from ( ... )
+
+import { Sequence, Choice, Optional, ZeroOrMore, Terminal, NonTerminal } from './railroadDiagram.js';
+
+/**
+ * @param {object} node A bnfengine-shaped EBNF AST node (see file header).
+ * @returns {object} The equivalent railroadDiagram.js Diagram-tree node.
+ * @throws {Error} for an unrecognized `node.type`.
+ */
+export function ebnfAstToDiagram(node) {
+    switch (node.type) {
+        case 'Terminal':
+            return Terminal(node.value);
+        case 'NonTerminal':
+            return NonTerminal(node.value);
+        case 'Sequence':
+            return Sequence(...node.items.map(ebnfAstToDiagram));
+        case 'Choice':
+            // The leading `normal` arg picks the "straight line" alternative
+            // in the original upstream railroad-diagrams library, but this
+            // simplified port's own Choice format() never reads it (only
+            // `.items` drives layout) — 0 is passed for clarity, not
+            // because it has any effect today.
+            return Choice(0, ...node.options.map(ebnfAstToDiagram));
+        case 'Optional':
+            return Optional(ebnfAstToDiagram(node.content));
+        case 'Repetition':
+            // bnfengine's own executor has no working semantics for `{...}`
+            // to confirm against (a separate, pre-existing bug in its
+            // interpreter, irrelevant to this adapter, which only reads the
+            // parse-tree shape) — mapped to the standard ISO/EBNF reading of
+            // curly-brace repetition: zero-or-more.
+            return ZeroOrMore(ebnfAstToDiagram(node.content));
+        case 'Group':
+            // Pure grouping/precedence — parentheses have no railroad-diagram
+            // visual of their own; the tree nesting already captures what
+            // they mean, so this is transparent (no wrapper node).
+            return ebnfAstToDiagram(node.content);
+        default:
+            throw new Error(`ebnfAstToDiagram: unknown EBNF AST node type "${node.type}"`);
+    }
+}

package/src/ebnfParser.js

@@ -0,0 +1,129 @@
+// Parses a small, standard EBNF grammar-rule text (matching common railroad-
+// diagram reference notation, e.g.
+// `DOUBLE ::= ( [0-9]+ ( '.' [0-9]* )? | '.' [0-9]+ ) EXPONENT`) into the
+// same AST shape ebnfDiagram.js's `ebnfAstToDiagram` already consumes (see
+// that file's own header for the full node-shape reference). Deliberately
+// not built on bnfengine's own parser: confirmed by reading its source
+// directly that it has no support at all for postfix ?/*/+ quantifiers —
+// every such character becomes its own stray Terminal literal instead of
+// being interpreted — disqualifying, since those quantifiers are exactly
+// what most real grammar rules need.
+//
+// Grammar:
+//   statement    := (IDENT '::=')? alternation
+//   alternation  := sequence ('|' sequence)*
+//   sequence     := factor+
+//   factor       := atom ('?' | '*' | '+')?
+//   atom         := STRING | BRACKET | IDENT | '(' alternation ')'
+//   STRING       := "'" [^']* "'" | '"' [^"]* '"'
+//   BRACKET      := '[' [^\]]* ']'          -- a character class, e.g.
+//                                              [0-9] — a literal, not a
+//                                              rule reference
+//   IDENT        := [A-Za-z_][A-Za-z0-9_-]*  -- a bare word is a
+//                                                NONTERMINAL (rule
+//                                                reference)
+
+const TOKEN_RE = /::=|[|?*+()]|'[^']*'|"[^"]*"|\[[^\]]*\]|[A-Za-z_][A-Za-z0-9_-]*/y;
+
+/** @private Splits `text` into a flat token array, skipping whitespace. */
+function tokenize(text) {
+    const tokens = [];
+    let pos = 0;
+    while (pos < text.length) {
+        while (pos < text.length && /\s/.test(text[pos])) pos++;
+        if (pos >= text.length) break;
+        TOKEN_RE.lastIndex = pos;
+        const m = TOKEN_RE.exec(text);
+        if (!m || m.index !== pos) {
+            throw new Error(`parseEbnf: unexpected character at position ${pos}: "${text[pos]}"`);
+        }
+        tokens.push(m[0]);
+        pos = TOKEN_RE.lastIndex;
+    }
+    return tokens;
+}
+
+/** @private Recursive-descent parse over an already-tokenized array. */
+function parseTokens(tokens) {
+    let i = 0;
+    const peek = () => tokens[i];
+    const next = () => tokens[i++];
+    const expect = (tok) => {
+        if (tokens[i] !== tok) throw new Error(`parseEbnf: expected "${tok}" but got "${tokens[i] ?? '<end of input>'}"`);
+        i++;
+    };
+
+    function parseStatement() {
+        let name = null;
+        if (tokens[i + 1] === '::=' && /^[A-Za-z_]/.test(tokens[i] || '')) {
+            name = next();
+            expect('::=');
+        }
+        const ast = parseAlternation();
+        if (i < tokens.length) throw new Error(`parseEbnf: unexpected trailing token "${tokens[i]}"`);
+        return { name, ast };
+    }
+
+    function parseAlternation() {
+        const branches = [parseSequence()];
+        while (peek() === '|') { next(); branches.push(parseSequence()); }
+        return branches.length === 1 ? branches[0] : { type: 'Choice', options: branches };
+    }
+
+    function parseSequence() {
+        const factors = [parseFactor()];
+        while (peek() && peek() !== '|' && peek() !== ')') factors.push(parseFactor());
+        return factors.length === 1 ? factors[0] : { type: 'Sequence', items: factors };
+    }
+
+    function parseFactor() {
+        const atom = parseAtom();
+        const q = peek();
+        if (q === '?') { next(); return { type: 'Optional', content: atom }; }
+        if (q === '*') { next(); return { type: 'Repetition', content: atom }; }
+        // `+` (one-or-more) desugars to "one mandatory pass, then zero-or-
+        // more more" — reuses only Sequence/Repetition (both already fixed
+        // and verified this session) instead of a dedicated OneOrMore AST
+        // node, which would resurrect railroadDiagram.js's own
+        // FORMATTERS.OneOrMore — still carrying its original, never
+        // exercised or fixed, likely-broken arc geometry (nothing used it
+        // before this parser existed).
+        if (q === '+') { next(); return { type: 'Sequence', items: [atom, { type: 'Repetition', content: atom }] }; }
+        return atom;
+    }
+
+    function parseAtom() {
+        const tok = next();
+        if (tok === undefined) throw new Error('parseEbnf: unexpected end of input');
+        if (tok === '(') {
+            const inner = parseAlternation();
+            expect(')');
+            return inner;
+        }
+        if ((tok[0] === "'" && tok[tok.length - 1] === "'") || (tok[0] === '"' && tok[tok.length - 1] === '"')) {
+            return { type: 'Terminal', value: tok.slice(1, -1) };
+        }
+        if (tok[0] === '[' && tok[tok.length - 1] === ']') {
+            return { type: 'Terminal', value: tok };
+        }
+        if (/^[A-Za-z_][A-Za-z0-9_-]*$/.test(tok)) {
+            return { type: 'NonTerminal', value: tok };
+        }
+        throw new Error(`parseEbnf: unexpected token "${tok}"`);
+    }
+
+    return parseStatement();
+}
+
+/**
+ * @param {string} text EBNF rule text, e.g. `DOUBLE ::= [0-9]+ ('.' [0-9]*)?`.
+ * @returns {{name: string|null, ast: object}} `name` is the leading
+ *   `IDENT ::=` rule name if present, else `null`. `ast` is the same
+ *   bnfengine-shaped node tree `ebnfAstToDiagram` consumes.
+ * @throws {Error} on malformed input, with a position/token in the message.
+ */
+export function parseEbnf(text) {
+    const tokens = tokenize(text);
+    if (tokens.length === 0) throw new Error('parseEbnf: empty input');
+    return parseTokens(tokens);
+}