@relation-graph/html

@relation-graph/html is the framework-free relation-graph runtime for plain HTML and Vanilla JavaScript. It reuses the same core data, options, layouts, APIs, and events as the framework packages, renders into light DOM, and has no Vue, React, or Svelte runtime dependency.

This is the official direct-browser distribution. The former Svelte-generated Web Component packages are discontinued. The HTML package does not register a custom element by default; its recommended entry is createRelationGraph().

See the complete manual or start with Startup.

Use It Directly in a Browser

Load the versioned CSS and UMD bundle:

<link rel="stylesheet" href="https://unpkg.com/@relation-graph/[email protected]/style.css">
<div id="graph" style="width: 100%; height: 600px"></div>
<script src="https://unpkg.com/@relation-graph/[email protected]/relation-graph.umd.js"></script>
<script>
  RelationGraph.createRelationGraph('#graph', {
    options: {
      layout: {layoutName: 'center'},
      defaultNodeWidth: 120,
      defaultNodeHeight: 44
    },
    data: {
      rootId: 'root',
      nodes: [
        {id: 'root', text: 'Relation Graph'},
        {id: 'html', text: 'HTML Runtime'}
      ],
      lines: [{from: 'root', to: 'html', text: 'runs in'}]
    }
  }).then(function (graph) {
    window.graph = graph;
  });
</script>

No npm install, framework, or compile step is required. The UMD global is RelationGraph.

Native browser ESM is also supported. Keep CSS explicit through a <link>:

<link rel="stylesheet" href="https://unpkg.com/@relation-graph/[email protected]/style.css">
<script type="module">
  import {createRelationGraph} from
    'https://unpkg.com/@relation-graph/[email protected]/relation-graph.mjs';

  const graph = await createRelationGraph('#graph', {options, data});
</script>

npm / ESM

npm install @relation-graph/html

import {createRelationGraph} from '@relation-graph/html';
import '@relation-graph/html/style.css';

const graph = await createRelationGraph(document.querySelector('#graph'), {
  options,
  data,
  events,
});

createRelationGraph() accepts an HTMLElement or a CSS selector that resolves to exactly one element. It resolves to the relation-graph instance itself, so all core APIs are available directly.

Configuration

type RGHtmlConfig = {
  options?: RGOptions;
  data?: RGJsonData;
  events?: RGListeners;
  renderers?: RGHtmlRenderers;
  layers?: RGHtmlLayers;
  plugins?: RGHtmlPlugin[];
  ui?: {
    toolbar?: boolean | RGHtmlToolbarOptions;
    miniView?: boolean | RGHtmlMiniViewOptions;
    editing?: boolean | RGHtmlEditingOptions;
  };
};

The toolbar is installed by default and follows options.showToolBar. Set ui.toolbar: false to remove it entirely. MiniView and editing are opt-in. Empty initial data is valid.

const graph = await createRelationGraph('#graph', {
  options: {showToolBar: true},
  data,
  ui: {
    toolbar: {direction: 'v', positionH: 'right', positionV: 'top'},
    miniView: {position: 'br', width: 220, height: 140},
    editing: {node: true, resize: true, connect: true, line: true}
  }
});

Renderers

A renderer returns a DOM node, DocumentFragment, text, or null:

const renderers = {
  node({node, checked}) {
    const element = document.createElement('button');
    element.type = 'button';
    element.className = checked ? 'my-node is-checked' : 'my-node';
    element.textContent = node.text;
    return element;
  },
  line({pathInfo}) {
    const group = document.createElementNS('http://www.w3.org/2000/svg', 'g');
    const background = document.createElementNS('http://www.w3.org/2000/svg', 'path');
    background.setAttribute('class', 'rg-line-bg');
    background.setAttribute('d', pathInfo.pathData);
    const line = document.createElementNS('http://www.w3.org/2000/svg', 'path');
    line.setAttribute('class', 'rg-line');
    line.setAttribute('d', pathInfo.pathData);
    group.append(background, line);
    return group;
  },
  lineLabel({line}) {
    const label = document.createElement('span');
    label.textContent = line.text || '';
    return label;
  }
};

The line renderer replaces the SVG contents inside the runtime-owned line shell. The shell keeps entity identity, checked state, delegated interaction, marker variables, and style variables. lineLabel independently controls the positioned HTML label. See examples/custom-line-slot-rendering/ for a complete example.

Plain strings are always rendered as text. HTML is parsed only through the explicit trustedHTML() wrapper; never pass unsanitized user input to it.

Use a lifecycle renderer when DOM identity or third-party resources must be preserved:

const nodeRenderer = {
  create(context) {
    const element = document.createElement('div');
    element.textContent = context.node.text;
    return element;
  },
  update(element, context) {
    element.textContent = context.node.text;
  },
  destroy(element, context) {
    // Release resources owned by this node.
  }
};

Layers and Plugins

The four stable layer mounts are background, canvasBehind, canvasAbove, and view. Canvas layers move and zoom with the graph; background and view layers stay in viewport space.

const layers = {
  canvasAbove({element}) {
    const badge = document.createElement('div');
    badge.className = 'canvas-badge';
    element.appendChild(badge);
    return () => badge.remove();
  }
};

Built-in UI can also be installed explicitly as ordinary DOM plugins:

import {miniView, editing} from '@relation-graph/html';

const removeMiniView = graph.use(miniView({position: 'tr'}));
const removeEditing = graph.use(editing({resize: true, lineText: true}));

removeMiniView();
removeEditing();

Layer replacement does not remove plugin mounts. Every plugin and layer cleanup runs during graph.destroy().

Events and State

Pass behavioral events through events; callback arguments and return-value semantics match the other relation-graph platforms:

const graph = await createRelationGraph('#graph', {
  data,
  events: {
    onNodeClick(node, event) {
      console.log(node.id);
    },
    beforeCreateLine(lineInfo) {
      return lineInfo.fromNode.id !== lineInfo.toNode.id;
    }
  }
});

Read-only DOM mirrors bubble from the host as rg:node-click, rg:line-click, rg:viewport-change, rg:selection-change, rg:ready, and rg:destroy.

const unsubscribe = graph.subscribe('viewport', viewport => {
  console.log(viewport.canvasZoom, viewport.canvasOffset);
});

The state domains are options, viewport, selection, editing, and renderPlan. A subscriber immediately receives the current snapshot.

Connect Targets

import {registerConnectTarget, RGJunctionPoint} from '@relation-graph/html';

const cleanup = registerConnectTarget(graph, element, {
  targetId: 'port-a',
  junctionPoint: RGJunctionPoint.right,
  targetData: {portType: 'output'}
});

The helper automatically chooses a node or canvas connection point from the element location. A specific target type can also be supplied.

Creating Nodes

The core drag-to-create API renders its preview through the same node renderer:

paletteItem.addEventListener('mousedown', event => {
  graph.startCreatingNodePlot(event, {
    templateNode: {text: 'New service', width: 120, height: 44},
    onCreateNode(x, y, template) {
      graph.addNodes([{
        id: `service-${Date.now()}`,
        text: template.text,
        data: template.data,
        width: template.width,
        height: template.height,
        x,
        y
      }]);
    }
  });
});

Optional Light-DOM Element

Only one element is needed, and registration is explicit:

<relation-graph id="graph" style="height: 600px"></relation-graph>
<script type="module">
  import {defineRelationGraphElement} from '@relation-graph/html';

  defineRelationGraphElement('relation-graph');
  const element = document.querySelector('#graph');
  const graph = await element.configure({options, data});

  console.log(element.shadowRoot); // null
</script>

Using a private tag such as my-relation-graph avoids collisions with other custom elements. Registration fails clearly if another implementation already owns the tag.

Lifecycle and Styling

await graph.whenReady;
graph.setRenderers(nextRenderers);
graph.setLayers(nextLayers);
const removePlugin = graph.use(plugin);

removePlugin();
graph.destroy();

Destroying an instance releases UI, subscriptions, core listeners, observers, and runtime DOM. The same host can then be mounted again. Because the graph uses light DOM, application CSS can target documented renderer classes directly.

See README-zh.md for the Chinese package overview, the complete manual for all HTML APIs, and migration-from-web-component.md for the legacy migration matrix. The HTML platform replaces old rg-* sub-elements with renderers, layers, plugins, and ordinary DOM helpers.

Modern browsers with ESM, Custom Elements, ResizeObserver, MutationObserver, SVG, and Canvas 2D are supported. The factory API itself does not require Custom Elements.