# XWUIFlowchart

An n8n-class workflow editor that extends `XWUIDiagram` and wraps its pan/zoom/drag-to-connect canvas in a three-column shell: a left node **palette** (grouped by node type, click-to-add), the canvas with a mini-map and viewport controls, and a right **inspector** that builds a parameter form from the selected node's type descriptor. The data attribute mirrors n8n's `IWorkflowBase` - `data.flow` (nodes + nested connections), `data.nodeTypes` (palette catalog), `data.executions` (run history shown as a status timeline), and `data.busy`. Live validation surfaces structural and schema problems (missing flow name, duplicate ids, dangling connection targets). Config includes `readOnly` (viewer-only), `hidePublish`, `hideRun`, `wireStyle` (`neutral` grey vs `colored`), `animateWires`, `wireShape` (`bezier`, `step` or `straight`), `inspectorFollowsSelection` (fold the inspector to a rail while nothing is selected), `hideValidation` (drop the built-in findings list, for hosts that draw their own) and `hideToolbarIdentity` (drop the toolbar's brand mark, state chip and name field, for hosts that head the editor with an object header of their own); it emits bubbling `xwui-flowchart:*` events (`save`, `publish`, `run`, `change`, `select-node`, `add-node`, `issues`) and exposes `setFlow`/`getFlow`, `setNodeTypes`, `setExecutions`, `selectNode`, `getSelection`, `setWireShape`, `setFlowName`, `fitView`, and `resetView`.

## Host seams

A host application drives the editor through the element instance, reached with `getInstance()`.

| Seam | What it does |
|---|---|
| `setToolbarExtra(nodes)` | Puts host nodes into the canvas column's toolbar, ahead of Save, Publish and Run. The nodes are kept by reference and are never detached by a repaint, so a live component handed over here keeps its instance. |
| `setInspectorPanel(node \| null)` | Shows a host panel in the right rail in place of the inspector for as long as one is held. A panel outranks the width rule and the selection rule, so pressing something to open it always opens it; clearing it returns the rail to whatever those rules say. The node is never re-parented by a repaint. |
| `updateNodeParameters(id, parameters)` | Replaces one node's parameters from outside the component, with the same undo history, revalidation and `change` emission the inspector's own Apply produces. The write a host panel uses while it holds the rail via `setInspectorPanel`; an id the flow does not hold is refused silently. |
| `getIssues()` | Copies of the current findings. Each carries `kind`, the `message` the built-in list prints, and, where the flow names them, `stepId`, `stepIndex`, `sourceRef`, `targetRef` and `unresolvedRef`, so a host never parses the sentence. |
| `getIssuesCheckedAt()` | When the last check ran, as an epoch millisecond stamp. |
| `focusFlowName()` | Puts the caret in the toolbar's flow-name field, which is where the "flow has no name" finding is cleared. Under `hideToolbarIdentity` there is no such field, so it does nothing and the host owns the caret. |
| `setFlowName(name)` | Writes the flow name from outside, re-checks the flow and announces the result, exactly as typing in the toolbar field does. This is how a host that set `hideToolbarIdentity` clears the "flow has no name" finding. A name equal to the current one is not an edit and says nothing. |

`xwui-flowchart:issues` fires after every check, with `detail.issues`, `detail.count` and
`detail.checkedAt`, so a host never polls. A check runs on construction, on `setFlow`, on every
graph mutation, on every inspector apply and on every edit of the flow name.

Set `hideValidation` when the host draws the findings itself, and `hideToolbarIdentity` when the host
names the flow and shows its state itself, so neither the list nor the name is on screen twice.
A dangling connection endpoint is reported once, by kind: `link-source-unknown`,
`link-target-unknown` or `link-endpoint-unknown` when neither end resolves.

## Side rails and the view

Both side rails fold two ways and the view answers each differently. A width change is not
something the operator asked for, so the canvas is refitted into its new column; one width change
that folds both rails refits once, not once per rail. A chevron is the operator asking for room at
the magnification they are working at, so the zoom is kept and the pan moves only far enough to
bring the content back onto the canvas when the fold has left none of it there.

## Basic Usage

A starter three-node linear workflow - an "On schedule" trigger feeding "Fetch users" then "Send digest" actions - wired by two connections, the minimal seed for the editor canvas.

```example
file: examples/BasicUsage.ts
html: examples/BasicUsage.html
title: Basic Usage
description: A three-node n8n-style flow (schedule trigger → fetch → send digest) joined by two connections.
```

## Branching Flow

A trigger that forks on a condition node into two outcome branches that re-converge.

```example
file: examples/BranchingFlow.ts
html: examples/BranchingFlow.html
title: Branching Flow
description: A new-order trigger splits at a condition into review and auto-approve branches that re-merge on notify.
```

## Error & Retry Flow

A fetch step whose failure path loops back to retry before escalating to an alert.

```example
file: examples/ErrorRetryFlow.ts
html: examples/ErrorRetryFlow.html
title: Error & Retry Flow
description: An hourly sync that retries a failed fetch in a loop and pages on-call when retries give up.
```

```api
```