@solidports/recharts 0.1.0

package/src/animation/timeoutController.ts

@@ -0,0 +1,70 @@
+/**
+ * Callback type for the timeout function.
+ * Receives current time as an argument.
+ */
+export type CallbackType = (now: number) => void
+
+/**
+ * A function that, when called, cancels the timeout.
+ *
+ * @since 3.9
+ */
+export type CancelableTimeout = () => void
+
+/**
+ * TimeoutController is responsible for controlling the movement of time.
+ * Think of it as a clock.
+ *
+ * Recharts default implementation uses requestAnimationFrame which works great in a browser.
+ * You may choose to override this which is especially useful if you want to control animations.
+ *
+ * Why would you want to do this?
+ * - unit tests
+ * - animations based on something other than time: UI controls, page scroll, mouse movement ...
+ *
+ * @see {@link https://recharts.github.io/en-US/guide/animations/ Animation guide}
+ *
+ * @since 3.9
+ */
+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.
+	 *
+	 * Note that this one function has two different time systems!
+	 * The input (delay - parameter of setTimeout)
+	 * - is relative
+	 * - it means "wait for this long"
+	 * -
+	 *
+	 * The output (now - parameter of the callback) is absolute; it means "this is the time now"
+	 *
+	 * @param callback - The function to execute after the delay. Receives the current absolute time in milliseconds as an argument.
+	 * @param delay (optional) - The duration of 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)
+			} else {
+				requestId = requestAnimationFrame(executeCallback)
+			}
+		}
+
+		requestId = requestAnimationFrame(executeCallback)
+
+		return () => {
+			if (requestId != null) {
+				cancelAnimationFrame(requestId)
+			}
+		}
+	}
+}

package/src/animation/useAnimationController.tsx

@@ -0,0 +1,34 @@
+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 one uses requestAnimationFrame-based TimeoutController, and ticks through the animations
+ * as time moves forward.
+ *
+ * Why would you want to use this? Several reasons:
+ * - Unit tests are an excellent use (Recharts itself has ton of tests with mock TimeoutController)
+ * - If you want to animate charts back and forth (Recharts only animates forward)
+ * - If you want to replace requestAnimationFrame with something else
+ *   - Perhaps a manual animation controls (https://recharts.github.io does this)
+ *   - If you want to maybe animate charts based on mouse movement, or page scroll position, instead of time
+ *
+ * If you don't use this provider then all charts use the default requestAnimationFrame and default animation logic.
+ *
+ * If you use this component then all charts inside use your custom animationController.
+ *
+ * @see {@link https://recharts.github.io/en-US/guide/animations/ Animation guide}
+ *
+ * @since 3.9
+ */
+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,118 @@
+import { createMemo, createSignal, untrack } from "solid-js"
+import type { Accessor } from "solid-js"
+
+export type AnimationStartSnapshot<T> = {
+	/**
+	 * The frozen value captured at the start of the current animation cycle.
+	 *
+	 * Consumers should read from this when computing interpolation pairs.
+	 * It intentionally does not drift while the same animation is in progress,
+	 * even if multiple frames are rendered for the same animation.
+	 */
+	startValue: Accessor<T>
+	/**
+	 * The start value without the `animationElapsedTime=1` refresh. Upstream keeps the
+	 * refresh in a ref, so it never re-runs item matching by itself; matching reads this
+	 * accessor to keep that behavior, while `startValue` lets `isEntrance` observe it.
+	 */
+	frozenStartValue: Accessor<T>
+	/**
+	 * Feed each rendered animation frame back into the snapshot state machine.
+	 *
+	 * This method serves two jobs:
+	 * 1. it "arms" the hook once the new animation has rendered its animationElapsedTime=0 frame, and
+	 * 2. it optionally commits later in-flight frames back into the mutable ref so
+	 *    future animations can continue smoothly from the latest visible geometry.
+	 */
+	syncStepValue: (stepValue: T, animationElapsedTime: number, canCommit?: boolean) => void
+}
+
+/**
+ * Small state machine shared by animated components that need interruption-safe
+ * animations.
+ *
+ * Recharts stores the latest visible animation frame in mutable refs so the next
+ * animation can resume from that exact geometry. When an animation is interrupted,
+ * frames may be computed before the new animation has emitted its own
+ * `animationElapsedTime=0` frame. Reading and writing the same live ref during that
+ * window lets the start value of the new animation drift, which produces visible jumps.
+ *
+ * - `startValue` is a frozen snapshot of the previous animation state, captured
+ *   once per animation cycle and kept stable while that cycle is matched and interpolated.
+ * - `previousValueRef.current` remains the mutable "latest visible frame" store
+ *   that future animations can resume from.
+ *
+ * Lifecycle:
+ * 1. When `animationInput` changes, a new cycle begins. We capture the current ref
+ *    value into `startValue` and temporarily block writes.
+ * 2. When the new animation renders `animationElapsedTime=0`, we unlock writes.
+ * 3. For `animationElapsedTime > 0`, callers may commit the visible frame back into the
+ *    mutable ref. Callers can still veto that with `canCommit=false` (for example when
+ *    a Line needs to wait until SVG path length has been measured).
+ * 4. At `animationElapsedTime=1`, we also refresh the frozen snapshot so later frames in
+ *    the completed state observe the finished geometry.
+ */
+export function useAnimationStartSnapshot<T>(
+	animationInput: Accessor<unknown>,
+	previousValueRef: { current: T },
+): AnimationStartSnapshot<T> {
+	/* Blocks writes into the live ref until the new cycle acknowledges its
+	   animationElapsedTime=0 frame. Plain mutable state, never read reactively. */
+	let isReadyToCommit = true
+	let initialized = false
+	/* Whether the current cycle rendered a frame before t=1. Plain mutable state. */
+	let animatedThisCycle = false
+
+	type Cycle = { value: T }
+	const snapshot = createMemo<Cycle>(() => {
+		animationInput()
+		return untrack(() => {
+			if (initialized) {
+				isReadyToCommit = false
+			}
+			initialized = true
+			animatedThisCycle = false
+			return { value: previousValueRef.current }
+		})
+	})
+	/* The t=1 refresh lives in a plain box like upstream's ref, so later reads see it.
+	   It is also published to a signal, scoped to its cycle and written at most once,
+	   but only when the cycle actually animated: upstream re-renders the item after
+	   onAnimationEnd, while a cycle that jumps straight to t=1 never re-renders. */
+	let refreshed: { cycle: Cycle; value: T } | null = null
+	const [completed, setCompleted] = createSignal<{ cycle: Cycle; value: T } | null>(null)
+
+	const syncStepValue = (stepValue: T, animationElapsedTime: number, canCommit: boolean = true) => {
+		if (animationElapsedTime < 1) {
+			animatedThisCycle = true
+		}
+
+		if (animationElapsedTime === 0) {
+			isReadyToCommit = true
+			return
+		}
+
+		if (animationElapsedTime === 1) {
+			const cycle = untrack(snapshot)
+			refreshed = { cycle, value: stepValue }
+			if (animatedThisCycle && untrack(completed)?.cycle !== cycle) {
+				setCompleted(refreshed)
+			}
+		}
+
+		if (animationElapsedTime > 0 && isReadyToCommit && canCommit) {
+			previousValueRef.current = stepValue
+		}
+	}
+
+	return {
+		frozenStartValue: () => snapshot().value,
+		startValue: () => {
+			const cycle = snapshot()
+			/* tracked so a published refresh re-runs readers */
+			completed()
+			return refreshed != null && refreshed.cycle === cycle ? refreshed.value : cycle.value
+		},
+		syncStepValue,
+	}
+}

package/src/animation/util.ts

@@ -0,0 +1,41 @@
+/*
+ * @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(",")
+
+/**
+ * Finds the intersection of keys between two objects
+ * @param {object} preObj previous object
+ * @param {object} nextObj next object
+ * @returns an array of keys that exist in both objects
+ */
+export const getIntersectionKeys = (
+	preObj: Record<string, unknown>,
+	nextObj: Record<string, unknown>,
+): string[] =>
+	[Object.keys(preObj), Object.keys(nextObj)].reduce((a, b) => a.filter((c) => b.includes(c)))
+
+/**
+ * Maps an object to another object
+ * @param {function} fn function to map
+ * @param {object} obj object to map
+ * @returns mapped object
+ */
+export const mapObject = <T extends Record<string, unknown>, R>(
+	fn: (key: keyof T, value: T[keyof T]) => R,
+	obj: T,
+): { [K in keyof T]: R } =>
+	Object.keys(obj).reduce(
+		(res: { [K in keyof T]: R }, key) => {
+			res[key as keyof T] = fn(key as keyof T, obj[key as keyof T])
+			return res
+		},
+		{} as { [K in keyof T]: R },
+	)