New Features & Migration Guide (v0.5.0)

Version 0.5.0 is a major leap forward for LitFlow, transitioning it from a simple diagramming tool to a Structural Diagnostic Engine. This guide covers the major new features and provides code examples for implementation.

1. Multi-Strategy Layouts (Lenses)

You can now automatically arrange nodes using three distinct algorithms via the layout-strategy attribute.

Hierarchical (Dagre)

The default. Best for workflows and DAGs.

<lit-flow layout-enabled layout-strategy="hierarchical" layout-direction="LR"></lit-flow>

Organic (D3-Force)

Best for cluster discovery. Uses a physics simulation with horizontal bias.

<lit-flow layout-enabled layout-strategy="organic"></lit-flow>

Tree (D3-Hierarchy)

Best for Org Charts. Requires a strict parent-child structure.

<lit-flow layout-enabled layout-strategy="tree" layout-direction="TB"></lit-flow>

2. Dynamic Orientation & Handles

Handles now automatically adapt to the layout-direction.

• LR (Left-to-Right): Handles move to the Left (Input) and Right (Output).
• TB (Top-to-Bottom): Handles move to the Top (Input) and Bottom (Output).

// Switching direction on the fly
const flow = document.querySelector('lit-flow');
flow.layoutDirection = 'TB'; // Handles and nodes will slide into vertical arrangement

3. Subgraph Isolation (Declarative & Imperative)

You can now "Focus" on specific parts of a large graph.

Declarative (Attribute-based)

Perfect for state-driven applications (like Tasker).

<lit-flow focus-node="node_123" focus-direction="both"></lit-flow>

Imperative (Method-based)

flow.isolateSubgraph('node_123', 'downstream');
// ... later
flow.clearIsolation();

4. Interactive Node Tools

Nodes can now be resized and equipped with contextual toolbars.

Resizable Nodes

Add resizable: true to your node data.

flow.nodes = [
  { id: '1', data: { label: 'Resizable' }, resizable: true, position: { x: 0, y: 0 } }
];

Node Toolbars

Use the toolbar slot. Toolbars only appear when the node is selected.

<lit-node label="My Node" selected resizable>
  <lit-node-toolbar slot="toolbar">
    <button onclick="deleteNode()">Delete</button>
    <button onclick="duplicateNode()">Duplicate</button>
  </lit-node-toolbar>
</lit-node>

5. Migration from v0.4.x

Light DOM Styling

LitNode now uses Light DOM. If you were relying on static styles in a subclass of LitNode, these will no longer work.

Action required: Move your styles to an inline <style> tag in your render() method or a global CSS file.

// v0.4.x (Old)
static styles = css`.my-class { color: red; }`;

// v0.5.0 (New)
render() {
  return html`
    <style>
      .my-class { color: red; }
    </style>
    ...
  `;
}

Mandatory position property

To prevent internal crashes, lit-flow now enforces a position property. If you provide nodes without positions, they will default to { x: 0, y: 0 } before being passed to layout engines.

ID Stringification

If you are using the hierarchical layout, ensure your node IDs are strings. The engine now explicitly casts IDs to strings to prevent layout registry errors.