layerchart 2.0.0-next.5 → 2.0.0-next.51

package/dist/components/Ellipse.svelte.d.ts

@@ -0,0 +1,89 @@
+import type { Without } from '../utils/types.js';
+import type { DataProp, DataDrivenStyleProps } from '../utils/dataProp.js';
+export type EllipsePropsWithoutHTML = {
+    /**
+     * The center x position of the ellipse.
+     * - `number`: pixel value (direct)
+     * - `string`: data property name, resolved via xScale
+     * - `function(d)`: accessor called per data item, result passed through xScale
+     *
+     * @default 0
+     */
+    cx?: DataProp;
+    /**
+     * The initial center x position of the ellipse (pixel mode only).
+     *
+     * @default cx
+     */
+    initialCx?: number;
+    /**
+     * The center y position of the ellipse.
+     * - `number`: pixel value (direct)
+     * - `string`: data property name, resolved via yScale
+     * - `function(d)`: accessor called per data item, result passed through yScale
+     *
+     * @default 0
+     */
+    cy?: DataProp;
+    /**
+     * The initial center y position of the ellipse (pixel mode only).
+     *
+     * @default cy
+     */
+    initialCy?: number;
+    /**
+     * The radius of the ellipse on the x-axis.
+     * - `number`: pixel value (direct)
+     * - `string`: data property name, resolved via rScale
+     * - `function(d)`: accessor called per data item, result passed through rScale
+     *
+     * @default 1
+     */
+    rx?: DataProp;
+    /**
+     * The initial radius of the ellipse on the x-axis (pixel mode only).
+     *
+     * @default rx
+     */
+    initialRx?: number;
+    /**
+     * The radius of the ellipse on the y-axis.
+     * - `number`: pixel value (direct)
+     * - `string`: data property name, resolved via rScale
+     * - `function(d)`: accessor called per data item, result passed through rScale
+     *
+     * @default 1
+     */
+    ry?: DataProp;
+    /**
+     * The initial radius of the ellipse on the y-axis (pixel mode only).
+     *
+     * @default ry
+     */
+    initialRy?: number;
+    /**
+     * Data array to iterate over in data mode.
+     * Falls back to chart context data when not provided.
+     */
+    data?: any[];
+    /**
+     * Key function for keyed {#each} rendering in data mode.
+     *
+     * @default (d, i) => i
+     */
+    key?: (d: any, index: number) => any;
+    /**
+     * A bindable reference to the `<ellipse>` element (pixel mode only).
+     *
+     * @bindable
+     */
+    ref?: SVGEllipseElement;
+    /** Motion configuration (pixel mode only). */
+    motion?: MotionProp;
+} & DataDrivenStyleProps;
+export type EllipseProps = EllipsePropsWithoutHTML & Without<SVGAttributes<Element>, EllipsePropsWithoutHTML>;
+import { type MotionProp } from '../utils/motion.svelte.js';
+import type { SVGAttributes } from 'svelte/elements';
+declare const Ellipse: import("svelte").Component<EllipseProps, {}, "ref">;
+type Ellipse = ReturnType<typeof Ellipse>;
+export default Ellipse;

package/dist/components/Ellipse.svelte.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/Ellipse.svelte.test.js

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest';
+import { render } from 'vitest-browser-svelte';
+import { page } from 'vitest/browser';
+import TestHarness, { componentTestId } from './tests/TestHarness.svelte';
+import Ellipse from './Ellipse.svelte';
+describe('Ellipse', () => {
+    describe('pixel mode', () => {
+        it('should render an ellipse with pixel values', async () => {
+            render(TestHarness, {
+                component: Ellipse,
+                componentProps: {
+                    cx: 50,
+                    cy: 50,
+                    rx: 30,
+                    ry: 20,
+                    fill: 'red',
+                },
+            });
+            const el = page.getByTestId(componentTestId);
+            await expect.element(el).toBeInTheDocument();
+            expect(el.element()?.getAttribute('cx')).toBe('50');
+            expect(el.element()?.getAttribute('cy')).toBe('50');
+            expect(el.element()?.getAttribute('rx')).toBe('30');
+            expect(el.element()?.getAttribute('ry')).toBe('20');
+        });
+    });
+    describe('data mode', () => {
+        const data = [
+            { date: new Date('2024-01-01'), value: 20 },
+            { date: new Date('2024-02-01'), value: 40 },
+            { date: new Date('2024-03-01'), value: 60 },
+        ];
+        it('should render one ellipse per data item with string accessors', async () => {
+            render(TestHarness, {
+                component: Ellipse,
+                chartProps: {
+                    data,
+                    x: 'date',
+                    y: 'value',
+                    yDomain: [0, 100],
+                },
+                componentProps: {
+                    cx: 'date',
+                    cy: 'value',
+                    rx: 10,
+                    ry: 5,
+                },
+            });
+            const ellipses = page.getByTestId(componentTestId).elements();
+            await expect.poll(() => ellipses.length).toBe(3);
+        });
+        it('should resolve data-driven fill through cScale', async () => {
+            const colorData = [
+                { date: new Date('2024-01-01'), value: 20, category: 'A' },
+                { date: new Date('2024-02-01'), value: 40, category: 'B' },
+                { date: new Date('2024-03-01'), value: 60, category: 'A' },
+            ];
+            render(TestHarness, {
+                component: Ellipse,
+                chartProps: {
+                    data: colorData,
+                    x: 'date',
+                    y: 'value',
+                    yDomain: [0, 100],
+                    c: 'category',
+                    cRange: ['steelblue', 'coral'],
+                },
+                componentProps: {
+                    cx: 'date',
+                    cy: 'value',
+                    rx: 10,
+                    ry: 5,
+                    fill: 'category',
+                },
+            });
+            const ellipses = page.getByTestId(componentTestId).elements();
+            await expect.poll(() => ellipses.length).toBe(3);
+            expect(ellipses[0].getAttribute('fill')).toBe('steelblue');
+            expect(ellipses[1].getAttribute('fill')).toBe('coral');
+            expect(ellipses[2].getAttribute('fill')).toBe('steelblue');
+        });
+        it('should pass literal CSS colors through unchanged in data mode', async () => {
+            render(TestHarness, {
+                component: Ellipse,
+                chartProps: {
+                    data,
+                    x: 'date',
+                    y: 'value',
+                    yDomain: [0, 100],
+                },
+                componentProps: {
+                    cx: 'date',
+                    cy: 'value',
+                    rx: 10,
+                    ry: 5,
+                    fill: 'red',
+                },
+            });
+            const ellipses = page.getByTestId(componentTestId).elements();
+            await expect.poll(() => ellipses.length).toBe(3);
+            expect(ellipses[0].getAttribute('fill')).toBe('red');
+            expect(ellipses[1].getAttribute('fill')).toBe('red');
+        });
+        it('should use explicit data prop over chart context data', async () => {
+            const explicitData = [{ date: new Date('2024-01-01'), value: 20 }];
+            render(TestHarness, {
+                component: Ellipse,
+                chartProps: {
+                    data,
+                    x: 'date',
+                    y: 'value',
+                    yDomain: [0, 100],
+                },
+                componentProps: {
+                    data: explicitData,
+                    cx: 'date',
+                    cy: 'value',
+                    rx: 10,
+                    ry: 5,
+                },
+            });
+            const ellipses = page.getByTestId(componentTestId).elements();
+            await expect.poll(() => ellipses.length).toBe(1);
+        });
+    });
+});

package/dist/components/ForceSimulation.svelte

@@ -1,8 +1,22 @@
 <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>>;
+  export type Forces<
+    NodeDatum extends SimulationNodeDatum,
+    LinkDatum extends SimulationLinkDatum<NodeDatum> | undefined,
+  > = Record<string, Force<NodeDatum, LinkDatum>>;
+
+  export type Data<TNode = any, TLink = any> = {
+    nodes: TNode[];
+    links?: TLink[];
+  };
 
   export type LinkPosition = {
     x1: number;
@@ -11,44 +25,115 @@
     y2: number;
   };
 
-  export type ForceSimulationProps = {
+  export type OnStartEvent<
+    NodeDatum extends SimulationNodeDatum,
+    LinkDatum extends SimulationLinkDatum<NodeDatum> | undefined,
+  > = {
+    alpha: number;
+    alphaTarget: number;
+    simulation: Simulation<NodeDatum, LinkDatum>;
+  };
+
+  export type OnTickEvent<
+    NodeDatum extends SimulationNodeDatum,
+    LinkDatum extends SimulationLinkDatum<NodeDatum> | undefined,
+  > = {
+    alpha: number;
+    alphaTarget: number;
+    nodes: NodeDatum[];
+    links: LinkDatum[];
+    simulation: Simulation<NodeDatum, LinkDatum>;
+  };
+
+  export type OnEndEvent<
+    NodeDatum extends SimulationNodeDatum,
+    LinkDatum extends SimulationLinkDatum<NodeDatum> | undefined,
+  > = {
+    alpha: number;
+    alphaTarget: number;
+    simulation: Simulation<NodeDatum, LinkDatum>;
+  };
+
+  export type OnNodesChangeEvent<
+    NodeDatum extends SimulationNodeDatum,
+    LinkDatum extends SimulationLinkDatum<NodeDatum> | undefined,
+  > = {
+    alpha: number;
+    alphaTarget: number;
+    nodes: NodeDatum[];
+    links: LinkDatum[];
+    simulation: Simulation<NodeDatum, LinkDatum>;
+  };
+
+  /**
+   * Default initial alpha value of the simulation.
+   */
+  export const DEFAULT_ALPHA: number = 1;
+
+  /**
+   * Default target alpha value for the simulation.
+   */
+  export const DEFAULT_ALPHA_TARGET: number = 0;
+
+  /**
+   * Default alpha decay rate per tick.
+   *
+   * Formula: `1 - Math.pow(0.001, 1 / 300)`.
+   */
+  export const DEFAULT_ALPHA_DECAY: number = 1 - Math.pow(0.001, 1 / 300);
+
+  /**
+   * Default minimum alpha value at which simulation stops.
+   */
+  export const DEFAULT_ALPHA_MIN: number = 0.01;
+
+  /**
+   * Default velocity decay factor applied to nodes each tick.
+   */
+  export const DEFAULT_VELOCITY_DECAY: number = 0.4;
+
+  export type ForceSimulationProps<
+    NodeDatum extends SimulationNodeDatum,
+    LinkDatum extends SimulationLinkDatum<NodeDatum> | undefined,
+  > = {
     /**
      * Force simulation parameters
      */
-    forces: Forces;
+    forces: Forces<NodeDatum, LinkDatum>;
 
     /**
-     * An array of links to be used for position calculation.
+     * An object with arrays of nodes and links,
+     * to be used for position calculation.
      */
-    links?: any[];
+    data: Data<NodeDatum, LinkDatum>;
 
     /**
      * Current alpha value of the simulation
-     * @default 1
+     * @default DEFAULT_ALPHA
      */
     alpha?: number;
 
     /**
      * Target alpha value for the simulation
-     * @default 0
+     * @default DEFAULT_ALPHA_TARGET
      */
     alphaTarget?: number;
 
     /**
      * Alpha decay rate per tick
-     * @default 1 - Math.pow(0.001, 1 / 300)
+     * @default DEFAULT_ALPHA_DECAY
      */
     alphaDecay?: number;
 
     /**
      * Minimum alpha value at which simulation stops
-     * @default 0.01
+     * @default DEFAULT_ALPHA_MIN
      */
     alphaMin?: number;
 
     /**
      * Velocity decay factor applied to nodes each tick
-     * @default 0.4
+     * @default DEFAULT_VELOCITY_DECAY
      */
     velocityDecay?: number;
 
@@ -73,65 +158,78 @@
     /**
      * Callback function triggered when simulation starts
      */
-    onStart?: () => void;
+    onStart?: (e: OnStartEvent<NodeDatum, LinkDatum | undefined>) => void;
+
+    /**
+     * Callback function triggered right before nodes get passed to the simulation
+     */
+    onNodesChange?: (e: OnNodesChangeEvent<NodeDatum, LinkDatum | undefined>) => void;
 
     /**
      * Callback function triggered on each simulation tick
      */
-    onTick?: (e: { alpha: number; alphaTarget: number }) => void;
+    onTick?: (e: OnTickEvent<NodeDatum, LinkDatum | undefined>) => void;
 
     /**
      * Callback function triggered when simulation ends
      */
-    onEnd?: () => void;
+    onEnd?: (e: OnEndEvent<NodeDatum, LinkDatum | undefined>) => void;
 
     children?: Snippet<
       [
         {
-          nodes: any[];
-          simulation: Simulation<SimulationNodeDatum, undefined>;
+          nodes: NodeDatum[];
+          links: LinkDatum[];
           linkPositions: LinkPosition[];
+          simulation: Simulation<NodeDatum, LinkDatum>;
         },
       ]
     >;
   };
 </script>
 
-<script lang="ts">
-  import { getChartContext } from './Chart.svelte';
+<script
+  lang="ts"
+  generics="NodeDatum extends SimulationNodeDatum,
+    LinkDatum extends SimulationLinkDatum<NodeDatum> | undefined,"
+>
   import { watch } from 'runed';
 
   let {
     forces,
-    links = [],
-    alpha = $bindable(1),
-    alphaTarget = 0,
-    alphaDecay = 1 - Math.pow(0.001, 1 / 300),
-    alphaMin = 0.001,
-    velocityDecay = 0.4,
+    data,
+    alpha = $bindable(DEFAULT_ALPHA),
+    alphaTarget = DEFAULT_ALPHA_TARGET,
+    alphaDecay = DEFAULT_ALPHA_DECAY,
+    alphaMin = DEFAULT_ALPHA_MIN,
+    velocityDecay = DEFAULT_VELOCITY_DECAY,
     stopped = false,
     static: staticProp,
-    onStart: onStartProp = () => {},
-    onTick: onTickProp = () => {},
-    onEnd: onEndProp = () => {},
+    onStart: onStartProp,
+    onNodesChange: onNodesChangeProp,
+    onTick: onTickProp,
+    onEnd: onEndProp,
     children,
     cloneNodes = false,
-  }: ForceSimulationProps = $props();
-
-  const ctx = getChartContext();
+  }: ForceSimulationProps<NodeDatum, LinkDatum> = $props();
 
   // MARK: Public Props
 
   // MARK: Private Props
 
-  let nodes: SimulationNodeDatum[] = $state([]);
   let linkPositions: LinkPosition[] = $state([]);
+  let simulatedNodes: NodeDatum[] = $state([]);
+  let simulatedLinks: LinkDatum[] = $derived(data.links ?? []);
 
-  const simulation = forceSimulation().stop();
+  // This casting is unfortunately necessary, due to unfortunate
+  // overloading choices made, over at `@typed/d3-force`:
+  const simulation: Simulation<NodeDatum, LinkDatum> = (
+    forceSimulation<NodeDatum>() as Simulation<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`.
-  let previousForces: Forces = {};
+  let previousForces: Forces<NodeDatum, LinkDatum> = {};
 
   let paused: boolean = true;
 
@@ -166,11 +264,12 @@
   );
 
   watch.pre(
-    () => ctx.data,
+    () => data,
     () => {
-      // Any time the `data` store gets changed we
-      // pass them to the internal d3 simulation object:
-      pushNodesToSimulation(ctx.data as any[]);
+      // Any time the `nodes` prop, or the `data` store gets changed
+      // we pass them to the internal d3 simulation object:
+      onNodesChange();
+      pushNodesToSimulation(data.nodes);
       runOrResumeSimulation();
     }
   );
@@ -192,12 +291,8 @@
       // pass it to the internal d3 simulation object:
       pushAlphaToSimulation(alpha);
 
-      // Only resume the simulation as long as `alpha`
-      // is above the cut-off threshold of `alphaMin`,
-      // otherwise our simulation will never terminate:
-      if (simulation.alpha() >= simulation.alphaMin()) {
-        runOrResumeSimulation();
-      }
+      // Then we attempt to resume the simulation:
+      runOrResumeSimulation();
     }
   );
 
@@ -235,7 +330,7 @@
     simulation.nodes(nodes);
   }
 
-  function pushForcesToSimulation(forces: Forces) {
+  function pushForcesToSimulation(forces: Forces<NodeDatum, LinkDatum>) {
     // Evict obsolete forces:
     const names = Object.keys(previousForces);
     for (const name of names) {
@@ -259,7 +354,7 @@
     // 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,
@@ -270,7 +365,8 @@
   // MARK: Pull State
 
   function pullNodesFromSimulation() {
-    nodes = cloneNodes ? structuredClone(simulation.nodes()) : simulation.nodes();
+    const simulationNodes = simulation.nodes();
+    simulatedNodes = cloneNodes ? structuredClone(simulationNodes) : simulationNodes;
   }
 
   function pullAlphaFromSimulation() {
@@ -337,6 +433,13 @@
       return;
     }
 
+    if (simulation.alpha() < simulation.alphaMin()) {
+      // Only resume the simulation as long as `alpha`
+      // is above the cut-off threshold of `alphaMin`,
+      // otherwise our simulation will never terminate:
+      return;
+    }
+
     onStart();
     simulation.restart();
 
@@ -364,7 +467,12 @@
     }
 
     paused = false;
-    onStartProp();
+
+    onStartProp?.({
+      alpha,
+      alphaTarget,
+      simulation,
+    });
   }
 
   function onTick() {
@@ -372,7 +480,13 @@
     pullAlphaFromSimulation();
     updateLinkPositions();
 
-    onTickProp({ alpha, alphaTarget });
+    onTickProp?.({
+      alpha,
+      alphaTarget,
+      nodes: simulatedNodes,
+      links: simulatedLinks,
+      simulation,
+    });
   }
 
   function onEnd() {
@@ -382,7 +496,22 @@
     }
 
     paused = true;
-    onEndProp();
+
+    onEndProp?.({
+      alpha,
+      alphaTarget,
+      simulation,
+    });
+  }
+
+  function onNodesChange() {
+    onNodesChangeProp?.({
+      alpha,
+      alphaTarget,
+      nodes: data.nodes,
+      links: data.links ?? [],
+      simulation,
+    });
   }
 
   $effect(() => {
@@ -393,4 +522,9 @@
   });
 </script>
 
-{@render children?.({ nodes: nodes, simulation, linkPositions })}
+{@render children?.({
+  nodes: simulatedNodes,
+  links: simulatedLinks,
+  simulation,
+  linkPositions,
+})}