@kazant/flexgraph 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project are documented here. This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.3.0] — 2026-10-19
+
+### Added
+- Stacking (animated fold / unfold): `stackable: "upstream" | "downstream"` and `stacked` node options, `view.stack(id)`,
+  `unstack`, `toggleStack`, `unstackAll`, `isStacked`, `getStacked`, and `stack` / `unstack` events. Folded nodes
+  slide in underneath their node, which shows a card stack and a `+N` toggle; unfolding brings them back out from
+  underneath. Lines into a stack are redirected (dashed) to the node that holds it. Part of undo / redo and of
+  `exportState()` / `importState()`.
+- `view.addNodes(..., { from })` and `view.removeNodes(ids, { to })`: new nodes come out from underneath a node,
+  removed nodes slide into one. `updateGraph(data, { from, to })` does the same.
+- Nodes that appear in any update now come out of the node they belong to (their first existing predecessor), and
+  nodes that disappear fade out, instead of popping in and out.
+
+### Fixed
+- Focusing a button inside a node no longer scrolls the viewport.
+- When a relayout keeps a node in place, the view now pans in step with the node animation.
+
 ## [1.2.0] — 2026-10-12
 
 ### Added

package/README.md

@@ -76,7 +76,7 @@ Edge `type` sets the CSS class `fg-edge--<type>` and default markers (`has-many`
 
 ### Events
 
-`view.on(name, cb)` with `layout`, `history`, `select`, `selectionchange`, `hover`, `nodeclick`, `edgeclick`, `groupclick`, `dragstart`, `drag`, `dragend`, `pin`, `change`, `viewport`, `animationend`, `contextmenu`, `expand`, `explore`.
+`view.on(name, cb)` with `layout`, `history`, `select`, `selectionchange`, `hover`, `nodeclick`, `edgeclick`, `groupclick`, `dragstart`, `drag`, `dragend`, `pin`, `change`, `viewport`, `animationend`, `contextmenu`, `expand`, `stack`, `unstack`, `explore`.
 
 ### Undo / redo
 
@@ -122,6 +122,35 @@ view.expand("api"); view.collapse("api"); view.toggleExpand("api"); view.isExpan
 
 Opt a node out with `expandable: false`, or start it open with `expanded: true`. The toggle text is `expandText` / `collapseText`.
 
+### Stacking (animated fold / unfold)
+
+A node can fold the nodes before or after it underneath itself, with an animation:
+
+```js
+const data = {
+  nodes: [
+    { id: "signed", label: "Contract signed", stackable: "upstream" },                  // can fold its whole history
+    { id: "delivery", label: "Delivery", stackable: "downstream", stacked: true },      // starts folded
+    // …
+  ],
+  edges: [ /* … */ ]
+};
+
+view.stack("signed");      // the previous nodes slide in underneath it; it shows a card stack and "+6"
+view.unstack("signed");    // they come back out from underneath and move to their places
+view.toggleStack("delivery"); view.isStacked("delivery"); view.getStacked("delivery"); view.unstackAll();
+
+view.addNodes({ nodes: [...], edges: [...] }, { from: "golive" });   // new nodes come out from underneath "golive"
+view.removeNodes(["a", "b"], { to: "c" });                          // nodes slide into "c" and disappear
+```
+
+- `stackable: "upstream"` folds every node that leads into this one; nodes that also lead somewhere else stay visible.
+- `stackable: "downstream"` (or `true`) folds everything after the node; nodes that are also reached from elsewhere stay visible.
+- A round toggle on the node edge shows `−`, or `+N` while folded. Lines into a stack are drawn dashed to the node that holds it.
+- The node you act on keeps its place on screen. Stacking is part of undo / redo and of `exportState()` / `importState()`.
+- `updateGraph(data, { from, to })` animates the same way; new nodes otherwise come out of their first existing predecessor.
+- Follows `animate: false` and `prefers-reduced-motion`.
+
 ### 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.

package/css/graph.css

@@ -317,3 +317,47 @@
   .fg-node, .fg-edge__line, .fg-node__toggle svg { transition: none; }
   .fg-explore .fg-node { animation: none; }
 }
+
+/* ---- stacking: nodes folded under another node ---------------------------- */
+
+/* stacked cards peeking out behind a node that holds a stack */
+.fg-stack {
+  position: absolute;
+  inset: -1px;
+  z-index: -1;
+  border-radius: var(--fg-node-radius);
+  pointer-events: none;
+  box-shadow: 5px 5px 0 -1px var(--fg-node-bg), 5px 5px 0 0 var(--fg-node-border);
+}
+.fg-stack--many {
+  box-shadow:
+    5px 5px 0 -1px var(--fg-node-bg), 5px 5px 0 0 var(--fg-node-border),
+    10px 10px 0 -1px var(--fg-node-bg), 10px 10px 0 0 var(--fg-node-border);
+}
+
+/* the round +/− toggle on the node edge (upstream: entry side, downstream: exit side) */
+.fg-stack-toggle {
+  position: absolute;
+  z-index: 2;
+  min-width: 20px;
+  height: 20px;
+  padding: 0 5px;
+  border: 1px solid var(--fg-node-border);
+  border-radius: 999px;
+  background: var(--fg-node-bg);
+  color: var(--fg-node-text);
+  font: 600 11px/18px system-ui, sans-serif;
+  cursor: pointer;
+  box-shadow: var(--fg-node-shadow);
+  transform: translate(-50%, -50%);
+}
+.fg-stack-toggle:hover, .fg-stack-toggle:focus-visible { border-color: var(--fg-accent); color: var(--fg-accent); outline: none; }
+.fg-stack-toggle--stacked { background: var(--fg-accent); border-color: var(--fg-accent); color: #fff; }
+.fg-stack-toggle--stacked:hover, .fg-stack-toggle--stacked:focus-visible { color: #fff; filter: brightness(1.1); }
+.fg-stack-toggle--top { left: calc(100% - 14px); top: 0; }
+.fg-stack-toggle--bottom { left: calc(100% - 14px); top: 100%; }
+.fg-stack-toggle--left { left: 0; top: calc(100% - 10px); }
+.fg-stack-toggle--right { left: 100%; top: calc(100% - 10px); }
+
+/* lines into a stack are drawn to the node that holds it */
+.fg-edge--proxy .fg-edge__line { stroke-dasharray: 5 4; }