@kazant/flexgraph 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to this project are documented here. This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.2.0] — 2026-10-12
+
+### Added
+- Undo / redo (`history`, on by default; `historyLimit` 100): moves (one step per drag, including group drags),
+  pins, `relayout`, `updateGraph`, expand / collapse, `importState` and direction / routing changes. Ctrl/Cmd+Z,
+  Ctrl/Cmd+Shift+Z or Ctrl/Cmd+Y, and ↶ ↷ buttons in the controls. `view.undo()`, `redo`, `canUndo`, `canRedo`,
+  `getHistory`, `clearHistory`, `batch(label, fn)` and a `history` event that carries the data now shown.
+- Multi-select (`multiSelect`, on by default): Ctrl/Cmd/Shift + click adds or removes nodes and lines, Shift + drag
+  on the background draws a selection box, Ctrl/Cmd+A selects all and Esc clears. Dragging a selected node moves
+  the whole selection. `view.select([...], { add, toggle })`, `getSelectedItems`, `getSelectedNodes`,
+  `getSelectedEdges`, `selectAll`, `clearSelection`, a `selectionchange` event, `selection` in the `contextmenu`
+  event and `ids` in the drag events. `fitFlow()` without a target fits a multi-selection.
+- Expandable nodes: give a node `details` (HTML) or set `renderDetails(node, el)`, and it gets a "Details" strip at
+  the bottom. Opening it makes room in the layout while the node keeps its place on screen. `view.expand(id)`,
+  `collapse`, `toggleExpand`, `isExpanded`, `onNodeExpand` and an `expand` event.
+- Explore mode for huge hierarchies (`explore: true`): only nodes without a parent are shown at first; clicking a
+  node opens its children, clicking it again closes it. Nodes off the open path are dimmed, blurred or hidden
+  (`exploreUnfocused`), long child lists end in a "+N more" node (`exploreLimit`), a breadcrumb shows the path and
+  badges show child counts. Only the open part of the graph is laid out, so 100 000+ nodes stay fast.
+  `view.setExplorePath(path)`, `getExplorePath`, `exploreBack` (also Escape) and an `explore` event.
+- Fan-out bundling (`bundleFanOut`, default 5): many edges leaving one side of a node share one trunk, like a
+  tree diagram, instead of each taking its own detour.
+
+### Fixed
+- Text was blurry after zooming in: the graph is now only a compositor layer while it moves, so the browser redraws
+  text sharp at the new zoom.
+- Edge labels no longer overlap each other, cover nodes or sit on top of other lines; each label is placed along
+  its own line where there is room.
+- Lines are easier to click and right-click: the hit area stays 14 screen pixels wide when zoomed out.
+- Auto-sized nodes were sometimes 1px too narrow, wrapping their label onto two lines.
+
+## [1.1.0] — 2026-10-09
+
+### Added
+- `view.fitFlow(id?)`: zooms and pans so the whole flow through a node or edge (everything upstream and
+  downstream) fills the view, as large as possible; defaults to the selection. `view.fitNodes(ids)` does the
+  same for any set of nodes. Both include the lines, animate smoothly and stop when the user pans or zooms.
+- Right-click support for custom context menus: `onNodeContextMenu(node, event, { previous, next })`,
+  `onEdgeContextMenu`, `onGroupContextMenu`, `onBackgroundContextMenu` and a `contextmenu` event with
+  `{ kind, node | edge | group, event }`. FlexGraph has no built-in menu; the browser menu is only suppressed for
+  targets the app handles.
+
 ## [1.0.2] — 2026-10-09
 
 ### Fixed

package/README.md

@@ -12,7 +12,13 @@ A flexible relationship graph for the browser, with full control over layout and
 - **Track assignment** – parallel segments are spread onto separate tracks, ordered so they don't cross.
 - **Line hops**, rounded corners, arrowheads and ERD markers (crow's foot etc.), edge labels.
 - **Groups** (compound layout – boxes never overlap), **constraints** (pinned, fixed rank, same rank, left-of).
-- **Interaction** – drag (re-routes only affected edges), pin, zoom/pan/pinch, fit, hover highlighting (whole upstream/downstream chain, or direct neighbors with `hoverHighlight: "neighbors"`; a clicked node stays highlighted), selection, save/load state, animated transitions, incremental updates.
+- **Fan-out bundling** – many edges leaving one side of a node share a trunk, like a tree diagram.
+- **Edge labels** placed so they don't overlap each other, nodes or other lines.
+- **Expandable nodes** – a "Details" strip opens your own content; the layout makes room.
+- **Explore mode** for huge hierarchies – start nodes first, click to open children level by level; only what is open is laid out.
+- **Multi-select** – Ctrl/Cmd/Shift + click, Shift + drag selection box, Ctrl+A; drag one selected node to move them all.
+- **Undo / redo** – Ctrl+Z / Ctrl+Shift+Z for moves, pins, relayout, data updates and expand / collapse.
+- **Interaction** – drag (re-routes only affected edges), pin, zoom/pan/pinch (text stays sharp at any zoom), fit, hover highlighting (whole upstream/downstream chain, or direct neighbors with `hoverHighlight: "neighbors"`; a clicked node stays highlighted), selection, save/load state, animated transitions, incremental updates.
 - Layout engine is DOM-free (Node, SSR, Web Worker).
 
 ## Install
@@ -49,6 +55,7 @@ const view = createGraph(document.getElementById("graph"), {
 
 view.relayout();               // full auto layout (respects pins)
 view.updateGraph(newData);     // incremental: existing nodes stay put
+view.fitFlow("b");             // zoom so the whole flow through "b" fills the view; no argument = the selection
 view.getConnections("b");      // { previous: [nodeA], next: [], incoming, outgoing }; { chain: true } for the whole chain
 view.exportState();            // positions, pins, zoom and the exact edge lines as JSON
 view.importState(saved);       // recreates the saved picture, lines included
@@ -60,7 +67,7 @@ The container needs a size (e.g. `height: 600px`). Nodes without `width`/`height
 
 | Concept | Shape |
 |---|---|
-| Node | `{ id, label?, width?, height?, group?, ports?: [{ id, side, offset? }], constraints?: { pinned, x, y, rank }, className?, type?, html? }` |
+| Node | `{ id, label?, width?, height?, group?, ports?: [{ id, side, offset? }], constraints?: { pinned, x, y, rank }, className?, type?, html?, details?, expandable?, expanded? }` |
 | Edge | `{ id?, source, target, sourcePort?, targetPort?, type?, label?, markerStart?, markerEnd?, minLen?, weight? }` |
 | Group | `{ id, label? }` |
 | Constraints | `{ type: "leftOf", a, b }`, `{ type: "sameRank", nodes: [...] }`, `{ type: "rank", node, rank }` |
@@ -69,7 +76,86 @@ Edge `type` sets the CSS class `fg-edge--<type>` and default markers (`has-many`
 
 ### Events
 
-`view.on(name, cb)` with `layout`, `select`, `hover`, `nodeclick`, `edgeclick`, `groupclick`, `dragstart`, `drag`, `dragend`, `pin`, `change`, `viewport`, `animationend`.
+`view.on(name, cb)` with `layout`, `history`, `select`, `selectionchange`, `hover`, `nodeclick`, `edgeclick`, `groupclick`, `dragstart`, `drag`, `dragend`, `pin`, `change`, `viewport`, `animationend`, `contextmenu`, `expand`, `explore`.
+
+### Undo / redo
+
+Moves (a whole drag is one step), pins, `relayout()`, `updateGraph()`, expand / collapse, `importState()` and direction or routing changes can be undone with Ctrl/Cmd+Z and redone with Ctrl/Cmd+Shift+Z or Ctrl/Cmd+Y, or with the ↶ ↷ buttons in the controls. Selection, zoom and explore navigation are not undo steps.
+
+```js
+view.undo(); view.redo();                 // Promise<boolean>
+view.canUndo(); view.getHistory();        // { undo: ["move", "update"], redo: [] }
+view.batch("tidy", () => { view.unpinAll(); return view.relayout(); });   // one step
+
+// undo can bring back earlier data (a removed node, say): keep your copy in sync
+view.on("history", ({ data, canUndo, canRedo }) => { myData = data; });
+```
+
+The data is kept by reference, so pass `updateGraph` a new object instead of editing the old one in place. Turn it off with `history: false`; `historyLimit` (default 100) caps the steps kept.
+
+### Selecting several items
+
+Ctrl/Cmd/Shift + click adds a node or line to the selection (or removes it), Shift + drag on the background draws a selection box, Ctrl/Cmd+A selects every node and Esc clears. Dragging a selected node moves the whole selection. Turn it off with `multiSelect: false`.
+
+```js
+view.select(["a", "b", { kind: "edge", id: "e1" }]);   // also { add: true } or { toggle: true }
+view.getSelectedNodes();                               // the original node objects
+view.on("selectionchange", ({ nodes, edges }) => { /* … */ });
+view.on("contextmenu", ({ node, selection }) => { /* e.g. "Delete 3 selected" */ });
+```
+
+`select` / `getSelection()` keep working as before and report the primary item (the one selected last).
+
+Lines are easy to hit: the click area stays 14 screen pixels wide at any zoom. `onEdgeClick(edge, event)` and `onEdgeContextMenu(edge, event)` work like their node versions.
+
+### Expandable nodes
+
+Give a node `details` (trusted HTML), or set `renderDetails` to give every node a "Details" strip at the bottom. Clicking it opens the node; the layout makes room and the node keeps its place on screen. Details are only built while the node is open.
+
+```js
+createGraph(el, data, {
+  renderDetails: (node) => `<dl><dt>Owner</dt><dd>${node.data.owner}</dd></dl>`,  // or { details: "…" } per node
+  onNodeExpand: (node, expanded) => { /* … */ }
+});
+view.expand("api"); view.collapse("api"); view.toggleExpand("api"); view.isExpanded("api");
+```
+
+Opt a node out with `expandable: false`, or start it open with `expanded: true`. The toggle text is `expandText` / `collapseText`.
+
+### Explore mode (huge hierarchies)
+
+For trees too big to show at once (say 10 start nodes, each with 1 000 children, each with 1 000 more), `explore: true` shows only the nodes without a parent. Clicking a node opens its children; clicking it again closes it. Only the open part of the graph is laid out and rendered.
+
+```js
+createGraph(el, { nodes, edges }, {
+  explore: true,
+  exploreUnfocused: "dim",   // nodes off the open path: "dim" | "blur" | "hide"
+  exploreLimit: 25           // children per node before a "+N more" node (click it for more)
+});
+view.setExplorePath(["region1", "site7"]);   // open a path from code; [] = start nodes only
+view.exploreBack();                          // close the last node (also Escape)
+view.on("explore", ({ path }) => { /* … */ });
+```
+
+A breadcrumb in the top-left corner shows the open path (`exploreBreadcrumb: false` hides it), and each node shows a badge with its number of children.
+
+### Right-click (context menus)
+
+FlexGraph has no built-in menu; it tells you what was right-clicked so you can open your own:
+
+```js
+createGraph(el, data, {
+  onNodeContextMenu: (node, event, { previous, next }) => openMyMenu(event.clientX, event.clientY, node),
+  onEdgeContextMenu: (edge, event) => { /* … */ },
+  onGroupContextMenu: (group, event) => { /* … */ },
+  onBackgroundContextMenu: (event) => { /* … */ }
+});
+
+// or one listener for everything: kind is "node" | "edge" | "group" | "background"
+view.on("contextmenu", ({ kind, node, edge, group, event }) => { /* … */ });
+```
+
+The browser's own menu is only suppressed for targets you handle. Text fields and links inside nodes keep the normal browser menu.
 
 ### Theming
 
@@ -102,7 +188,7 @@ Written from scratch in plain JavaScript (ES modules, ES2020); not a fork or wra
 - **Layout:** Sugiyama-style layered layout: DFS cycle removal, longest-path ranking with compaction, barycenter/median crossing minimization (as in Graphviz *dot*) with transposition and sifting, isotonic-regression coordinate assignment.
 - **Routing:** A* on a sparse orthogonal grid with bend/crossing penalties, track nudging, line hops.
 - **Browser features:** SVG, CSS custom properties, Pointer Events, `requestAnimationFrame`, optional Web Worker. No network requests, no `eval`.
-- **Size:** about 67 kB minified / 25 kB gzipped (ESM), worker 38 kB.
+- **Size:** about 91 kB minified / 33 kB gzipped (ESM), worker 40 kB.
 - **Tooling:** Node.js 20+, tests with `node --test`.
 
 ## Development

package/css/graph.css

@@ -58,7 +58,9 @@
   cursor: grab;
 }
 .fg-viewport.fg-panning { cursor: grabbing; }
-.fg-world { position: absolute; left: 0; top: 0; transform-origin: 0 0; will-change: transform; }
+.fg-world { position: absolute; left: 0; top: 0; transform-origin: 0 0; }
+/* a compositor layer only while panning/zooming: once the view settles text is redrawn sharp at the new zoom */
+.fg-world.fg-moving { will-change: transform; }
 
 /* layers */
 .fg-groups, .fg-labels, .fg-nodes { position: absolute; left: 0; top: 0; }
@@ -84,6 +86,8 @@
 }
 .fg-node__label { text-align: center; overflow: hidden; text-overflow: ellipsis; }
 .fg-node--measuring { width: max-content !important; height: auto !important; max-width: 320px; visibility: hidden; }
+.fg-node--measuring-h { height: auto !important; visibility: hidden; }
+.fg-node--expanded.fg-node--measuring { max-width: 420px; }
 .fg-node:hover { border-color: var(--fg-accent); }
 .fg-node.fg-selected { border-color: var(--fg-accent); box-shadow: 0 0 0 3px color-mix(in srgb, var(--fg-accent) 25%, transparent), var(--fg-node-shadow); }
 .fg-node--dragging { cursor: grabbing; box-shadow: 0 8px 24px rgba(15, 23, 42, 0.18); z-index: 2; }
@@ -143,7 +147,8 @@
   stroke-linecap: round;
   transition: stroke 0.15s, opacity 0.15s;
 }
-.fg-edge__hit { fill: none; stroke: transparent; stroke-width: 12px; pointer-events: stroke; cursor: pointer; }
+/* the hit area stays 14 screen pixels wide at any zoom, so lines are easy to click when zoomed out */
+.fg-edge__hit { fill: none; stroke: transparent; stroke-width: max(12px, calc(14px / var(--fg-zoom, 1))); pointer-events: stroke; cursor: pointer; }
 .fg-edge:hover .fg-edge__line, .fg-edge.fg-selected .fg-edge__line { stroke: var(--fg-edge-active); stroke-width: 2.25px; }
 .fg-edge--dependency .fg-edge__line, .fg-edge--association .fg-edge__line { stroke-dasharray: 6 4; }
 
@@ -167,6 +172,105 @@
   cursor: pointer;
 }
 
+/* expandable nodes: a full-width "Details" strip at the bottom opens the user's details */
+.fg-node--expandable { flex-direction: column; align-items: stretch; padding: 0; }
+.fg-node__body { flex: 1 1 auto; display: flex; align-items: center; justify-content: center; min-height: 0; padding: 8px 12px; }
+.fg-node__details {
+  padding: 8px 12px;
+  border-top: 1px solid var(--fg-node-border);
+  font-size: 12px;
+  text-align: left;
+  user-select: text;
+  -webkit-user-select: text;
+  cursor: auto;
+}
+.fg-node__toggle {
+  flex: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  padding: 3px 12px;
+  border: 0;
+  border-top: 1px solid var(--fg-node-border);
+  background: color-mix(in srgb, var(--fg-node-border) 18%, var(--fg-node-bg));
+  color: var(--fg-group-text);
+  font: 600 11px/16px system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  letter-spacing: 0.02em;
+  border-radius: 0 0 calc(var(--fg-node-radius) - 1px) calc(var(--fg-node-radius) - 1px);
+  cursor: pointer;
+}
+.fg-node__toggle:hover, .fg-node__toggle:focus-visible { color: var(--fg-accent); background: color-mix(in srgb, var(--fg-accent) 10%, var(--fg-node-bg)); outline: none; }
+.fg-node__toggle svg { transition: transform 0.15s; }
+.fg-node__toggle[aria-expanded="true"] svg { transform: rotate(180deg); }
+
+/* explore mode */
+.fg-node__badge {
+  position: absolute;
+  right: -9px;
+  top: 50%;
+  min-width: 18px;
+  height: 18px;
+  margin-top: -9px;
+  padding: 0 5px;
+  box-sizing: border-box;
+  border-radius: 9px;
+  border: 1px solid var(--fg-node-border);
+  background: var(--fg-node-bg);
+  color: var(--fg-group-text);
+  font: 600 10px/16px system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  text-align: center;
+  pointer-events: none;
+}
+/* the badge sits on the side the children are on */
+.fg-explore[data-fg-direction="TB"] .fg-node__badge { top: auto; bottom: -9px; margin-top: 0; }
+.fg-explore[data-fg-direction="BT"] .fg-node__badge { top: -9px; margin-top: 0; }
+.fg-explore[data-fg-direction="RL"] .fg-node__badge { right: auto; left: -9px; }
+.fg-node__badge--open { background: var(--fg-accent); border-color: var(--fg-accent); color: #fff; }
+.fg-node--more { white-space: nowrap; border-style: dashed; color: var(--fg-group-text); font-weight: 600; box-shadow: none; }
+.fg-edge--more .fg-edge__line { stroke-dasharray: 3 4; }
+.fg-explore .fg-node { animation: fg-appear 0.25s ease-out; }
+@keyframes fg-appear { from { opacity: 0; } }
+.fg-node.fg-unfocused, .fg-edge-label.fg-unfocused { opacity: var(--fg-dim-opacity); }
+.fg-edge.fg-unfocused .fg-edge__line { opacity: var(--fg-dim-opacity); }
+.fg-explore--blur .fg-node.fg-unfocused, .fg-explore--blur .fg-edge-label.fg-unfocused { filter: blur(1.5px); opacity: 0.55; }
+.fg-explore--blur .fg-node.fg-unfocused:hover { filter: none; opacity: 1; }
+.fg-breadcrumb {
+  position: absolute;
+  left: 12px;
+  top: 12px;
+  right: 60px;
+  z-index: 20;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 2px;
+  width: max-content;
+  max-width: calc(100% - 72px);
+  padding: 3px;
+  border: 1px solid var(--fg-node-border);
+  border-radius: 8px;
+  background: var(--fg-node-bg);
+  box-shadow: var(--fg-node-shadow);
+  font-size: 12px;
+}
+.fg-breadcrumb button {
+  max-width: 180px;
+  padding: 3px 8px;
+  border: 0;
+  border-radius: 5px;
+  background: none;
+  color: var(--fg-group-text);
+  font: inherit;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  cursor: pointer;
+}
+.fg-breadcrumb button:hover { background: color-mix(in srgb, var(--fg-accent) 10%, transparent); color: var(--fg-accent); }
+.fg-breadcrumb button[aria-current] { color: var(--fg-node-text); font-weight: 600; }
+.fg-breadcrumb__sep { color: var(--fg-group-text); opacity: 0.6; }
+
 /* hover highlighting */
 .fg-hovering .fg-node:not(.fg-hl),
 .fg-hovering .fg-edge-label:not(.fg-hl) { opacity: var(--fg-dim-opacity); }
@@ -174,6 +278,16 @@
 .fg-hovering .fg-edge.fg-hl .fg-edge__line { stroke: var(--fg-edge-active); stroke-width: 2.25px; }
 .fg-dragging .fg-world { cursor: grabbing; }
 
+/* multi-select: Shift + drag on the background draws this box */
+.fg-selection-box {
+  position: absolute;
+  z-index: 15;
+  border: 1px solid var(--fg-accent);
+  border-radius: 2px;
+  background: color-mix(in srgb, var(--fg-accent) 10%, transparent);
+  pointer-events: none;
+}
+
 /* controls */
 .fg-controls {
   position: absolute;
@@ -195,8 +309,11 @@
   cursor: pointer;
   box-shadow: var(--fg-node-shadow);
 }
-.fg-controls button:hover { border-color: var(--fg-accent); color: var(--fg-accent); }
+.fg-controls button:hover:not(:disabled) { border-color: var(--fg-accent); color: var(--fg-accent); }
+.fg-controls button:disabled { opacity: 0.4; cursor: default; }
+.fg-controls__undo { margin-top: 6px; }
 
 @media (prefers-reduced-motion: reduce) {
-  .fg-node, .fg-edge__line { transition: none; }
+  .fg-node, .fg-edge__line, .fg-node__toggle svg { transition: none; }
+  .fg-explore .fg-node { animation: none; }
 }