@ixfx/components 0.16.5 → 0.17.1

package/docs-user/node-graph.md

@@ -0,0 +1,376 @@
+# `ixfx-node-graph`
+
+A Svelte-Flow-style node editor: nodes on a pan/zoom canvas, wires between typed ports, and a magnetic connect gesture. Nodes are ordinary light-DOM elements, so you can put anything inside them — including other ixfx controls.
+
+Three elements:
+
+- `<ixfx-node-graph>` — the canvas: pan/zoom, wires, gestures, selection
+- `<ixfx-graph-node>` — one node (`key`, `x`/`y`, optional `label` header)
+- `<ixfx-graph-port>` — one connectable dot (`key`, `dir`, `type`, …)
+
+```html
+<ixfx-node-graph acyclic>
+  <ixfx-graph-node key="osc" x="40" y="60" label="Oscillator">
+    <ixfx-graph-port key="freq" dir="in" type="number" label="Freq"></ixfx-graph-port>
+    <ixfx-slider-input min="0" max="100"></ixfx-slider-input>
+    <ixfx-graph-port key="out" dir="out" type="signal" label="Out"></ixfx-graph-port>
+  </ixfx-graph-node>
+  <ixfx-graph-node key="amp" x="300" y="60" label="Amp">
+    <ixfx-graph-port key="in" dir="in" type="signal" label="In"></ixfx-graph-port>
+    <ixfx-graph-port key="out" dir="out" type="signal" label="Out"></ixfx-graph-port>
+  </ixfx-graph-node>
+</ixfx-node-graph>
+```
+
+```js
+const graph = document.querySelector('ixfx-node-graph');
+
+// Wire ports programmatically — same rules and events as a drag.
+// Either argument order works; it commits out → in.
+graph.connect({ node: 'osc', port: 'out' }, { node: 'amp', port: 'in' });
+
+// The wire list (plain immutable data; ids are deterministic)
+console.log(graph.edges);
+// [{ id: 'osc/out->amp/in', from: { node: 'osc', port: 'out' }, to: { node: 'amp', port: 'in' } }]
+```
+
+Nodes are light-DOM children. A port that is a *direct child* of a node is auto-assigned to the node's left (`in`) or right (`out`) rail based on `dir`. A port nested deeper — inside the body content — stays where you put it, and wires follow its measured position (Svelte Flow's `<Handle>` pattern). A direct child with an explicit `slot` attribute (use `slot=""` for the body) is left where it is too. Set `side` to match where the port actually sits, e.g. a port pinned to the top edge with CSS wants `side="top"`. Otherwise the wire arrives from the wrong direction, through the node body.
+
+## Graph model
+
+The **port graph** is the source of truth: a `Graphs.Directed` graph (from `@ixfx/collections`) whose vertices are ports and whose edges are wires. Wires always run from an `out` port to an `in` port. Because vertices are ports — not nodes — two wires between the same pair of nodes never collide, and duplicate/max-connection checks are plain graph reads.
+
+The `edges` property is a derived view of that graph, and `getNodeGraph()` returns it collapsed to node keys. That collapsed graph points in the direction of data flow (`a → b` means *b reads from a*), which makes it directly usable as a `Graphs.Dependencies.DependencyGraph` — evaluation order, cycle detection and reachability come for free:
+
+```js
+const ng = graph.getNodeGraph();
+const order = Graphs.Dependencies.recalculationOrder(ng, ['output']);
+```
+
+Port and wire ids escape their keys, so `node: 'a/b'` is safe. Use the exported `portId` / `parsePortId` helpers to build or read vertex ids — never hand-split on `/`.
+
+> **Reset vs. mutate.** The element owns its graph. Read it via `edges` / `getGraph()` / `getPortGraph()`; set `edges` only to reset the whole wiring wholesale (it rebuilds the port graph from the plain array). In particular, if a framework re-renders around the graph, do *not* re-assign `edges` with the array you read back after every `graph-edges-change` — that throws away in-flight gesture state. Subscribe and read, or reset deliberately.
+
+## `<ixfx-node-graph>` API
+
+### Properties / attributes
+
+| Attribute / property | Type                      | Default  | Description                                                             |
+|----------------------|---------------------------|----------|-------------------------------------------------------------------------|
+| `edges`              | `readonly GraphEdge[]`    | `[]`     | Wire list. Setting it rebuilds the graph (see warning above).            |
+| `viewport`           | `{x, y, zoom}`            | `0,0,1`  | Pan/zoom transform of the canvas.                                       |
+| `min-zoom`           | `number`                  | `0.2`    | Zoom clamp for gestures and `fitView()`.                                |
+| `max-zoom`           | `number`                  | `3`      | Zoom clamp for gestures and `fitView()`.                                |
+| `wheel`              | `'zoom' \| 'pan'`         | `'zoom'` | Plain wheel behaviour; ctrl/cmd + wheel always zooms.                    |
+| `snap-radius`        | `number`                  | `32`     | Magnet radius (screen px) when releasing a wire near a compatible port.  |
+| `allow-self`         | `boolean`                 | `false`  | Allow a wire between two ports of the same node.                        |
+| `acyclic`            | `boolean`                 | `false`  | Reject wires that would create a cycle at the node level.               |
+| `port-layout`        | `'rail' \| 'full'`        | `'rail'` | How nodes list ports: inputs left and outputs right (`rail`), or a full-width row per port (`full`). A node's own `port-layout` wins. See [Port layouts](#port-layouts). |
+| `dblclick-toggle`    | `boolean`                 | `false`  | Double-clicking a node's title bar collapses or expands it. The `graph-node-title-dblclick` event fires either way. |
+| `available-ports`    | `'show' \| 'hide'`        | `'show'` | Show or tuck away every node's available (unconnected) ports. A node's own `available-ports` wins. See [Port states](#port-states). |
+| `drag-by`            | `'node' \| 'handle'`      | `'node'` | What starts moving a node: anywhere on it, or only its title-bar grip. A node's own `drag-by` wins. |
+| `easy-connect`       | `boolean`                 | `false`  | Drag from anywhere inside a node to start a wire; drop anywhere on a node to finish one. |
+| `easy-connect-margin`| `number`                  | `10`     | Width (flow px) of the ring around a node that still moves it under `easy-connect`. |
+| `proximity-connect`  | `number`                  | `0`      | While dragging a node, offer a wire to the nearest node within this many flow px (`0` = off); made on drop. |
+| `bridge-on-delete`   | `boolean`                 | `false`  | Deleting a node in the middle of a flow reconnects what fed it to what it fed. |
+| `nodeFactory`        | `(ctx) => GraphNodeElement \| null` | — | Opt-in: called when a wire is dropped on empty space; the returned node is added there and wired. Property only. |
+| `edgeLabels`         | `Record<string, string>`  | `{}`     | Wire id → label text. Property only; prefer `setEdgeLabel()`. |
+| `touch-mode`         | `'pan' \| 'select'`       | `'pan'`  | What a touch/pen drag on empty space does: pan, or draw a selection rectangle. Mouse is unaffected. |
+| `isValidConnection`  | `(from, to, graph) => boolean` | —   | Extra veto hook, called after the built-in rules pass. Property only.   |
+| `wireFlow`           | `Record<string, number>`  | `{}`     | Wire id → flow speed (flow-space px/s). See [Data-flow animation](#data-flow-animation). Property only. |
+
+### Methods
+
+| Method                    | Returns                        | Description                                              |
+|---------------------------|--------------------------------|----------------------------------------------------------|
+| `connect(from, to)`       | `boolean`                      | Wire two ports (either order); `false` if the rules reject it. |
+| `disconnect(id)`          | `boolean`                      | Remove a wire by id.                                     |
+| `setEdgeLabel(id, text)`  | `void`                         | Set or clear (`''` / `undefined`) a wire's label.        |
+| `setWireFlow(id, speed)`  | `void`                         | Animate one wire at `speed` px/s; `0` / `undefined` stops it. |
+| `getGraph()`              | `GraphSnapshot`                | Plain-JSON snapshot: nodes with positions and ports, plus edges. |
+| `getSubflowEdges(groupKey)` | `{ incoming, outgoing, internal }` | The wires crossing a sub flow's boundary (the group and everything in it): in from outside, out to outside, and the ones entirely inside. |
+| `getPortGraph()`          | `Graphs.Directed.DirectedGraph`| The source-of-truth port graph.                          |
+| `getNodeGraph()`          | `Graphs.Directed.DirectedGraph`| Port graph collapsed to node keys (= dependency graph).  |
+| `setViewport(v)`          | `void`                         | Set pan/zoom (zoom is clamped).                          |
+| `fitView(padding?)`       | `void`                         | Pan/zoom so all nodes fit (default 50px margin).         |
+| `screenToFlow(p)`         | `Point`                        | Client coordinates → flow coordinates.                   |
+| `flowToScreen(p)`         | `Point`                        | Flow coordinates → client coordinates.                   |
+| `contextTarget`           | `GraphContextMenuDetail?`      | What the last right-click landed on (for `menu-command` handlers). |
+| `getViewState(options?)`  | `NodeGraphViewState`           | Viewport + selected wires (see `docs/infra-view-state.md`). |
+| `setViewState(state)`     | `void`                         | Restore a view state.                                    |
+
+View state `kind` is `'node-graph'`; `clearPendingViewState()` is a no-op — this component has no pending view state to clear.
+
+### Events
+
+All events are composed and (except where noted) cancelable.
+
+| Event                     | Detail                                      | Cancelable | Description                                                |
+|---------------------------|---------------------------------------------|------------|-------------------------------------------------------------|
+| `graph-connect`           | `{ edge, replaces? }`                       | yes        | A wire is about to be committed (drag or `connect()`).      |
+| `graph-disconnect`        | `{ edges, reason }`                         | yes        | Wires removed; reason `delete` \| `detach` \| `replace` \| `api`. |
+| `graph-connect-end`       | `{ from, point, client }`                   | no         | A dragged wire was released on empty space (e.g. to open a create-node menu). |
+| `graph-delete`            | `{ nodes, edges, bridged }`                 | yes        | Selection delete is about to run. `nodes` includes a deleted group's children; `bridged` lists wires added by `bridge-on-delete`. |
+| `graph-node-move`         | `{ moves }`                                 | no         | Node positions during a drag.                               |
+| `graph-node-moved`        | `{ moves }`                                 | no         | Node positions after a drag commit.                         |
+| `graph-node-resize` / `graph-node-resized` | `{ key, x, y, width, height }` | no | While resizing / on release. `x`, `y` are relative to the parent. |
+| `graph-node-title-dblclick` | `{ key, collapsed }`                      | yes        | A node's title bar was double-clicked (not its collapse button, menu or grip). `collapsed` is the state before. With `dblclick-toggle` on, `preventDefault()` stops the toggle. |
+| `graph-node-collapse`     | `{ key, collapsed }`                        | no         | A node was collapsed or expanded (bubbles from the node).    |
+| `graph-port-change`       | `{ node, port, availability }`              | no         | The user added a port (`available`) or hid one (`potential`). |
+| `graph-node-added`        | `{ key, from, connectedTo? }`               | no         | A `nodeFactory` node was added (and wired, if a compatible port existed). |
+| `graph-context-menu`      | `{ kind, id?, client, point }`              | yes        | Right-click on a `node`, `edge` or `pane` that has a menu. Cancel to suppress it. |
+| `graph-selection-change`  | `{ nodes, edges }`                          | no         | Selection changed (key arrays).                             |
+| `graph-viewport-change`   | `{x, y, zoom}`                              | no         | Pan/zoom committed.                                         |
+| `graph-edges-change`      | `{ edges, graph }`                          | no         | The graph changed; `graph` is the new port graph (for undo stacks). |
+
+Veto a change by calling `event.preventDefault()` on the cancelable ones — the graph state is only mutated if the event isn't canceled.
+
+## Gestures & keyboard
+
+- **Connect** — drag from a port. Any compatible port under the pointer glows when within magnet range (`data-magnet="active"`, `--magnet-proximity`); release to connect. Releasing on empty space fires `graph-connect-end`. Dragging backwards from an `in` port works; the wire commits out → in. Dragging an existing wire off a port detaches it (its far end follows the pointer).
+- **Pan** — drag the background, drag with the middle button anywhere, or Space + drag. **Zoom** — wheel, ctrl/cmd + wheel (trackpad pinch), or two-finger touch pinch.
+- **Select** — click a node or wire; shift/cmd-click to toggle. Drag a selected node to move the whole selection. Click the background to clear.
+- **Select a region** — hold **Shift** and drag on empty space with the mouse to draw a selection rectangle; every node it overlaps (even partly) is selected live. Add **Ctrl/Cmd** as well to add to the current selection instead of replacing it. Touch and pen can't hold a key, so they follow `touch-mode`: `pan` (default) drags the canvas, `select` draws the rectangle. A second finger during a touch selection cancels it and becomes a pinch, so you can still zoom in `select` mode. Then drag any selected node to move them all together. Only nodes are selected, not wires.
+- **Delete** — `Delete` / `Backspace` deletes the selection (veto with `graph-delete`).
+- **Escape** — cancels an in-flight wire drag, detach or selection rectangle (the selection goes back to what it was).
+
+### Escape hatches
+
+Elements inside nodes opt out of gestures with plain attributes (checked across shadow boundaries):
+
+- `data-nodrag` — pressing it never starts a node drag (embedded controls, buttons)
+- `data-nowheel` — wheel over it never zooms/pans the canvas
+
+Native form controls and `[contenteditable]` are always excluded from both.
+
+## `<ixfx-graph-node>`
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `key` | `string` | — | Unique within its graph. Required. |
+| `x`, `y` | `number` | `0` | Position in flow coordinates; relative to the parent when `parent` is set. |
+| `label` | `string` | `''` | Title-bar text; omit for a headerless node. |
+| `selected` | `boolean` | | Set by the graph, for styling (`:host([selected])`). |
+| `port-layout` | `rail` \| `full` | inherits | Override the graph's `port-layout` for this node. |
+| `icon` | `string` | `''` | Name of an icon in the icon registry, shown before the title. |
+| `available-ports` | `show` \| `hide` | inherits | Show or tuck away this node's available ports. |
+| `shape` | `rect` `rounded` `pill` `circle` `diamond` `hexagon` | `rounded` | Outline. See [Shapes and borders](#shapes-and-borders). |
+| `collapsed` | `boolean` | `false` | Show only the title bar. Needs a `label`; the disclosure widget in the title bar toggles it. |
+| `no-collapse` | `boolean` | `false` | Hide the disclosure widget. |
+| `resizable` | `boolean` | `false` | Edge and corner resize grips (plain CSS, not the ixfx handles). |
+| `width`, `height` | `number` | `0` | Explicit size in flow px (`0` = content / `--graph-node-width`). Set by resizing. |
+| `min-width`, `min-height` | `number` | `80`, `40` | Resize limits. |
+| `max-width`, `max-height` | `number` | `0` | Resize limits (`0` = unlimited). |
+| `drag-by` | `node` \| `handle` | inherits | `handle`: only the title-bar grip starts a drag. |
+| `easy-connect` | `on` \| `off` | inherits | Override the graph's `easy-connect` for this node. |
+| `connect-port` | `string` | first suitable | Key of the port easy-connect wires from. |
+| `parent` | `string` | | Key of a parent (group) node. |
+| `group` | `boolean` | `false` | A container for child nodes. |
+| `extent` | `parent` | | Keep this node inside its parent while dragging. |
+| `toolbar-visible` | `selected` \| `always` \| `hover` | `selected` | When the `toolbar` slot shows. |
+| `toolbar-position` | `top` \| `bottom` \| `left` \| `right` | `top` | Where it sits. |
+
+Shadow parts: `shape`, `surface`, `header`, `disclosure`, `menu`, `drag-handle`, `rail-in`, `rail-out`, `body`, `toolbar`, `resize-n` … `resize-sw`. Size it with `--graph-node-width` (default `180px`); height is content-driven unless `height` is set.
+
+### Shapes and borders
+
+`rect`, `rounded`, `pill` and `circle` are box shapes with a real CSS border, so any `border-style` works. `diamond` and `hexagon` are clipped with `clip-path`, so their border is a layered solid colour (its thickness is approximate on non-square nodes; no dashed or dotted style). Content in `circle`, `diamond` and `hexagon` is centred, and ports stay on the left/right rails inside the outline.
+
+The look is CSS variables, read with fallbacks, so the same variable works **for all nodes** (set it on the graph) or **for one node** (set it in that node's `style`, or with a CSS rule on it):
+
+```css
+ixfx-node-graph { --graph-node-border-width: 2px; }                 /* every node */
+ixfx-graph-node[key=warning] { --graph-node-border-color: orange;   /* just this one */
+  --graph-node-border-style: dashed; }
+```
+
+### Toolbar, context menu, drag handle, groups
+
+- **Toolbar** — a child with `slot="toolbar"` (an `ixfx-toolbar` with `ixfx-button`s) appears above the node while it is selected (or `always` / on `hover`). It never starts a node drag.
+- **Context menu** — a three-dot button in the title bar; see [Context menus](#context-menus).
+- **Title bar** — left to right: the drag grip (with `drag-by="handle"`), the disclosure widget, an optional `icon` (the name of any icon in the icon registry), the title, and the menu button.
+- **Collapse** — every titled node has a disclosure widget at the left of its title bar. Collapsed, a node shows only its title bar and its wires attach to the edge of that bar; it has no effect on a node without a `label`. Collapsing a group hides all its children, but keeps its outside connections: every wire into the sub flow is drawn to **one virtual in port** on the group's left edge, and every wire out of it from **one virtual out port** on the right (a dashed dot with a tooltip such as "2 incoming connections"). Wires with both ends inside the sub flow are hidden. `graph.getSubflowEdges(key)` lists the boundary wires, collapsed or not. Fires `graph-node-collapse` (`{ key, collapsed }`).
+- **Drag handle** — `drag-by="handle"` (on the node, or on the graph for all) shows the shared ixfx grip in the title bar; only it moves the node. Mark any element `data-drag-handle` to make it a grip too.
+- **Sub flows** — a node with `parent="groupKey"` is positioned relative to that group and moves with it, and is **clipped to the group's rectangle** (a child poking out is cut off at the edge; a child fully inside is left alone, so its outline and toolbar still show). A group (`group`, usually `resizable`) can hold children; deleting it deletes them. `extent="parent"` clamps a child inside. If a group and its child are both selected, the child is moved once, with the group.
+
+## Port layouts
+
+`port-layout` (on the graph, or on a node to override it) chooses how a node lists its ports:
+
+- **`rail`** (default): inputs down the left edge, outputs down the right, beside the content, as before.
+- **`full`**: every input and then every output is a **full-width row** (except that a direction with a single, unlabeled port is not given a row: see below), with the label in bold and the port's `description` as a byline under it, a divider between rows, and the dot centred on the node's left (input) or right (output) edge. The whole row is the port, so a wire can start from, or be dropped on, anywhere in it.
+
+**A lone unlabeled port stays compact.** In the `full` layout, if a node has exactly one input (or exactly one output) and that port has no `label`, it is not shown as a row: it is drawn as in `rail`, a dot on the node's edge. This is decided per direction, so a node can list its outputs as rows and keep a single unnamed input as a plain dot. (A lone port that has a label still gets a row, and so does any direction with two or more ports, labeled or not.)
+
+Content slots, in both layouts, top to bottom: the **title bar** (shaded: `--graph-node-header-bg`), `slot="before"`, the default slot (the node body: beside the rails in `rail`, above the ports in `full`), the ports, then `slot="after"`.
+
+```html
+<ixfx-graph-node key="model" label="Model: Status" icon="info" port-layout="full">
+  <ul slot="before">…a note…</ul>
+  <ixfx-graph-port key="data" dir="in" label="Data" description="The complete record"></ixfx-graph-port>
+  <ixfx-graph-port key="out" dir="out" label="Output" description="The validated record"></ixfx-graph-port>
+  <a slot="after">Copy fields as Markdown</a>
+</ixfx-graph-node>
+```
+
+**Port shape and colour.** `--node-graph-port-radius` is the dot's corner radius: `50%` (default) a circle, `3px` a rounded square, `0` a square. `--node-graph-port-size` is its size. `--node-graph-port-connected-color` and `--node-graph-port-available-color` colour a port by state (both default to `--node-graph-port-color`). All of these can be set on the graph, a node, or a single port.
+
+## Port states
+
+Every port is in one of three states:
+
+| State | Meaning |
+|---|---|
+| **connected** | A wire is attached. Always visible, in the node's port column. |
+| **available** | Visible, not connected. |
+| **potential** | Not connected and hidden away. Never drawn as a port; only the **+** button can add it. |
+
+A port's `availability` (`available` or `potential`) is what the author or user chose for it while it is unconnected; the graph works out `connected` from the wires (`data-status` on the port shows the result).
+
+**Hiding available ports.** `available-ports="hide"` on the graph (the default for every node) or on one node tucks its available ports away so the node stays compact (`show` is the default). A tucked-away port is revealed as an overlay on the node's edge, below the ports that are always shown, so nothing reflows. Both inputs and outputs are revealed:
+
+- while the node is **selected** (so this works on touch too, where there is no hover);
+- while the **mouse is over** the node, including over the revealed ports, and for a moment after it leaves;
+- while a **wire is being dragged** toward the node's left (in) or right (out) edge area, for as long as the pointer stays there or over the revealed list of ports (which can extend below and beside the node). The revealed ports become connection targets;
+- after you **add** a port, until you press elsewhere.
+
+**Adding and hiding.** If a node has potential ports on a side, a circle with a **+** appears at the bottom of that side's port column (always **after** the list of ports, below any revealed ones) while the node is selected, or when the pointer hovers there. Clicking it lists the potential ports; choosing one makes it `available`. If the node tucks its available ports away, the new port stays shown until you press elsewhere, so you can see it. Right-clicking an available port offers **Hide port**, which makes it `potential` again. A connected port can't be hidden. Both fire `graph-port-change`, and the port's `availability` attribute reflects the new state, so you can save it.
+
+Ports are drawn **centred on the node's edge**, not inside it.
+
+## Context menus
+
+Author a menu with the ixfx menu primitives and give it a slot. A node's menu is a **three-dot (`ellipsis`) button in its title bar**: use a default-mode `ixfx-menu-trigger` with `icon-name="ellipsis"`, which renders the button. Right-click on the node opens the same menu at the pointer. The graph's `edge-menu` and `pane-menu` have no button (use `mode="dropdown"`) and open on right-click of a wire or the background. With no menu for a target, the browser's own menu is left alone. Right-clicking a node or wire selects it first.
+
+```html
+<ixfx-node-graph>
+  <ixfx-graph-node key="a">
+    <ixfx-menu-trigger slot="context-menu" icon-name="ellipsis">
+      <ixfx-menu-container slot="menu"><ixfx-menu-item command="remove" label="Remove"></ixfx-menu-item></ixfx-menu-container>
+    </ixfx-menu-trigger>
+  </ixfx-graph-node>
+  <ixfx-menu-trigger slot="edge-menu" mode="dropdown">…</ixfx-menu-trigger>
+  <ixfx-menu-trigger slot="pane-menu" mode="dropdown">…</ixfx-menu-trigger>
+</ixfx-node-graph>
+```
+
+Commands arrive as the menu's own `menu-command` event; `graph.contextTarget` says what was clicked (`{ kind, id, point }`, where `point` is in flow coordinates, handy for "add node here"). Listen for the cancelable `graph-context-menu` to adjust or suppress a menu first. (`ixfx-menu-trigger` gained a public `openAt(x, y)` for this.)
+
+## Connecting
+
+- **Connection limits** — `max` on a port caps its wires (an `in` port defaults to one, which a new wire replaces). Over-limit and incompatible ports dim during a drag. `isValidConnection` adds your own veto.
+- **Easy connect** — with `easy-connect`, drag from anywhere inside a node to start a wire from its first `out` port (or `connect-port`), and drop anywhere on a node to connect to its best valid port. The `easy-connect-margin` ring still moves the node; the title-bar grip, controls, group nodes and `data-nodrag` areas never start a wire.
+- **Proximity connect** — with `proximity-connect="70"`, dragging a node within 70 flow px of another shows a dashed wire (the node on the left is the source, then the reverse) and makes it on release, through the normal `graph-connect` event and rules.
+- **Add node on drop** — set `graph.nodeFactory = ({ from, point }) => node`. It runs when a wire is dropped on empty space; the node is placed so its connecting port sits under the pointer and is wired to the dragged port. Return `null` to add nothing. A node with no compatible port is added but left unwired. `graph-connect-end` still fires first.
+- **Delete in the middle** — with `bridge-on-delete`, deleting `B` in `A → B → C` leaves `A → C`. For each wire that entered the node and each that left it, a wire is added when the port types pass through (`in` type compatible with `out` type) and the normal rules allow it (max, cycles, `isValidConnection`); a bridge never replaces another wire. Only nodes you deleted are bridged, not a deleted group's children. `graph-delete.bridged` lists them; cancel the event to veto everything.
+
+## Edge labels
+
+`graph.setEdgeLabel(edge.id, 'text')` draws text at the middle of a wire (`edgeLabels` takes a whole map). It has a halo in the canvas colour instead of a box, so nothing needs measuring. Style with `--node-graph-edge-label-color`, `--node-graph-edge-label-size`, `--node-graph-edge-label-bg`. Labels are text only; there is no HTML label.
+
+## Port location
+
+`port-location` (on the graph; a node's own attribute wins) is `vertical` (default: inputs on the left edge, outputs on the right) or `horizontal` (inputs on the top edge, outputs on the bottom). Wires leave horizontal ports up / down, and revealing hidden ports, the + button and a collapsed group's virtual ports all follow. In `horizontal` mode only the dots are shown (port labels and descriptions are in the tooltip) and `port-layout="full"` is silently ignored. `flip-ports` (graph or node) swaps the two ends — inputs right / bottom, outputs left / top — for flows that run right-to-left or bottom-to-top. A port's own `side` still wins for its wire tangent.
+
+## Edge routing and hints
+
+`edge-style` (`bezier` default, `straight`, `step`) sets how every wire is drawn. Steer single wires with `graph.setEdgeHint(edge.id, { style?, waypoints? })` (`edgeHints` takes a whole map): `style` overrides the graph style for that wire; `waypoints` (flow coordinates) is a list of points the wire passes through.
+
+For full control set `graph.edgeRouter = (request) => Map<edgeId, Point[]>`. The request lists every wire (both ends: node, port, centre, outgoing `side`) and every shown node's rectangle as an obstacle; return the full point list for the wires you route (others are drawn normally). A router wins over hints, which win over styles. It runs synchronously on every redraw, and errors are caught and warned once. `demo/libavoid-router.ts` adapts [libavoid-js](https://github.com/Aksem/libavoid-js) (WASM, orthogonal routing around nodes) to this shape.
+
+## Layout helpers
+
+`getNodeRects()` returns every shown node's `{key, rect}` and `setNodePositions({key: {x, y}})` moves many nodes at once (no events), which is all a layout algorithm needs: `demo/node-graph-layout.ts` feeds them to [dagre](https://github.com/dagrejs/dagre) for layered layouts. `force-layout.ts` is a small immutable force-directed layout (`forceState`, `forceStep`, `forcePositions`, `forcePin`, `forceMovement`) to run once per animation frame.
+
+## `<ixfx-graph-port>`
+
+| Attribute | Type                            | Default          | Description                                                        |
+|-----------|---------------------------------|------------------|--------------------------------------------------------------------|
+| `key`     | `string`                        | —                | Unique identifier within its node. Required. Used in wires and events. |
+| `dir`     | `'in' \| 'out'`                 | `'in'`           | Wire direction.                                                    |
+| `type`    | `string`                        | `''`             | Compatibility tag; empty or `'*'` matches anything.                |
+| `max`     | `number`                        | `0`              | Max connections; `0` = default (1 for `in`, unlimited for `out`).  |
+| `side`    | `'left' \| 'right' \| 'top' \| 'bottom'` | from `dir` | Wire tangent. Mostly useful for inline (nested) ports.          |
+| `label`   | `string`                        | `''`             | Human-visible name, shown next to the dot.                         |
+| `description` | `string`                    | `''`             | Optional longer explanation, shown in the tooltip (the label is the tooltip when there is none). |
+| `availability` | `'available' \| 'potential'` | `'available'` | For an unconnected port: visible, or hidden away until added with the node's + button. A wired port is always `connected`. |
+| `blink`   | `number`                        | `0`              | Blink rate in Hz (`in` or `out` ports). `0` = steady. Clamped to 10 Hz. |
+
+Connection rules, in order: directions must differ → no same-node wire (unless `allow-self`) → types must match → `in` port not full → exact wire must not already exist → no node-level cycle (if `acyclic`) → `isValidConnection`. An `in` port at `max === 1` silently *replaces* its existing wire (reported via `graph-connect`'s `replaces` and `graph-disconnect` reason `replace`).
+
+During a wire drag the graph sets state on ports for CSS: `data-connect="valid|invalid"` and `data-magnet="active"` plus `--magnet-proximity` (0–1).
+
+## Data-flow animation
+
+Two independent ways to show data moving, both pure CSS (no per-frame JS):
+
+- **Wires** — `graph.setWireFlow(edge.id, 120)` draws a dashed highlight that runs along the wire, from the `out` port to the `in` port, at 120 flow-space px/second. Speed is per wire (`wireFlow` takes a whole map). Because speed is in px/s, a long and a short wire at the same speed move at the same pace. `0` / `undefined` stops it. Wire ids are deterministic (`edgeId(from, to)`), so an entry survives the wire being removed and re-created. Only animated wires cost anything, since the overlay exists only while a speed is set.
+- **Ports** — `<ixfx-graph-port blink="2">` blinks the dot twice a second. Set `blink` from code to follow live activity.
+
+Both stop under `prefers-reduced-motion: reduce` (the wire overlay stays as static dashes, ports stay steady).
+
+The wire effect is a moving dash pattern, not a colour gradient: an SVG gradient can't follow a curved path, only a straight line. Tune it with the `--node-graph-wire-flow-*` variables below.
+
+## CSS custom properties
+
+On `<ixfx-node-graph>`:
+
+| Property                        | Default              | Description                        |
+|---------------------------------|----------------------|------------------------------------|
+| `--node-graph-bg`               | `var(--surface-2)`   | Canvas background                  |
+| `--node-graph-grid-color`       | `var(--surface-4)`   | Dot-grid colour                    |
+| `--node-graph-grid-gap`         | `20px`               | Dot-grid spacing                   |
+| `--node-graph-wire-color`       | `var(--surface-6)`   | Wire stroke                        |
+| `--node-graph-wire-width`       | `2px`                | Wire stroke width                  |
+| `--node-graph-wire-selected-color` | `var(--accent)`   | Selected wire stroke               |
+| `--node-graph-port-size`        | `10px`               | Port dot diameter                  |
+| `--node-graph-port-color`       | `var(--surface-6)`   | Port dot fill                      |
+| `--node-graph-port-radius`      | `50%`                | Port dot corner radius (circle → square) |
+| `--node-graph-port-connected-color` | `var(--node-graph-port-color)` | Dot of a connected port |
+| `--node-graph-port-available-color` | `var(--node-graph-port-color)` | Dot of an available (unconnected) port |
+| `--node-graph-magnet-color`     | `var(--accent)`      | Magnet glow / valid-target colour  |
+| `--node-graph-marquee-border`   | `var(--accent)`      | Selection rectangle border         |
+| `--node-graph-marquee-fill`     | 15% `var(--accent)`  | Selection rectangle fill           |
+| `--node-graph-wire-flow-color`  | `var(--accent)`      | Data-flow dash colour              |
+| `--node-graph-wire-flow-dash`   | `14`                 | Flow dash length (unitless px)     |
+| `--node-graph-wire-flow-gap`    | `56`                 | Gap between flow dashes (unitless px) |
+| `--node-graph-port-blink-dim`   | `0.2`                | Port opacity in the "off" half of a blink |
+| `--node-graph-edge-label-color` | `var(--surface-text)`| Edge label text                    |
+| `--node-graph-edge-label-size`  | `11px`               | Edge label font size               |
+| `--node-graph-edge-label-bg`    | `var(--node-graph-bg)`| Edge label halo colour            |
+
+On `<ixfx-graph-node>`:
+
+| Property                       | Default              | Description                |
+|--------------------------------|----------------------|----------------------------|
+| `--graph-node-width`           | `180px`              | Node width                 |
+| `--graph-node-header-bg`       | 7% of the text colour| Title bar shading          |
+| `--graph-node-port-row-border` | `1px solid` (faint)  | Divider between full-width port rows |
+| `--graph-node-bg`              | `var(--surface-3)`   | Node background            |
+| `--graph-node-text`            | `var(--surface-3-text)` | Node text colour        |
+| `--graph-node-radius`          | `var(--radius-m)`    | Corner radius (`rounded`)  |
+| `--graph-node-border-width`    | `1px`                | Border width               |
+| `--graph-node-border-style`    | `solid`              | Border style (box shapes only) |
+| `--graph-node-border-color`    | `var(--surface-5)`   | Border colour              |
+| `--graph-node-selected-outline`| `var(--accent)`      | Selection outline          |
+| `--graph-node-toolbar-offset`  | `8px`                | Gap between node and toolbar |
+| `--graph-node-selected-outline`| `var(--accent)`      | Selection outline colour   |
+
+Per-type port colours are plain consumer CSS — the `type` attribute reflects, so:
+
+```css
+ixfx-graph-port[type=number] { --node-graph-port-color: oklch(70% 0.12 210); }
+```
+
+## Performance notes
+
+- Wire paths are recomputed only when something invalidated them (graph change, node geometry change, viewport change); they render through a keyed `repeat` over deterministic edge ids, so a viewport pan touches no wire DOM beyond the layer transform.
+- Node geometry (position + measured size + port offsets) is cached per node, refreshed by `ResizeObserver` and a `MutationObserver` on node children — no per-frame measuring.
+- Pan/zoom renders through the layer transform only; the dot-grid background is drawn on the pane with `background-position` from the same transform.
+- For very large graphs, remove off-screen nodes rather than hiding them (ports register/unregister with the graph via slot observation, so removal also prunes the model).
+
+## Demo
+
+`demo/node-graph-layout.html`: edge routing with libavoid-js and waypoint hints, dagre auto layout, and a live force-directed layout.
+
+`demo/node-graph.html` (also via the demo index): a live arithmetic patch — two slider inputs, a sum, a scale and an output LED — evaluated with `Graphs.Dependencies.calc` from `getNodeGraph()`, plus event logging and a JSON snapshot.

package/llms.txt

@@ -43,6 +43,7 @@ import '@ixfx/components/data-grid';
 - [miller](docs-user/miller.md): A Miller column component displays hierarchical data as multiple vertical columns, like macOS Finder or email clients. Each column shows the children of the selected item in the previous column.
 - [multicol-list](docs-user/multicol-list.md): A faceted-filtering component: each column shows one property (facet) of the *same*
 - [narrowed-text](docs-user/narrowed-text.md): A filtered text selection component with inline search. Shows slotted items filtered by a query string as the user types.
+- [node-graph](docs-user/node-graph.md): A Svelte-Flow-style node editor: nodes on a pan/zoom canvas, wires between typed ports, and a magnetic connect gesture. Nodes are ordinary light-DOM elements, so you can put anything inside them — inc
 - [notifier](docs-user/notifier.md): A "lookless" app-wide notification system. `NotificationManager` is a singleton that owns notification state, queueing, and timing — it doesn't know how to draw anything. A `NotificationRenderer` (the
 - [pan-text](docs-user/pan-text.md): Pans overflowing text on hover or continuously in a loop. Use when a label is too long for its container and you want to reveal the full text without truncation.
 - [panel](docs-user/panel.md): An collapsible panel component with support for titles, icons, toolbars, and multiple visual variants.

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.16.5",
+  "version": "0.17.1",
   "packageManager": "pnpm@10.0.0",
   "description": "Web components for ixfx — Lit-based UI toolkit",
   "author": "Clint Heyer",
   "license": "MIT",
-  "keywords": ["web-components", "lit", "ixfx", "ui"],
+  "keywords": [
+    "web-components",
+    "lit",
+    "ixfx",
+    "ui"
+  ],
   "exports": {
     "./style.css": "./dist/style.css",
     ".": {
@@ -101,6 +106,10 @@
       "types": "./dist/narrowed-text.d.ts",
       "import": "./dist/narrowed-text.js"
     },
+    "./node-graph": {
+      "types": "./dist/node-graph.d.ts",
+      "import": "./dist/node-graph.js"
+    },
     "./panel": {
       "types": "./dist/panel.d.ts",
       "import": "./dist/panel.js"
@@ -225,7 +234,9 @@
     "docs-user",
     "llms.txt"
   ],
-  "engines": { "node": ">=20" },
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
@@ -252,36 +263,40 @@
     "lit": "^3.0.0"
   },
   "peerDependenciesMeta": {
-    "lit": { "optional": false }
+    "lit": {
+      "optional": false
+    }
   },
   "dependencies": {
     "@clinth/ui-commands": "1.1.2",
-    "@clinth/vcanvas": "0.0.5",
-    "@ixfx/arrays": "0.56.14",
-    "@ixfx/collections": "0.56.14",
-    "@ixfx/core": "0.56.14",
-    "@ixfx/dom": "0.56.14",
-    "@ixfx/flow": "0.56.14",
-    "@ixfx/geometry": "0.56.14",
-    "@ixfx/modulation": "0.56.14",
-    "@ixfx/numbers": "0.56.14",
-    "@ixfx/visual": "0.56.14",
+    "@clinth/vcanvas": "0.0.6",
+    "@ixfx/arrays": "0.56.21",
+    "@ixfx/collections": "0.56.21",
+    "@ixfx/core": "0.56.21",
+    "@ixfx/dom": "0.56.21",
+    "@ixfx/flow": "0.56.21",
+    "@ixfx/geometry": "0.56.21",
+    "@ixfx/modulation": "0.56.21",
+    "@ixfx/numbers": "0.56.21",
+    "@ixfx/visual": "0.56.21",
     "fzf": "0.5.2"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.3.0",
-    "@tsdown/css": "0.22.14",
+    "@antfu/eslint-config": "^10.0.0",
+    "@dagrejs/dagre": "3.1.3",
+    "@tsdown/css": "0.23.7",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "eslint": "10.8.1",
+    "eslint": "10.14.0",
     "eslint-plugin-format": "2.0.1",
-    "globals": "17.9.0",
-    "happy-dom": "^20.14.0",
-    "knip": "6.32.0",
+    "globals": "17.14.0",
+    "happy-dom": "^21.0.4",
+    "knip": "6.44.2",
+    "libavoid-js": "0.5.0-beta.5",
     "lit": "3.3.3",
-    "tsdown": "0.22.14",
+    "tsdown": "0.23.7",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.66.0",
-    "vite": "8.2.1",
-    "vitest": "^5.0.0"
+    "typescript-eslint": "8.72.2",
+    "vite": "8.3.7",
+    "vitest": "^5.1.0"
   }
 }

package/bundle/rolldown-runtime-CEoa-xHZ.js

@@ -1 +0,0 @@
-var e=Object.defineProperty,t=(t,n)=>{let r={};for(var i in t)e(r,i,{get:t[i],enumerable:!0});return n||e(r,Symbol.toStringTag,{value:`Module`}),r},n=(e=>typeof require<`u`?require:typeof Proxy<`u`?new Proxy(e,{get:(e,t)=>(typeof require<`u`?require:e)[t]}):e)(function(e){if(typeof require<`u`)return require.apply(this,arguments);throw Error('Calling `require` for "'+e+"\" in an environment that doesn't expose the `require` function. See https://rolldown.rs/in-depth/bundling-cjs#require-external-modules for more details.")});export{n,t};

package/dist/interaction-E-uMGHkJ.js

@@ -1,3 +0,0 @@
-import "./tickled-controller-D-HZymaZ.js";
-import "./tickled-styles-BrAHEj1q.js";
-import "./list-native-drag-controller-CcXoS0YX.js";

package/dist/rolldown-runtime-D7D4PA-g.js

@@ -1,13 +0,0 @@
-//#region \0rolldown/runtime.js
-var __defProp = Object.defineProperty;
-var __exportAll = (all, no_symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
-//#endregion
-export { __exportAll as t };