solid-recharts 0.1.0

package/src/animation/matchBy.ts

@@ -0,0 +1,211 @@
+// Ported from recharts 3.9.0 src/animation/matchBy.ts.
+// Pure logic — no framework surface. Deviation from the reference is limited to
+// this repo's type discipline (no non-null `!`): the index-bounded `nextItems[i]`
+// access is narrowed with an explicit guard instead of an assertion.
+import type { DataKey } from "../util/types";
+import { getValueByDataKey } from "../util/ChartUtils";
+
+/**
+ * A tagged union describing the status of an item during animation.
+ *
+ * - `matched`: item exists in both previous and next data — interpolate between positions
+ * - `added`: item is new (no previous position) — animate in
+ * - `removed`: item was in previous data but not in next — animate out
+ *
+ * @since 3.9
+ */
+export type AnimationItem<T> =
+  | { readonly status: "matched"; readonly prev: T; readonly next: T }
+  | { readonly status: "added"; readonly next: T }
+  | { readonly status: "removed"; readonly prev: T };
+
+/**
+ * A function that extracts a key from an animation item for matching purposes.
+ * Items in the previous and next arrays that return the same key are considered
+ * the same logical item and will animate between their positions.
+ *
+ * @since 3.9
+ */
+export type AnimationMatchBy<T> = (item: T, index: number) => string | number | null;
+
+/**
+ * The union of all accepted `animationMatchBy` prop values:
+ * a built-in sentinel string, or a custom matching function.
+ *
+ * @since 3.9
+ */
+export type AnimationMatchByProp<T> =
+  | typeof matchByIndex
+  | typeof matchAppend
+  | AnimationMatchBy<T>;
+
+/**
+ * Match animation items by their array index (the default behavior).
+ *
+ * @since 3.9
+ */
+export const matchByIndex = "index" as const;
+
+/**
+ * Match animation items sequentially: previous item 0 pairs with next item 0, etc.
+ * When the new array is longer, the extra items animate in from their default position.
+ * When shorter, the surplus previous items are dropped.
+ *
+ * @since 3.9
+ */
+export const matchAppend = "append" as const;
+
+/**
+ * Create a matching function that pairs items by a data key from their payload.
+ *
+ * Useful for time-series or streaming charts where new data points are added to
+ * one end and old points removed from the other, so existing points animate to
+ * their new positions instead of shifting by index.
+ *
+ * @since 3.9
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === "object";
+}
+
+export function matchByDataKey(
+  dataKey: DataKey<Record<string, unknown>>,
+): AnimationMatchBy<{ payload?: unknown }> {
+  return (item: { payload?: unknown }): string | number | null => {
+    if (!isRecord(item.payload)) return null;
+    const value = getValueByDataKey(item.payload, dataKey);
+    if (value == null) return null;
+    if (typeof value === "string" || typeof value === "number") return value;
+    return JSON.stringify(value);
+  };
+}
+
+function tagAlignedItems<T>(
+  alignedPrevItems: ReadonlyArray<T | undefined>,
+  nextItems: ReadonlyArray<T>,
+  removedPrevItems: ReadonlyArray<T> = [],
+): ReadonlyArray<AnimationItem<T>> {
+  const tagged: AnimationItem<T>[] = [];
+  /*
+   * We put removed points at the start because we assume that a typical chart animates right-to-left
+   * and the removed points will disappear from the left edge and outside the plot area.
+   * If your chart behaves differently you may want to customize your matching function.
+   */
+  for (const prev of removedPrevItems) {
+    tagged.push({ status: "removed", prev });
+  }
+  for (let i = 0; i < nextItems.length; i++) {
+    // This function intentionally pairs by array index. The strategy-specific functions
+    // below produce an alignedPrevItems array whose indices already correspond to nextItems.
+    const prev = alignedPrevItems[i];
+    const next = nextItems[i];
+    if (next === undefined) {
+      continue;
+    }
+    if (prev != null) {
+      tagged.push({ status: "matched", prev, next });
+    } else {
+      tagged.push({ status: "added", next });
+    }
+  }
+  return tagged;
+}
+
+function matchByIndexImpl<T>(
+  prevItems: ReadonlyArray<T>,
+  nextItems: ReadonlyArray<T>,
+): ReadonlyArray<AnimationItem<T>> {
+  const factor = prevItems.length / nextItems.length;
+  const alignedPrevItems = nextItems.map((_, i) => prevItems[Math.floor(i * factor)]);
+  return tagAlignedItems(alignedPrevItems, nextItems);
+}
+
+function matchAppendImpl<T>(
+  prevItems: ReadonlyArray<T>,
+  nextItems: ReadonlyArray<T>,
+): ReadonlyArray<AnimationItem<T>> {
+  const alignedPrevItems = nextItems.map((_, i) => prevItems[i]);
+  return tagAlignedItems(alignedPrevItems, nextItems);
+}
+
+function buildPrevKeyMap<T>(
+  prevItems: ReadonlyArray<T>,
+  matchBy: AnimationMatchBy<T>,
+): ReadonlyMap<string | number, T> {
+  const prevMap = new Map<string | number, T>();
+  for (let i = 0; i < prevItems.length; i++) {
+    const item = prevItems[i];
+    if (item == null) continue;
+    const key = matchBy(item, i);
+    if (key != null && !prevMap.has(key)) {
+      prevMap.set(key, item);
+    }
+  }
+  return prevMap;
+}
+
+/**
+ * Match previous items to next items by key, and include removed items explicitly.
+ *
+ * @internal
+ */
+function matchByKey<T>(
+  prevItems: ReadonlyArray<T>,
+  nextItems: ReadonlyArray<T>,
+  matchBy: AnimationMatchBy<T>,
+): ReadonlyArray<AnimationItem<T>> {
+  const prevMap = buildPrevKeyMap(prevItems, matchBy);
+
+  // Track which prev keys were matched
+  const matchedKeys = new Set<string | number>();
+
+  const alignedPrevItems = nextItems.map((next, i) => {
+    const key = matchBy(next, i);
+    if (key != null) {
+      const prev = prevMap.get(key);
+      if (prev !== undefined) {
+        matchedKeys.add(key);
+        return prev;
+      }
+    }
+    return undefined;
+  });
+
+  // Removed = prev items whose keys were not matched to any next item
+  const removedPrevItems: T[] = [];
+  for (const [key, item] of prevMap) {
+    if (!matchedKeys.has(key)) {
+      removedPrevItems.push(item);
+    }
+  }
+
+  return tagAlignedItems(alignedPrevItems, nextItems, removedPrevItems);
+}
+
+/**
+ * Match previous items to next items using the given matching strategy and return tagged animation items.
+ *
+ * On first render, all next items are returned as `{ status: 'added' }`.
+ * For key-based matching, unmatched previous items are appended as `{ status: 'removed' }`.
+ *
+ * @internal
+ */
+export function matchAnimationItems<T>(
+  prevItems: ReadonlyArray<T> | null,
+  nextItems: ReadonlyArray<T> | undefined,
+  matchBy: AnimationMatchByProp<T>,
+): ReadonlyArray<AnimationItem<T>> | null {
+  if (nextItems == null) {
+    return null;
+  }
+  if (prevItems == null) {
+    return nextItems.map((next) => ({ status: "added", next }));
+  }
+  if (matchBy === matchByIndex) {
+    return matchByIndexImpl(prevItems, nextItems);
+  }
+  if (matchBy === matchAppend) {
+    return matchAppendImpl(prevItems, nextItems);
+  }
+  return matchByKey(prevItems, nextItems, matchBy);
+}

package/src/animation/timeoutController.ts

@@ -0,0 +1,51 @@
+// Ported from recharts 3.8.1 src/animation/timeoutController.ts (commit 7a23854).
+// Pure timer abstraction — no framework surface — so behavior is byte-identical to recharts.
+// Deviations from the reference are limited to satisfying this repo's type
+// discipline (no `as` / no non-null `!`); `as const` is not needed here.
+
+/**
+ * Callback type for the timeout function.
+ * Receives current time in milliseconds as an argument.
+ */
+export type CallbackType = (now: number) => void;
+
+/**
+ * A function that, when called, cancels the timeout.
+ */
+export type CancelableTimeout = () => void;
+
+export interface TimeoutController {
+  /**
+   * Sets a timeout that executes a callback after a specified delay.
+   * Allows setting multiple timeouts and provides a way to cancel them independently.
+   * @param callback - The function to execute after the delay. Receives the current time in milliseconds as an argument.
+   * @param delay (optional) - The time in milliseconds to wait before executing the callback. Defaults to 0.
+   */
+  setTimeout(callback: CallbackType, delay?: number): CancelableTimeout;
+}
+
+export class RequestAnimationFrameTimeoutController implements TimeoutController {
+  setTimeout(callback: CallbackType, delay: number = 0): CancelableTimeout {
+    const startTime = performance.now();
+
+    let requestId: number | null = null;
+
+    const executeCallback = (now: number): void => {
+      if (now - startTime >= delay) {
+        callback(now);
+        // tests fail without the extra if, even when five lines below it's not needed
+        // TODO finish transition to the mocked timeout controller and then remove this condition
+      } else if (typeof requestAnimationFrame === "function") {
+        requestId = requestAnimationFrame(executeCallback);
+      }
+    };
+
+    requestId = requestAnimationFrame(executeCallback);
+
+    return () => {
+      if (requestId != null) {
+        cancelAnimationFrame(requestId);
+      }
+    };
+  }
+}

package/src/animation/useAnimationController.tsx

@@ -0,0 +1,31 @@
+// Ported from recharts 3.9.0 src/animation/useAnimationController.tsx.
+//
+// Solid deviations: React `createContext`/`useContext`/`useMemo` → Solid
+// `createContext`/`useContext`. The context default is a real value
+// (`animationControllerImpl`), so `useContext` returns it without throwing
+// outside a provider, and the hook runs once per component (no `useMemo`).
+import { createContext, useContext } from "solid-js";
+import type { AnimationController } from "./AnimationController";
+import { animationControllerImpl } from "./AnimationControllerImpl";
+
+const AnimationControllerContext = createContext<AnimationController>(animationControllerImpl);
+
+/**
+ * Allows overriding the default AnimationController that Recharts uses internally to drive animations.
+ * The default uses a requestAnimationFrame-based TimeoutController and ticks animations as time moves forward.
+ *
+ * Useful for unit tests, for animating charts back and forth, or for driving animations from something
+ * other than time (manual controls, page scroll, mouse movement, ...).
+ *
+ * @since 3.9
+ */
+// Solid 2.0: the context object itself is the provider component
+// (`<Ctx value={…}>`); there is no `.Provider` as in React / Solid 1.x.
+export const AnimationControllerProvider = AnimationControllerContext;
+
+export function useAnimationController(
+  animationControllerFromProps: AnimationController | undefined,
+): AnimationController {
+  const animationControllerFromContext = useContext(AnimationControllerContext);
+  return animationControllerFromProps ?? animationControllerFromContext;
+}

package/src/animation/useAnimationStartSnapshot.ts

@@ -0,0 +1,73 @@
+// Ported from recharts 3.9.0 src/animation/useAnimationStartSnapshot.ts.
+//
+// Solid 2.0 deviations: React renders many times and mutates refs during render;
+// Solid components run once and re-run reactive computations. So the "capture a
+// frozen snapshot when the animation cycle changes" step becomes a `createMemo`
+// keyed on `animationInput` (it recomputes exactly when the cycle id changes,
+// snapshotting the mutable ref untracked at that instant). `syncStepValue` stays
+// an imperative callback invoked from the animation render-prop; it mutates a
+// plain ref object (not a signal), so it triggers no reactive-graph diagnostics.
+import { createMemo, untrack } from "solid-js";
+import type { Accessor } from "solid-js";
+
+/** A minimal mutable ref, mirroring React's `MutableRefObject`. */
+export type MutableRef<T> = { current: T };
+
+export type AnimationStartSnapshot<T> = {
+  /**
+   * The frozen value captured at the start of the current animation cycle.
+   * It does not drift while the same animation is in progress.
+   */
+  startValue: Accessor<T>;
+  /**
+   * Feed each rendered animation frame back into the snapshot state machine:
+   * 1. "arm" the hook once the new animation renders its `animationElapsedTime=0` frame, and
+   * 2. optionally commit later in-flight frames into the mutable ref so future
+   *    animations resume smoothly from the latest visible geometry.
+   */
+  syncStepValue: (stepValue: T, animationElapsedTime: number, canCommit?: boolean) => void;
+};
+
+export function useAnimationStartSnapshot<T>(
+  animationInput: Accessor<unknown>,
+  previousValueRef: MutableRef<T>,
+): AnimationStartSnapshot<T> {
+  /*
+   * Blocks writes back into the live ref until the new animation has actually
+   * rendered its own `animationElapsedTime=0` frame, so pre-start renders cannot
+   * rebase the next animation onto already-shifted geometry. The INITIAL cycle
+   * starts armed (recharts parity): only a cycle *change* requires the t=0
+   * handshake before commits resume.
+   */
+  let isReadyToCommit = true;
+  let isFirstCycle = true;
+
+  // A new cycle begins whenever `animationInput` changes by reference: capture
+  // exactly one frozen starting snapshot from the live ref and block commits.
+  const startValue = createMemo<T>(() => {
+    animationInput();
+    if (isFirstCycle) {
+      isFirstCycle = false;
+    } else {
+      isReadyToCommit = false;
+    }
+    return untrack(() => previousValueRef.current);
+  });
+
+  const syncStepValue = (stepValue: T, animationElapsedTime: number, canCommit = true): void => {
+    if (animationElapsedTime === 0) {
+      // Handshake: the new animation has rendered its starting frame. We do not
+      // write anything yet; we only allow later in-flight frames to commit.
+      isReadyToCommit = true;
+      return;
+    }
+
+    if (animationElapsedTime > 0 && isReadyToCommit && canCommit) {
+      // Commit the latest visible frame so a future interruption resumes from
+      // exactly what the user saw most recently.
+      previousValueRef.current = stepValue;
+    }
+  };
+
+  return { startValue, syncStepValue };
+}

package/src/animation/util.ts

@@ -0,0 +1,16 @@
+// Ported from recharts 3.8.1 src/animation/util.ts (commit 7a23854).
+// Pure utils — no framework surface — so behavior is byte-identical to recharts.
+// Deviations from the reference are limited to satisfying this repo's type
+// discipline (no `any` / no non-null `!`).
+
+/*
+ * @description: convert camel case to dash case
+ * string => string
+ */
+export const getDashCase = (name: string) => name.replace(/([A-Z])/g, (v) => `-${v.toLowerCase()}`);
+
+export const getTransitionVal = (
+  props: ReadonlyArray<string>,
+  duration: string | number,
+  easing: string,
+): string => props.map((prop) => `${getDashCase(prop)} ${duration}ms ${easing}`).join(",");