@sentropic/design-system-react 0.10.0 → 0.11.0

package/dist/catalog.js

@@ -518,10 +518,32 @@ function forceGraphMulberry32(seed) {
         return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
     };
 }
+// Stable seed from the SET of node ids (sorted), not from ns.length/es.length.
+// A length-based seed reshuffled the whole layout whenever a node was added or
+// removed (notably after a reconciliation merge), making the graph "jump". A
+// hash over the sorted ids keeps the same topology → same layout, so removing
+// one node leaves the rest essentially in place. (FNV-1a 32-bit over the joined
+// sorted ids; deterministic and order-independent.) PORTED VERBATIM from the
+// Svelte `stableSeed` so the three frameworks produce the SAME layout.
+function forceGraphStableSeed(ns) {
+    const ids = ns.map((n) => n.id).sort();
+    let h = 0x811c9dc5; // FNV offset basis
+    const joined = ids.join("|");
+    for (let i = 0; i < joined.length; i++) {
+        h ^= joined.charCodeAt(i);
+        h = Math.imul(h, 0x01000193); // FNV prime
+    }
+    // Fold in the count too so wholly different graphs of equal id-hash still
+    // differ, but the dominant term is the (order-independent) id hash.
+    h ^= ns.length;
+    return h >>> 0;
+}
 function runForceGraphSimulation(ns, es, w, h, ticks, nodeRadius, repulsionFactor) {
     const cx = w / 2;
     const cy = h / 2;
-    const rand = forceGraphMulberry32(ns.length * 2654435761 + es.length);
+    // Seed from the stable id-set hash so adding/removing a node does not
+    // reshuffle the whole layout (same topology → same layout).
+    const rand = forceGraphMulberry32(forceGraphStableSeed(ns));
     const idIndex = new Map();
     const sim = ns.map((n, i) => {
         idIndex.set(n.id, i);
@@ -628,9 +650,15 @@ function runForceGraphSimulation(ns, es, w, h, ticks, nodeRadius, repulsionFacto
 // Curvature offset factor: how far (relative to chord length) the control
 // point bows out at edgeCurve=1. Kept modest so edgeCurve≈0.15 reads "light".
 const FORCE_GRAPH_CURVE_FACTOR = 0.5;
+// Merge (reconciliation) glide duration.
+const FORCE_GRAPH_MERGE_DURATION_MS = 450;
+// ease-in-out (cubic) for a smooth glide.
+function forceGraphEaseInOut(t) {
+    return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+}
 // Fit-to-content margin (per side, fraction of the content box).
 const FORCE_GRAPH_CONTENT_MARGIN = 0.08;
-export function ForceGraph({ nodes, edges, label, width = 480, height = 360, nodeRadius = 7, showLabels = true, iterations = 300, selectedIds = [], focusId = null, onSelect, onOpenEntity, onEdgeHover, legend, edgeCurve = 0.15, repulsion = 1, onNodeHover, className, ...rest }) {
+export function ForceGraph({ nodes, edges, label, width = 480, height = 360, nodeRadius = 7, showLabels = true, iterations = 300, selectedIds = [], focusId = null, onSelect, onOpenEntity, onEdgeHover, legend, edgeCurve = 0.15, repulsion = 1, onNodeHover, mergePair = null, onMergeComplete, className, ...rest }) {
     // SSR-safe reduced-motion check (window may be undefined during SSR/tests).
     const prefersReducedMotion = typeof window !== "undefined" &&
         typeof window.matchMedia === "function" &&
@@ -746,6 +774,144 @@ export function ForceGraph({ nodes, edges, label, width = 480, height = 360, nod
     }, [positionedNodes, width, height]);
     const [hoveredNodeIndex, setHoveredNodeIndex] = React.useState(null);
     const [hoveredEdgeIndex, setHoveredEdgeIndex] = React.useState(null);
+    const [mergeState, setMergeState] = React.useState(null);
+    // The id of the `from` node to keep MASKED after a completed merge, until the
+    // consumer drops it from `nodes` (or a new pair arrives). Decouples the mask
+    // from `mergePair` returning to null (otherwise the node would flash back).
+    const [maskedFromId, setMaskedFromId] = React.useState(null);
+    // The id currently being (or already) handled, so the effect only reacts to a
+    // genuinely NEW id. Re-passing the same id (even a fresh object) is a no-op.
+    const handledMergeIdRef = React.useRef(null);
+    // Set true on unmount so no queued microtask/frame fires a callback or touches
+    // state after teardown.
+    const disposedRef = React.useRef(false);
+    // Latest layout / callback, read inside the effect without retriggering it.
+    const layoutRef = React.useRef(layout);
+    layoutRef.current = layout;
+    const onMergeCompleteRef = React.useRef(onMergeComplete);
+    onMergeCompleteRef.current = onMergeComplete;
+    const mergeId = mergePair ? mergePair.id : null;
+    // Component-lifetime teardown guard: mark disposed on unmount.
+    React.useEffect(() => {
+        return () => {
+            disposedRef.current = true;
+        };
+    }, []);
+    React.useEffect(() => {
+        const pair = mergePair;
+        const id = pair ? pair.id : null;
+        // Idempotent on id: same id (or still null) means nothing to (re)start. A
+        // new id always (re)plays, even for the same from/into pair.
+        if (id === handledMergeIdRef.current)
+            return;
+        handledMergeIdRef.current = id;
+        // Tear down any in-flight animation for a previous pair.
+        setMergeState(null);
+        if (!pair)
+            return;
+        // A genuinely new pair supersedes any lingering mask from a prior merge.
+        setMaskedFromId(null);
+        let raf = null;
+        let cancelled = false;
+        // Validate: both endpoints must currently exist.
+        const lay = layoutRef.current;
+        const fromPos = lay.get(pair.from);
+        const intoPos = lay.get(pair.into);
+        if (!fromPos || !intoPos)
+            return; // invalid pair → no-op, no callback
+        const captured = { id: pair.id, from: pair.from, into: pair.into };
+        const complete = () => {
+            // Keep `from` hidden until the consumer removes it (or a new pair arrives).
+            setMaskedFromId(captured.from);
+            onMergeCompleteRef.current?.(captured);
+        };
+        // Reduced motion: no animation, resolve on a microtask. Guarded so a late
+        // microtask after unmount or after a newer id took over is a no-op.
+        if (prefersReducedMotion || typeof requestAnimationFrame !== "function") {
+            queueMicrotask(() => {
+                if (disposedRef.current || cancelled || handledMergeIdRef.current !== id)
+                    return;
+                complete();
+            });
+            return () => {
+                cancelled = true;
+            };
+        }
+        const dx = intoPos.x - fromPos.x;
+        const dy = intoPos.y - fromPos.y;
+        setMergeState({ id: captured.id, from: captured.from, into: captured.into, progress: 0, dx, dy });
+        let start = null;
+        const tick = (now) => {
+            // Bail cleanly if the instance went away or a newer id superseded us.
+            if (disposedRef.current || cancelled || handledMergeIdRef.current !== id) {
+                raf = null;
+                return;
+            }
+            // Re-validate both endpoints every frame: if either disappears mid-flight
+            // (e.g. the consumer removed a node), cancel the glide WITHOUT firing
+            // onMergeComplete (no double-tir) and without a dangling frame.
+            const live = layoutRef.current;
+            if (!live.has(captured.from) || !live.has(captured.into)) {
+                raf = null;
+                setMergeState(null);
+                return;
+            }
+            if (start === null)
+                start = now;
+            const t = Math.min(1, Math.max(0, (now - start) / FORCE_GRAPH_MERGE_DURATION_MS));
+            setMergeState((prev) => (prev ? { ...prev, progress: t } : prev));
+            if (t < 1) {
+                raf = requestAnimationFrame(tick);
+            }
+            else {
+                raf = null;
+                setMergeState(null);
+                complete();
+            }
+        };
+        raf = requestAnimationFrame(tick);
+        return () => {
+            cancelled = true;
+            if (raf != null && typeof cancelAnimationFrame === "function") {
+                cancelAnimationFrame(raf);
+            }
+        };
+        // Re-run only when the pair's id changes (not on unrelated re-renders).
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [mergeId, prefersReducedMotion]);
+    // Eased progress of the `from` node toward `into`. 0 when no merge running.
+    const mergeFromId = mergeState?.from ?? null;
+    const mergeEased = mergeState ? forceGraphEaseInOut(mergeState.progress) : 0;
+    /** True when this id is the (post-merge) masked node — render it fully hidden. */
+    function isMasked(id) {
+        return maskedFromId === id;
+    }
+    /** Extra translation applied to the merging node so it glides toward `into`. */
+    function mergeOffset(id) {
+        if (!mergeState || mergeState.from !== id)
+            return { x: 0, y: 0 };
+        return { x: mergeState.dx * mergeEased, y: mergeState.dy * mergeEased };
+    }
+    /**
+     * Opacity for a node during/after a merge. The animating `from` fades 1->0; a
+     * masked `from` (merge done, awaiting removal) stays at 0. Others unaffected.
+     */
+    function mergeNodeOpacity(id) {
+        if (isMasked(id))
+            return 0;
+        if (mergeFromId !== id)
+            return undefined;
+        return 1 - mergeEased;
+    }
+    /** Opacity for an edge incident to the merging/masked `from` node (fades too). */
+    function mergeEdgeOpacity(e) {
+        const fromId = mergeFromId ?? maskedFromId;
+        if (fromId == null)
+            return undefined;
+        if (e.source !== fromId && e.target !== fromId)
+            return undefined;
+        return isMasked(fromId) ? 0 : 1 - mergeEased;
+    }
     const selectedSet = React.useMemo(() => new Set(selectedIds), [selectedIds]);
     // Adjacency: id -> set of directly connected node ids. Used to keep the
     // direct neighbours of selected/focused nodes fully visible (demand 6).
@@ -929,9 +1095,10 @@ export function ForceGraph({ nodes, edges, label, width = 480, height = 360, nod
                                 onEdgeHover?.(e.edge);
                             };
                             const onHitLeave = () => setHoveredEdgeIndex(null);
+                            const mEdgeOpacity = mergeEdgeOpacity(e.edge);
                             const edgeClass = classNames("st-forceGraph__edge", e.edge.weak && "st-forceGraph__edge--weak", e.edge.emphasis && "st-forceGraph__edge--emphasis", hoveredEdgeIndex === e.i && "st-forceGraph__edge--hovered", (isEdgeSelectionDimmed(e.edge) || isHoverDimmedEdge(e.edge)) &&
-                                "st-forceGraph__edge--dim");
-                            return (_jsxs(React.Fragment, { children: [e.path ? (_jsx("path", { className: "st-forceGraph__edgeHit", role: "presentation", d: e.path, fill: "none", onMouseEnter: onHitEnter, onMouseLeave: onHitLeave })) : (_jsx("line", { className: "st-forceGraph__edgeHit", role: "presentation", x1: e.x1, y1: e.y1, x2: e.x2, y2: e.y2, onMouseEnter: onHitEnter, onMouseLeave: onHitLeave })), e.path ? (_jsx("path", { className: edgeClass, d: e.path, fill: "none", strokeDasharray: e.dashArray ?? undefined, strokeWidth: e.strokeWidth ?? undefined, pointerEvents: "none" })) : (_jsx("line", { className: edgeClass, x1: e.x1, y1: e.y1, x2: e.x2, y2: e.y2, strokeDasharray: e.dashArray ?? undefined, strokeWidth: e.strokeWidth ?? undefined, pointerEvents: "none" }))] }, e.i));
+                                "st-forceGraph__edge--dim", mEdgeOpacity !== undefined && "st-forceGraph__edge--merging");
+                            return (_jsxs(React.Fragment, { children: [e.path ? (_jsx("path", { className: "st-forceGraph__edgeHit", role: "presentation", d: e.path, fill: "none", onMouseEnter: onHitEnter, onMouseLeave: onHitLeave })) : (_jsx("line", { className: "st-forceGraph__edgeHit", role: "presentation", x1: e.x1, y1: e.y1, x2: e.x2, y2: e.y2, onMouseEnter: onHitEnter, onMouseLeave: onHitLeave })), e.path ? (_jsx("path", { className: edgeClass, d: e.path, fill: "none", strokeDasharray: e.dashArray ?? undefined, strokeWidth: e.strokeWidth ?? undefined, opacity: mEdgeOpacity, pointerEvents: "none" })) : (_jsx("line", { className: edgeClass, x1: e.x1, y1: e.y1, x2: e.x2, y2: e.y2, strokeDasharray: e.dashArray ?? undefined, strokeWidth: e.strokeWidth ?? undefined, opacity: mEdgeOpacity, pointerEvents: "none" }))] }, e.i));
                         }) }), _jsx("g", { className: "st-forceGraph__nodes", children: positionedNodes.map((p) => {
                             const ariaLabel = `${p.title}${p.node.group !== undefined ? `: ${p.node.group}` : ""}`;
                             const pressed = selectedSet.has(p.node.id);
@@ -961,8 +1128,12 @@ export function ForceGraph({ nodes, edges, label, width = 480, height = 360, nod
                                 onDoubleClick: () => onOpenEntity?.(p.node.id),
                                 onKeyDown: (e) => handleNodeKeydown(p.node.id, e),
                             };
+                            const mOff = mergeOffset(p.node.id);
+                            const mOpacity = mergeNodeOpacity(p.node.id);
+                            const mMasked = isMasked(p.node.id);
                             return (_jsxs("g", { className: classNames("st-forceGraph__node", `st-forceGraph__node--${p.tone}`, (isHoverDimmedNode(p.node.id) || isSelectionDimmed(p.node.id)) &&
-                                    "st-forceGraph__node--dim", pressed && "st-forceGraph__node--selected", focusId === p.node.id && "st-forceGraph__node--focus"), transform: `translate(${p.x} ${p.y})`, children: [p.shapePath ? (_jsx("path", { ...shapeProps, d: p.shapePath })) : (_jsx("circle", { ...shapeProps, r: p.r })), showLabels ? (_jsx("text", { className: "st-forceGraph__label", x: p.r + 3, y: 0, dominantBaseline: "middle", children: p.title })) : null] }, p.node.id));
+                                    "st-forceGraph__node--dim", pressed && "st-forceGraph__node--selected", focusId === p.node.id && "st-forceGraph__node--focus", (mergeFromId === p.node.id || mMasked) &&
+                                    "st-forceGraph__node--merging"), "aria-hidden": mMasked ? "true" : undefined, opacity: mOpacity, transform: `translate(${p.x + mOff.x} ${p.y + mOff.y})`, children: [p.shapePath ? (_jsx("path", { ...shapeProps, d: p.shapePath })) : (_jsx("circle", { ...shapeProps, r: p.r })), showLabels ? (_jsx("text", { className: "st-forceGraph__label", x: p.r + 3, y: 0, dominantBaseline: "middle", children: p.title })) : null] }, p.node.id));
                         }) })] }), hoveredNode ? (_jsxs("div", { className: "st-forceGraph__tooltip", role: "presentation", style: {
                     left: `${((hoveredNode.x - vbX) / vbW) * 100}%`,
                     top: `${((hoveredNode.y - vbY) / vbH) * 100}%`,