Components (HTML nodes)

Overview

Elenweave supports HTML nodes that mount DOM on top of the canvas. This enables embedded UI (forms, pickers, widgets) without losing graph behaviors (selection, link, resize).

How it works

The view creates a DOM overlay layer (.ew-html-layer) and mounts HTML nodes there. Each render pass, the view syncs nodes, repositions/scales DOM to match the camera, and remounts when the component identity changes.

• HTML nodes are standard graph nodes with type: "html" plus component / render / loader.
• Per render: add/remove nodes, align DOM with camera (translate + scale), and call update(node, api) when data/props change.
• Component identity is derived from component, render, and loader. If any change, the view remounts the node.

Node fields used by components

The component system watches these node fields to decide what to mount and when to update.

• type: "html" — opt into DOM mounting
• component — registry key
• render — inline renderer per node
• loader — async resolver for a component definition
• data / props — component state/config

Component contract

Render functions receive { node, api }. The render result can be an element, a lifecycle object, or an HTML string.

api helpers

• setData(patch) / setProps(patch) — merge into node.data / node.props
• updateNode(patch) — update any node fields
• select() — select this node
• emit(event, payload) — emit view events (e.g. node:input)
• getNode() — return the latest node snapshot

Security & trust

Sanitize HTML/SVG and gate untrusted component code when embedding external content.

• sanitizeHtml / sanitizeSvg default to true.
• Provide domPurify (or sanitizer) to sanitize HTML strings and in-place elements.
• Customize sanitizer behavior with sanitizeConfig: { html, svg }.
• Mark registry entries as untrusted with trusted: false, or set node.trusted = false.
• Set allowUntrustedComponents: false to block untrusted components.

Lifecycle

Mount, update, and unmount behavior is deterministic and derived from component identity.

• Mount: when node appears or component identity changes, the view resolves and calls render.
• Update: when identity is unchanged and the node is marked dirty, update(node, api) runs.
• Unmount: when node is removed or remounted, cleanup() runs (if provided), then the element is removed.

Selection, drag, link, resize

HTML nodes are interactive by default. Use data-ew-* attributes to control selection and handles.

• data-ew-select: marks a selectable area (root is selectable by default)
• data-ew-drag: marks a drag handle region
• data-ew-link: marks a link anchor for linking mode
• Resize handles are injected automatically by the view.
• Set node.fixed = true to disable dragging and resizing (handles hidden).

Events

The view is an event emitter. Components commonly emit node:input.

view.on('node:input', (payload) => {
  console.log('component input', payload);
});

Registering components

Register once on the view, then use component on nodes to mount.

ESM/CJS build (recommended)

import { ElenweaveWorkspace, ElenweaveView } from 'elenweave';
import { OptionPicker } from 'elenweave/components';
import 'elenweave/styles.css';

const workspace = new ElenweaveWorkspace();
const view = new ElenweaveView({ canvas, workspace });
view.registerComponent('OptionPicker', { render: OptionPicker });

view.registerComponent('option-picker', {
  render: ({ node, api }) => {
    // return HTMLElement
  }
});

// You can also pass a registry map when creating the view.

Dynamic components (async)

Load component code lazily via a loader in the registry or per-node.

view.registerComponent('lazy-widget', {
  loader: () => import('./lazy-widget.js')
});

// or per-node:
view.updateNode(id, { loader: () => import('./lazy-widget.js') });

Capturing user input

Write state to the node and emit a typed signal.

api.setData({ selected: value });
api.emit('node:input', { id: node.id, value });

Bulk updates

For large changes, update nodes/edges in bulk from the host app.

graph.updateNodes([{ id, patch: { text: 'Updated' } }]);
workspace.updateNodesBatch([
  { graphId, updates: [{ id, patch: { color: '#78dbff' } }] }
]);

Example: component with update + cleanup

Return an object with el, update, and cleanup to control lifecycle.

view.registerComponent('counter', {
  render: ({ node, api }) => {
    const el = document.createElement('div');
    el.className = 'counter';
    const btn = document.createElement('button');
    btn.textContent = node.data?.label || 'Click';
    btn.addEventListener('click', () => {
      const value = (node.data?.count || 0) + 1;
      api.setData({ count: value });
      api.emit('node:input', { id: node.id, value });
    });
    el.appendChild(btn);

    return {
      el,
      update: (nextNode) => {
        btn.textContent = `${nextNode.data?.count || 0}`;
      },
      cleanup: () => {
        btn.replaceWith(btn.cloneNode(true));
      }
    };
  }
});

Chart components

Chart components are regular HTML nodes that render SVG visuals in the overlay layer. They remain draggable, linkable, resizable, and serialize with the graph.

Shared fields

Charts read from node.data or node.props (both supported).

• title: header title
• palette: override series colors
• labels: x-axis labels (line/area/bar)
• legend: set false to hide legend
• minX/maxX/minY/maxY: axis overrides (cartesian)

Data shapes

Line / Area / Bar

data: {
  series: [
    { name: 'Alpha', color: '#5feaff', values: [4, 6, 5, 8] },
    { name: 'Beta', values: [2, 4, 3, 5] }
  ],
  labels: ['Mon', 'Tue', 'Wed', 'Thu'],
  stacked: false // bar chart only
}

Scatter

data: {
  series: [
    { name: 'Cluster A', points: [{ x: 1, y: 2 }, { x: 2, y: 3 }] },
    { name: 'Cluster B', points: [{ x: 1.4, y: 4.2 }, { x: 2.6, y: 4.4 }] }
  ],
  radius: 3
}

Heatmap

data: {
  matrix: [
    [2, 4, 6],
    [3, 5, 7],
    [4, 6, 8]
  ],
  xLabels: ['A', 'B', 'C'],
  yLabels: ['Row 1', 'Row 2', 'Row 3'],
  min: 0,
  max: 10
}

Radar

data: {
  axes: ['Core', 'Flux', 'Drift', 'Pulse'],
  series: [
    { name: 'Alpha', values: [6, 8, 5, 7] },
    { name: 'Beta', values: [4, 6, 4, 5] }
  ],
  max: 10
}

Sparkline

data: {
  values: [3, 5, 4, 6, 5, 7, 6, 8],
  color: '#5feaff'
}

Usage example

Register the component, then add an HTML node with component set to the chart name.

view.registerComponent('LineChart', { loader: () => import('./components/chart-line.js') });

view.addNode({
  type: 'html',
  component: 'LineChart',
  x: 200, y: 160, w: 380, h: 240,
  props: { title: 'Signal Trend', labels: ['Mon', 'Tue', 'Wed', 'Thu'] },
  data: {
    series: [
      { name: 'Alpha', values: [4, 6, 5, 8] },
      { name: 'Beta', values: [2, 4, 3, 5] }
    ]
  }
});

Built-in system components

Built-in components live in canvas/components/ and mount as HTML nodes (type: "html"). They accept input and emit node:input.

view.registerComponent('OptionPicker', { loader: () => import('./components/option-picker.js') });

view.addNode({
  type: 'html',
  component: 'OptionPicker',
  x: 200, y: 120, w: 320, h: 160,
  props: { title: 'Signal Gate', options: ['A', 'B'] },
  data: { choice: 'A' }
});

The catalog below lists each component’s purpose and its props/data model. Use props for configuration and data for state.

Input Controls

Media & Content

Charts & Visualizations

Monitoring & Analytics Panels

Graph & Flow Visualizers

DevOps & Code Intelligence

Motion Visualization

Operational Intelligence

Conversation & Community