# FlowEditor

Package: @nannier/canvas
Version: 4.7.0
Status: source-snapshot (not proof of an npm release)
Source SHA-256: 28bc0777dafb01344884368b82a4ba6ecd9c288af2350d8fec2d697f9bbe6849

Source: `src/organisms/flow-editor/flow-editor.md`
Human reference: https://canvas.nannier.com/components/flow-editor

## Public imports

```tsx
import { FlowEditor } from "@nannier/canvas";
```

The following examples are source excerpts. Supply application data and handlers; snippets using `tokens` read `const { tokens } = useTheme()` inside a component. Import React hooks from React. Intentional “Don't” examples illustrate unsupported patterns.

A node-graph editor: cards placed freely on a pannable, zoomable canvas, joined by directed edges. Use it to let people shape a process, such as a delivery workflow whose edges carry conditions. The application owns the graph; FlowEditor draws the `nodes` and `edges` it is given and reports what the user asked for (`onMoveNode`, `onConnect`, `onAddNode`, `onDelete`, `onSelectionChange`).

Drag a card to move it (it snaps to the grid on release), drag from a card's right-hand port onto another card to connect them, and drag a palette entry onto the canvas to add a node. Drag the background to pan; the wheel, a pinch or the toolbar zoom buttons zoom, and Fit shows the whole graph. A rework edge, one that returns work upstream, is drawn dashed.

## Usage

```tsx
<Stateful initial={{
  nodes: [
    { id: "product", label: "Product", description: "Requirements", x: 0, y: 48 },
    { id: "design", label: "Design", description: "Mockups", x: 240, y: 48 },
    { id: "build", label: "Engineering", x: 480, y: 48 },
  ],
  edges: [
    { id: "e1", from: "product", to: "design", label: "Ready" },
    { id: "e2", from: "design", to: "build", label: "Ready" },
    { id: "e3", from: "build", to: "design", label: "Contract changed", rework: true },
  ],
}}>
  {(graph, setGraph) => (
    <FlowEditor label="Delivery workflow" nodes={graph.nodes} edges={graph.edges}
      palette={[{ id: "review", label: "Review" }]}
      onMoveNode={(id, point) => setGraph({ ...graph, nodes: graph.nodes.map((n) => n.id === id ? { ...n, ...point } : n) })}
      onConnect={(from, to) => setGraph({ ...graph, edges: [...graph.edges, { id: `${from}-${to}`, from, to, label: "Ready" }] })}
      onAddNode={(kind, point) => setGraph({ ...graph, nodes: [...graph.nodes, { id: `${kind}-${graph.nodes.length}`, label: "Review", ...point }] })}
      onDelete={(selection) => setGraph(selection.kind === "node"
        ? { nodes: graph.nodes.filter((n) => n.id !== selection.id), edges: graph.edges.filter((e) => e.from !== selection.id && e.to !== selection.id) }
        : { ...graph, edges: graph.edges.filter((e) => e.id !== selection.id) })} />
  )}
</Stateful>
```

## Variants

### Read only

Pass `readOnly` to show a graph without editing it: the toolbar, the ports and card drags are gone, while panning, zooming and selection stay, so a selected card or edge can drive a detail panel beside the editor.

```tsx
<FlowEditor readOnly label="Published workflow, version 2"
  nodes={[
    { id: "intake", label: "Intake", x: 0, y: 0 },
    { id: "product", label: "Product", x: 240, y: 0 },
    { id: "done", label: "Done", x: 480, y: 0 },
  ]}
  edges={[
    { id: "a", from: "intake", to: "product", label: "Triage chose Product" },
    { id: "b", from: "product", to: "done", label: "Ready" },
  ]} />
```

### Free placement

Cards snap to a 24-point grid by default. Pass `freePlacement` to keep them exactly where they are dropped.

```tsx
<FlowEditor freePlacement label="Sketch"
  nodes={[{ id: "a", label: "Start", x: 13, y: 7 }, { id: "b", label: "Finish", x: 251, y: 61 }]}
  edges={[{ id: "ab", from: "a", to: "b" }]} />
```

## Do & Don't

### Say what an edge means

**Do**: Label each edge with the condition it carries, so the graph reads without opening every edge.

```tsx
<FlowEditor readOnly label="Review routing"
  nodes={[{ id: "a", label: "Quality", x: 0, y: 0 }, { id: "b", label: "Operations", x: 240, y: 0 }]}
  edges={[{ id: "ab", from: "a", to: "b", label: "Review ready" }]} />
```

**Don't**: Leave edges unlabeled when several leave one card; the reader cannot tell which path a ticket takes.

```tsx
<FlowEditor readOnly label="Review routing"
  nodes={[{ id: "a", label: "Quality", x: 0, y: 0 }, { id: "b", label: "Operations", x: 240, y: -48 }, { id: "c", label: "Design", x: 240, y: 72 }]}
  edges={[{ id: "ab", from: "a", to: "b" }, { id: "ac", from: "a", to: "c" }]} />
```

## Accessibility

Every pointer action has a keyboard and screen-reader path. Each card is a focusable button named by its title, description, agent line, attention reason and incoming and outgoing connections. Each connection names its source and destination, its label when provided, and whether it is a rework edge; isolated cards announce no connections in either direction. These names follow graph updates and remain available in `readOnly` mode. Edges with a missing source or destination are omitted, just as they are from the drawing.

Cards announce selection (pressed state on the web); Enter or Space selects a focused card. In editable mode, the arrow keys move a focused card one grid step and Delete removes it, and VoiceOver and TalkBack offer the same as named actions (move left, right, up and down, delete). Read-only cards retain selection without editing actions. The toolbar's From and To selects with Connect join two cards without dragging a port; when the two are joined already the button reads Disconnect and removes that edge, the keyboard path to an edge. Each palette entry adds its node in view when pressed. The canvas itself takes focus: plus and minus zoom and 0 fits the graph. Edges are selected by pressing them or their label; Delete removes the selection in editable mode.

## Who acts on a card

A node's optional `agent` is a compact third line naming who acts on the card, such as a role and its skill count. The card keeps its size: its padding tightens when the line is shown. A node's optional `attention` is the reason the card needs attention: it draws a warning mark in the card's top-right corner, and the card's accessible name ends with "needs attention:" and the reason. The mark is not interactive; the application shows the detail, for example in an inspector.

## Supported props

### FlowEditorProps

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | string | yes |  | Accessible name of the canvas, such as "Workflow version 3". |
| nodes | FlowNode[] | yes |  | The cards, controlled. |
| edges | FlowEdge[] | yes |  | The connections, controlled. |
| palette | FlowPaletteItem[] \| undefined | no |  | Kinds of node the user can add; omit for no palette. |
| selected | FlowSelection \| null \| undefined | no |  | Controlled selection; null selects nothing. Omit for uncontrolled use. |
| defaultSelected | FlowSelection \| null \| undefined | no |  | Initial selection for uncontrolled use. |
| onSelectionChange | ((selection: FlowSelection \| null) => void) \| undefined | no |  | Fired when the selection changes, in both modes. |
| onMoveNode | ((id: string, point: FlowPoint) => void) \| undefined | no |  | A card was moved to a new top-left corner (snapped unless `freePlacement`). |
| onConnect | ((from: string, to: string) => void) \| undefined | no |  | The user asked for an edge between two cards. |
| onAddNode | ((paletteId: string, point: FlowPoint) => void) \| undefined | no |  | The user asked to add a node of a palette kind with its top-left corner at `point`. |
| onDelete | ((selection: FlowSelection) => void) \| undefined | no |  | The user asked to delete the selected node or edge. |
| readOnly | boolean \| undefined | no | false | Show the graph without editing: no toolbar edits, drags or ports; pan, zoom and selection stay. |
| freePlacement | boolean \| undefined | no | false | Place cards exactly where they are dropped instead of on the grid. |
| testID | string \| undefined | no |  | E2E hook forwarded to the root element. |

See [installation](https://canvas.nannier.com/ai/4.7.0/installation.md) for required peers and feature fallbacks.
