Merge pull request finos#1670 from LeighFinegold/block-architecture-shapes

feat(calm-widgets): Node Type Visual Differentiation for Block Architecture Widget

Author: rocketstack-matt

calm-widgets/README.md

@@ -1,6 +1,6 @@
 # CALM Widgets Framework
 
-A TypeScript widget system built on Handlebars that provides reusable components for generating Markdown documentation. The framework allows you to create custom widgets that can transform data into formatted output using Handlebars templates.
+A TypeScript widget system built on Handlebars that provides reusable components for generating Markdown documentation. The framework allows you to create custom widgets.
 
 ## 🔧 Built-in Widgets
 
@@ -155,6 +155,12 @@ Renders a system architecture as a Mermaid flowchart with optional containers (s
 
 {{!-- Collapse multiple relationships between same source-target pairs --}}
 {{block-architecture this collapse-relationships=true}}
+
+{{!-- Render nodes with different shapes based on node-type --}}
+{{block-architecture this render-node-type-shapes=true}}
+
+{{!-- Custom node type mapping to built-in shapes --}}
+{{block-architecture this render-node-type-shapes=true node-type-map='{"cache": "database", "queue": "messagebus", "proxy": "service"}'}}
 ```
 
 **What it shows**
@@ -172,7 +178,10 @@ Renders a system architecture as a Mermaid flowchart with optional containers (s
 | `focus-relationships` | string (CSV) | — | Restrict view to the specified relationship unique-ids. Only those relationships and the nodes they connect are included (plus containers per settings). |
 | `focus-flows`         | string (CSV) | — | Restrict edges to transitions that belong to the given **flow unique-ids or names** (case-insensitive). Only nodes touching those edges are included (plus containers per settings). |
 | `focus-controls`      | string (CSV) | — | Restrict view to nodes and relationships linked to the specified control IDs. Only nodes touching those controls are included (plus containers per settings). |
-| `focus-interfaces`    | string (CSV) | — | Restrict view to nodes and relationships linked to the specified interface IDs. Only nodes touching those interfaces are included (plus containers per settings). || `highlight-nodes`     | string (CSV) | — | Nodes to visually highlight. |
+| `focus-interfaces`    | string (CSV) | — | Restrict view to nodes and relationships linked to the specified interface IDs. Only nodes touching those interfaces are included (plus containers per settings). |
+| `highlight-nodes`     | string (CSV) | — | Nodes to visually highlight. |
+| `render-node-type-shapes` | boolean | `false` | If `true`, render nodes with different Mermaid shapes based on their `node-type`. Supports built-in CALM types: `actor`, `database`, `webclient`, `service`, `system`, `messagebus`. |
+| `node-type-map`       | stringified JSON map | — | Custom mapping of node types to built-in shapes, e.g. `{"cache": "database", "queue": "messagebus"}`. Only used when `render-node-type-shapes` is `true`. |
 | `render-interfaces`   | boolean | `false` | If `true`, render each node’s `interfaces` as small interface boxes connected by dotted lines. |
 | `include-containers`  | `'none' \| 'parents' \| 'all'` | `'all'` | Which containers (systems) to draw. |
 | `include-children`    | `'none' \| 'direct' \| 'all'` | `'all'` | When focusing container nodes, include their direct/all descendants. |
@@ -184,6 +193,17 @@ Renders a system architecture as a Mermaid flowchart with optional containers (s
 | `link-prefix`         | string | — | Prefix for clickable `click` links in Mermaid (e.g., `/docs/` makes `/docs/<node-id>`). |
 | `link-map`            | stringified JSON map | — | Explicit per-id links, e.g. `{"trade-svc": "/svc/trade"}`. Map entries override `link-prefix`. |
 
+**Built-in Node Type Shapes**
+
+When `render-node-type-shapes` is enabled, the following CALM node types are rendered with distinctive Mermaid shapes:
+
+- `actor` → Circle with person icon 👤
+- `database` → Cylinder shape with database icon 🗄️
+- `webclient` → Rectangle with web icon 💻
+- `service` → Rounded rectangle with gear icon ⚙️
+- `system` → Rectangle with system icon 🏢
+- `messagebus` → horizontal cylinder with web icon 📨  - this isn't in schema but think we need it
+
 > **Sorting:** Containers and nodes are always sorted **alphabetically by label** for stable layouts.
 
 **Context requirements**
@@ -198,6 +218,8 @@ For more examples, see the test fixtures:
 - [Interface variations](./test-fixtures/block-architecture-widget/interface-variations/)
 - [Focus flows](./test-fixtures/block-architecture-widget/focus-flows/)
 - [Domain interaction](./test-fixtures/block-architecture-widget/domain-interaction/)
+- [Node type shapes](./test-fixtures/block-architecture-widget/node-type-shapes/)
+- [Custom node type mapping](./test-fixtures/block-architecture-widget/custom-node-type-map/)
 
 #### Example block architecture diagram with interfaces
 

calm-widgets/src/widgets.e2e.spec.ts

@@ -309,5 +309,12 @@ describe('Widgets E2E - Handlebars Integration', () => {
             const result = compiled(context);
             expect(result.trim()).toBe(expected);
         });
+
+        it('renders nodes with type-specific shapes and colors when render-node-type-shapes option is enabled', () => {
+            const { context, template, expected } = fixtures.loadFixture('block-architecture-widget', 'node-type-shapes');
+            const compiled = handlebars.compile(template);
+            const result = compiled(context);
+            expect(result.trim()).toBe(expected);
+        });
     });
 });

calm-widgets/src/widgets/block-architecture/block-architecture.hbs

@@ -5,6 +5,14 @@ classDef boundary fill:#f8fafc,stroke:#64748b,stroke-dasharray: 5 4,stroke-width
 classDef node fill:#ffffff,stroke:#1f2937,stroke-width:1px,color:#000;
 classDef iface fill:#f1f5f9,stroke:#64748b,stroke-width:1px,font-size:10px,color:#000;
 classDef highlight fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#000;
+{{#if renderNodeTypeShapes}}
+classDef actor fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000;
+classDef database fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000;
+classDef webclient fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000;
+classDef service fill:#e8f5e8,stroke:#388e3c,stroke-width:2px,color:#000;
+classDef messagebus fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#000;
+classDef system fill:#fff8e1,stroke:#f9a825,stroke-width:2px,color:#000;
+{{/if}}
 
 {{!-- Render container forest (if any) --}}
 {{#each containers}}
@@ -13,7 +21,11 @@ classDef highlight fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#000;
 
 {{!-- Render loose nodes (not inside any rendered container) --}}
 {{#each looseNodes}}
+    {{#if ../renderNodeTypeShapes}}
+    {{> typed-node.hbs}}
+    {{else}}
     {{id}}["{{label}}"]:::node
+    {{/if}}
     {{#each interfaces}}
         {{id}}["{{label}}"]:::iface
     {{/each}}

calm-widgets/src/widgets/block-architecture/container.hbs

@@ -3,7 +3,11 @@
     subgraph {{id}}["{{label}}"]
     direction TB
     {{#each nodes}}
+    {{#if @root.renderNodeTypeShapes}}
+        {{> typed-node.hbs}}
+    {{else}}
         {{id}}["{{label}}"]:::node
+    {{/if}}
         {{#each interfaces}}
             {{id}}["{{label}}"]:::iface
         {{/each}}

calm-widgets/src/widgets/block-architecture/core/builders/container-builder.ts

@@ -40,6 +40,7 @@ export function buildContainerForest(
         vmContainers.set(id, {
             id,
             label: labelFor(node, id),
+            nodeType: node?.['node-type'],
             nodes: [],
             containers: [],
         });

calm-widgets/src/widgets/block-architecture/core/factories/node-factory.ts

@@ -1,7 +1,7 @@
 import { CalmNodeCanonicalModel } from '@finos/calm-models/canonical';
 import { VMLeafNode, VMAttach } from '../../types';
 import { VMNodeFactory } from './vm-factory-interfaces';
-import {ifaceId, prettyLabel} from '../utils';
+import { ifaceId, prettyLabel } from '../utils';
 
 
 type WithOptionalLabel = CalmNodeCanonicalModel & { label?: string };
@@ -18,7 +18,8 @@ export class StandardVMNodeFactory implements VMNodeFactory {
         const attachments: VMAttach[] = [];
         const leaf: VMLeafNode = {
             id: node['unique-id'],
-            label: labelFor(node, node['unique-id'])
+            label: labelFor(node, node['unique-id']),
+            nodeType: node['node-type']
         };
 
         if (renderInterfaces && Array.isArray(node.interfaces) && node.interfaces.length > 0) {

calm-widgets/src/widgets/block-architecture/core/options-parser.spec.ts

@@ -118,4 +118,29 @@ describe('options-parser', () => {
         expect(out.direction).toBe('both');
         expect(out.edgeLabels).toBe('description');
     });
+
+    it('parses node-type-map when provided as object', () => {
+        const out = parseOptions(
+            raw('{ "node-type-map": { "postgres": "database", "nginx": "service" } }')
+        );
+        expect(out.nodeTypeMap).toEqual({ postgres: 'database', nginx: 'service' });
+    });
+
+    it('parses node-type-map when provided as JSON string', () => {
+        const out = parseOptions({
+            'node-type-map': JSON.stringify({ redis: 'database', 'load-balancer': 'service' })
+        });
+        expect(out.nodeTypeMap).toEqual({ redis: 'database', 'load-balancer': 'service' });
+    });
+
+    it('ignores bad JSON for node-type-map', () => {
+        const out = parseOptions({ 'node-type-map': '{bad json for node types' });
+        expect(out.nodeTypeMap).toBeUndefined();
+    });
+
+    it('render-node-type-shapes: false by default; true only when explicitly true', () => {
+        expect(parseOptions().renderNodeTypeShapes).toBe(false);
+        expect(parseOptions({ 'render-node-type-shapes': false }).renderNodeTypeShapes).toBe(false);
+        expect(parseOptions({ 'render-node-type-shapes': true }).renderNodeTypeShapes).toBe(true);
+    });
 });

calm-widgets/src/widgets/block-architecture/core/options-parser.ts

@@ -32,6 +32,7 @@ export function parseOptions(raw?: BlockArchOptions): NormalizedOptions {
         edges: 'connected',
         direction: 'both',
         renderInterfaces: false,
+        renderNodeTypeShapes: false,
         edgeLabels: 'description',
         collapseRelationships: false,
     };
@@ -47,6 +48,7 @@ export function parseOptions(raw?: BlockArchOptions): NormalizedOptions {
     if (raw['highlight-nodes']) o.highlightNodes = csv(raw['highlight-nodes']);
     if (raw['node-types']) o.nodeTypes = csv(raw['node-types']);
     if (raw['render-interfaces']) o.renderInterfaces = true;
+    if (raw['render-node-type-shapes']) o.renderNodeTypeShapes = true;
     if (raw['collapse-relationships']) o.collapseRelationships = true;
 
     o.edgeLabels = pickEnum(raw['edge-labels'], ['description', 'none'] as const, o.edgeLabels);
@@ -75,8 +77,22 @@ export function parseOptions(raw?: BlockArchOptions): NormalizedOptions {
             } else {
                 o.linkMap = raw['link-map'];
             }
-        } catch {
-            // ignore bad JSON; keep linkMap undefined
+        } catch (error) {
+            console.warn(`[options-parser] Failed to parse link-map JSON: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            // keep linkMap undefined
+        }
+    }
+
+    if (raw['node-type-map']) {
+        try {
+            if (typeof raw['node-type-map'] === 'string') {
+                o.nodeTypeMap = JSON.parse(raw['node-type-map']);
+            } else {
+                o.nodeTypeMap = raw['node-type-map'];
+            }
+        } catch (error) {
+            console.warn(`[options-parser] Failed to parse node-type-map JSON: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            // keep nodeTypeMap undefined
         }
     }
 

calm-widgets/src/widgets/block-architecture/core/strategies/expand/children-strategy.spec.ts

@@ -11,6 +11,7 @@ const base = (overrides: Partial<NormalizedOptions> = {}): NormalizedOptions =>
     edges: 'connected',
     direction: 'both',
     renderInterfaces: false,
+    renderNodeTypeShapes: false,
     edgeLabels: 'description',
     collapseRelationships: false,
     ...overrides,

calm-widgets/src/widgets/block-architecture/core/strategies/expand/container-strategy.spec.ts

@@ -11,6 +11,7 @@ const base = (includeContainers: NormalizedOptions['includeContainers']): Normal
     edges: 'connected',
     direction: 'both',
     renderInterfaces: false,
+    renderNodeTypeShapes: false,
     edgeLabels: 'description',
     collapseRelationships: false
 });