Make ForceSimulation generic over its nodes and links, i.e. ForceSimulation<Node, Link> (#527)

* Make `ForceSimulation` generic over its nodes and links, i.e. `ForceSimulation<Node, Link>`

* Expose `links` via `children` snippet of `ForceSimulation`

* Fix breakages

* Add changeset

Author: regexident

.changeset/crazy-friends-talk.md

@@ -0,0 +1,6 @@
+---
+'layerchart': minor
+---
+
+- Made `ForceSimulation` generic over its nodes and links, i.e. `ForceSimulation<Node, Link>.`
+- Exposed `links` via `children` snippet of `ForceSimulation`.

packages/layerchart/src/lib/components/ForceSimulation.svelte

@@ -1,5 +1,11 @@
 <script lang="ts" module>
-  import { forceSimulation, type Force, type Simulation, type SimulationNodeDatum } from 'd3-force';
+  import {
+    forceSimulation,
+    type Force,
+    type Simulation,
+    type SimulationLinkDatum,
+    type SimulationNodeDatum,
+  } from 'd3-force';
   import type { Snippet } from 'svelte';
 
   type Forces = Record<string, Force<any, any>>;
@@ -9,14 +15,24 @@
     links?: TLink[];
   };
 
-  export type LinkPosition = {
+  export type LinkPosition = Prettify<{
     x1: number;
     y1: number;
     x2: number;
     y2: number;
-  };
+  }>;
+
+  type NodeDatumFor<NodeDatum> = Prettify<NodeDatum & SimulationNodeDatum>;
+  type LinkDatumFor<NodeDatum, LinkDatum> = Prettify<
+    LinkDatum & SimulationLinkDatum<NodeDatumFor<NodeDatum>>
+  >;
+
+  type SimulationFor<NodeDatum, LinkDatum> = Simulation<
+    NodeDatumFor<NodeDatum>,
+    LinkDatumFor<NodeDatum, LinkDatum>
+  >;
 
-  export type ForceSimulationProps = {
+  export type ForceSimulationProps<NodeDatum, LinkDatum> = {
     /**
      * Force simulation parameters
      */
@@ -26,7 +42,7 @@
      * An object with arrays of nodes and links,
      * to be used for position calculation.
      */
-    data: Data;
+    data: Data<NodeDatum, LinkDatum>;
 
     /**
      * Current alpha value of the simulation
@@ -94,17 +110,19 @@
     children?: Snippet<
       [
         {
-          nodes: any[];
-          simulation: Simulation<SimulationNodeDatum, undefined>;
+          nodes: NodeDatumFor<NodeDatum>[];
+          links: LinkDatumFor<NodeDatum, LinkDatum>[];
           linkPositions: LinkPosition[];
+          simulation: SimulationFor<NodeDatum, LinkDatum>;
         },
       ]
     >;
   };
 </script>
 
-<script lang="ts">
+<script lang="ts" generics="NodeDatum, LinkDatum = undefined">
   import { watch } from 'runed';
+  import type { Prettify } from '@layerstack/utils';
 
   let {
     forces,
@@ -121,16 +139,23 @@
     onEnd: onEndProp = () => {},
     children,
     cloneNodes = false,
-  }: ForceSimulationProps = $props();
+  }: ForceSimulationProps<NodeDatum, LinkDatum> = $props();
 
   // MARK: Public Props
 
   // MARK: Private Props
 
-  let simulatedNodes: SimulationNodeDatum[] = $state([]);
   let linkPositions: LinkPosition[] = $state([]);
+  let simulatedNodes: NodeDatumFor<NodeDatum>[] = $state([]);
+  let simulatedLinks: LinkDatumFor<NodeDatum, LinkDatum>[] = $derived(
+    (data.links ?? []) as LinkDatumFor<NodeDatum, LinkDatum>[]
+  );
 
-  const simulation = forceSimulation().stop();
+  // This casting is unfortunately necessary, due to unfortunate
+  // overloading choices made, over at `@typed/d3-force`:
+  const simulation: SimulationFor<NodeDatum, LinkDatum> = (
+    forceSimulation() as SimulationFor<NodeDatum, LinkDatum>
+  ).stop();
 
   // d3.Simulation does not provide a `.forces()` getter, so we need to
   // keep track of previous forces ourselves, for diffing against `forces`.
@@ -259,12 +284,10 @@
   }
 
   function updateLinkPositions() {
-    const links = data.links ?? [];
-
     // Keeping the link positions in sync with the simulation
     // so we don't need to recalculate _all_ link positions on each tick
     // which bogs down the simulation
-    linkPositions = links.map((link: any) => ({
+    linkPositions = simulatedLinks.map((link: any) => ({
       x1: link.source.x ?? 0,
       y1: link.source.y ?? 0,
       x2: link.target.x ?? 0,
@@ -275,7 +298,8 @@
   // MARK: Pull State
 
   function pullNodesFromSimulation() {
-    simulatedNodes = cloneNodes ? structuredClone(simulation.nodes()) : simulation.nodes();
+    const simulationNodes = simulation.nodes();
+    simulatedNodes = cloneNodes ? structuredClone(simulationNodes) : simulationNodes;
   }
 
   function pullAlphaFromSimulation() {
@@ -398,4 +422,9 @@
   });
 </script>
 
-{@render children?.({ nodes: simulatedNodes, simulation, linkPositions })}
+{@render children?.({
+  nodes: simulatedNodes,
+  links: simulatedLinks,
+  simulation,
+  linkPositions,
+})}

packages/layerchart/src/routes/docs/examples/CollisionDetection/+page.svelte

@@ -48,7 +48,12 @@
               <Group center>
                 {#each nodes as node, i}
                   {#if i > 0}
-                    <Circle cx={node.x} cy={node.y} r={node.r} fill={groupColor(node.group)} />
+                    <Circle
+                      cx={node.x}
+                      cy={node.y}
+                      r={node.r}
+                      fill={groupColor(node.group.toString())}
+                    />
                   {/if}
                 {/each}
               </Group>

packages/layerchart/src/routes/docs/examples/ForceDisjointGraph/+page.svelte

@@ -1,5 +1,12 @@
 <script lang="ts">
-  import { forceManyBody, forceLink, forceX, forceY } from 'd3-force';
+  import {
+    forceManyBody,
+    forceLink,
+    forceX,
+    forceY,
+    type SimulationNodeDatum,
+    type SimulationLinkDatum,
+  } from 'd3-force';
   import { curveLinear } from 'd3-shape';
   import { scaleOrdinal } from 'd3-scale';
   import { schemeCategory10 } from 'd3-scale-chromatic';
@@ -10,8 +17,19 @@
 
   let { data } = $props();
 
-  const nodes = data.miserables.nodes;
-  const links = data.miserables.links;
+  type Node = {
+    id: string;
+    group: number;
+  };
+
+  type Link = {
+    source: string;
+    target: string;
+    value: number;
+  };
+
+  const nodes: (Node & SimulationNodeDatum)[] = data.miserables.nodes;
+  const links: (Link & SimulationLinkDatum<Node & SimulationNodeDatum>)[] = data.miserables.links;
 
   const colorScale = scaleOrdinal(schemeCategory10);
 
@@ -20,6 +38,10 @@
   const chargeForce = forceManyBody().strength(-30).theta(0.9);
   const xForce = forceX();
   const yForce = forceY();
+
+  function keyForLink(link: Link & SimulationLinkDatum<Node & SimulationNodeDatum>): any {
+    return link.value + link.index!;
+  }
 </script>
 
 <h1>Examples</h1>
@@ -41,8 +63,8 @@
           }}
           data={{ nodes, links }}
         >
-          {#snippet children({ nodes, linkPositions })}
-            {#each links as link, i (link.value + link.index)}
+          {#snippet children({ nodes, links, linkPositions })}
+            {#each links as link, i (keyForLink(link))}
               <Link
                 data={link}
                 explicitCoords={linkPositions[i]}
@@ -52,7 +74,7 @@
             {/each}
 
             {#each nodes as node}
-              <Circle cx={node.x} cy={node.y} r={3} fill={colorScale(node.group)} />
+              <Circle cx={node.x} cy={node.y} r={3} fill={colorScale(node.group.toString())} />
             {/each}
           {/snippet}
         </ForceSimulation>

packages/layerchart/src/routes/docs/examples/ForceGraph/+page.svelte

@@ -1,5 +1,12 @@
 <script lang="ts">
-  import { forceCollide, forceManyBody, forceLink, forceCenter } from 'd3-force';
+  import {
+    forceCollide,
+    forceManyBody,
+    forceLink,
+    forceCenter,
+    type SimulationNodeDatum,
+    type SimulationLinkDatum,
+  } from 'd3-force';
   import { curveLinear } from 'd3-shape';
   import { scaleOrdinal } from 'd3-scale';
   import { schemeCategory10 } from 'd3-scale-chromatic';
@@ -11,8 +18,19 @@
 
   let { data } = $props();
 
-  const nodes = data.miserables.nodes;
-  const links = data.miserables.links;
+  type Node = {
+    id: string;
+    group: number;
+  };
+
+  type Link = {
+    source: string;
+    target: string;
+    value: number;
+  };
+
+  const nodes: (Node & SimulationNodeDatum)[] = data.miserables.nodes;
+  const links: (Link & SimulationLinkDatum<Node & SimulationNodeDatum>)[] = data.miserables.links;
 
   const colorScale = scaleOrdinal(schemeCategory10);
 
@@ -288,7 +306,7 @@
                   cx={node.x}
                   cy={node.y}
                   r={nodeRadius}
-                  fill={colorScale(node.group)}
+                  fill={colorScale(node.group.toString())}
                   stroke-width={nodeStrokeWidth}
                   class="stroke-surface-content"
                   onpointermove={(e) => context.tooltip.show(e, node)}