@solidports/recharts 0.1.0

package/src/animation/CSSTransitionAnimate.tsx

@@ -0,0 +1,170 @@
+import { createMemo, createSignal, untrack, createEffect } from "solid-js"
+import type { Accessor } from "solid-js"
+import type { JSX } from "@solidjs/web"
+import { useAnimationController } from "./useAnimationController"
+import { getTransitionVal } from "./util"
+import { resolveIsAnimationActive, usePrefersReducedMotion } from "../util/usePrefersReducedMotion"
+import { CSSTransitionAnimation } from "./AnimationHandle"
+import { RequestAnimationFrameTimeoutController } from "./timeoutController"
+import type { EasingInput, NamedBezier } from "./easing"
+import type { AnimationController } from "./AnimationController"
+
+type CSSTransitionAnimateProps = {
+	animationController?: AnimationController
+	animationId: string
+	attributeName: string
+	begin?: number
+	canBegin?: boolean
+	/* Children receive an accessor and are invoked once, like JavascriptAnimate. A CSS
+	   transition only runs when the SAME element changes its style: re-invoking children
+	   per style change would mount a new element already at `to`, and nothing animates. */
+	children: (style: Accessor<Record<string, string | number>>) => JSX.Element
+	duration?: number
+	easing?: NamedBezier
+	from: string
+	isActive?: boolean | "auto"
+	onAnimationEnd?: () => void
+	onAnimationStart?: () => void
+	to: string
+}
+
+const defaultProps = {
+	begin: 0,
+	canBegin: true,
+	duration: 1000,
+	easing: "ease",
+	isActive: true,
+	onAnimationEnd: () => {},
+	onAnimationStart: () => {},
+} as const satisfies Partial<CSSTransitionAnimateProps>
+
+export function extractCssEasing(easingInput: EasingInput): NamedBezier | undefined {
+	if (easingInput === "spring" || typeof easingInput !== "string") {
+		return undefined
+	}
+	return easingInput
+}
+
+export function CSSTransitionAnimate(outsideProps: CSSTransitionAnimateProps) {
+	/* Live getters with defaults (resolveDefaultProps would freeze them at setup — see
+	 * GOTCHA-005-C). A literal view skips mergeProps' per-key defineProperty and key scan;
+	 * this runs once per animated shape. `??` matches mergeProps: no prop here admits null. */
+	const props = {
+		get animationController() {
+			return outsideProps.animationController
+		},
+		get animationId() {
+			return outsideProps.animationId
+		},
+		get attributeName() {
+			return outsideProps.attributeName
+		},
+		get begin() {
+			return outsideProps.begin ?? defaultProps.begin
+		},
+		get canBegin() {
+			return outsideProps.canBegin ?? defaultProps.canBegin
+		},
+		get children() {
+			return outsideProps.children
+		},
+		get duration() {
+			return outsideProps.duration ?? defaultProps.duration
+		},
+		get easing() {
+			return outsideProps.easing ?? defaultProps.easing
+		},
+		get from() {
+			return outsideProps.from
+		},
+		get isActive() {
+			return outsideProps.isActive ?? defaultProps.isActive
+		},
+		get onAnimationEnd() {
+			return outsideProps.onAnimationEnd ?? defaultProps.onAnimationEnd
+		},
+		get onAnimationStart() {
+			return outsideProps.onAnimationStart ?? defaultProps.onAnimationStart
+		},
+		get to() {
+			return outsideProps.to
+		},
+	}
+
+	const prefersReducedMotion = usePrefersReducedMotion()
+	const isActive = createMemo(() => resolveIsAnimationActive(props.isActive, prefersReducedMotion))
+
+	const animationController = useAnimationController(() => props.animationController)
+	const [style, setStyle] = createSignal<string | number>(
+		untrack(() => (isActive() === false ? props.to : props.from)),
+	)
+	/* Plain mutable mirrors React's useRef — flipping it must NOT trigger a
+	 * re-render. Re-renders happen only when `style` changes (signal) or
+	 * canBegin/isActive flip. The post-start render then reads the flag and
+	 * adds `transition`. */
+	let initialized = false
+
+	createEffect(
+		() =>
+			isActive() === false || !props.canBegin
+				? null
+				: {
+						animationId: props.animationId + props.attributeName,
+						begin: props.begin,
+						controller: animationController(),
+						duration: props.duration,
+						easing: props.easing,
+						from: props.from,
+						onAnimationEnd: props.onAnimationEnd,
+						onAnimationStart: props.onAnimationStart,
+						to: props.to,
+					},
+		(run) => {
+			if (run == null) {
+				return undefined
+			}
+			initialized = true
+
+			const animation = new CSSTransitionAnimation({
+				animationBegin: run.begin,
+				animationDuration: run.duration,
+				animationId: run.animationId,
+				easing: run.easing,
+				from: run.from,
+				onAnimationEnd: run.onAnimationEnd,
+				onAnimationStart: () => {
+					setStyle(run.from)
+					run.onAnimationStart()
+				},
+				to: run.to,
+			})
+
+			return run.controller(new RequestAnimationFrameTimeoutController(), animation, setStyle)
+		},
+	)
+
+	const childStyle = createMemo<Record<string, string | number>>(() => {
+		/* Always read `style()` so the memo tracks it regardless of which
+		 * branch we currently take. Otherwise: memo first evaluates with
+		 * initialized=false, never reads style, never subscribes — when the
+		 * start-effect later flips initialized and setStyle fires, the memo
+		 * has no dependency on style and doesn't re-evaluate. */
+		const styleNow = style()
+		if (isActive() === false) {
+			return { [props.attributeName]: props.to }
+		}
+		if (!props.canBegin) {
+			return { [props.attributeName]: props.from }
+		}
+		if (initialized) {
+			return {
+				transition: getTransitionVal([props.attributeName], props.duration, props.easing),
+				[props.attributeName]: styleNow,
+			}
+		}
+		return { [props.attributeName]: props.from }
+	})
+
+	/* eslint-disable-next-line solid/reactivity -- one-time children() call keeps element identity; childStyle is reactive */
+	return untrack(() => props.children(childStyle))
+}

package/src/animation/JavascriptAnimate.tsx

@@ -0,0 +1,119 @@
+import { createMemo, createSignal, untrack, createEffect } from "solid-js"
+import type { JSX } from "@solidjs/web"
+import { createEasingFunction } from "./easing"
+import type { EasingInput } from "./easing"
+import { useAnimationController } from "./useAnimationController"
+import { resolveIsAnimationActive, usePrefersReducedMotion } from "../util/usePrefersReducedMotion"
+import { JavascriptAnimation } from "./AnimationHandle"
+import { RequestAnimationFrameTimeoutController } from "./timeoutController"
+import type { AnimationController } from "./AnimationController"
+
+import { mergeProps } from "../util/solid-1-compat"
+type JavascriptAnimateProps = {
+	animationController?: AnimationController
+	animationId: string
+	begin?: number
+	canBegin?: boolean
+	/* Children receives an Accessor<number> instead of a plain number. Solid
+	   evaluates the children fn ONCE at setup and the returned JSX is mounted
+	   stable across animation ticks; reading `t()` inside reactive attribute
+	   slots (e.g. `<path d={getD(t())}/>`) updates only the attribute, not the
+	   element identity. Plain-value children gets re-instantiated every tick,
+	   replacing the DOM node on each render — tests holding a captured DOM ref
+	   see stale attributes. */
+	children: (time: () => number) => JSX.Element
+	duration?: number
+	easing?: EasingInput
+	isActive?: boolean | "auto"
+	onAnimationEnd?: () => void
+	onAnimationStart?: () => void
+}
+
+const defaultJavascriptAnimateProps = {
+	begin: 0,
+	canBegin: true,
+	duration: 1000,
+	easing: "ease",
+	isActive: true,
+	onAnimationEnd: () => {},
+	onAnimationStart: () => {},
+} as const satisfies Partial<JavascriptAnimateProps>
+
+const from = 0
+const to = 1
+
+export function JavascriptAnimate(outsideProps: JavascriptAnimateProps) {
+	/* mergeProps preserves the props proxy lazily so child callbacks and
+	 * downstream toggles (isActive, canBegin) stay reactive. resolveDefaultProps
+	 * would freeze them at setup — see GOTCHA-005-C. */
+	const props = mergeProps(defaultJavascriptAnimateProps, outsideProps)
+
+	const prefersReducedMotion = usePrefersReducedMotion()
+	const isActive = createMemo(() => resolveIsAnimationActive(props.isActive, prefersReducedMotion))
+
+	const animationController = useAnimationController(() => props.animationController)
+
+	/* Each committed frame is tagged with the animation that produced it. When
+	   animationId flips, the previous animation's frame no longer applies and
+	   time reads `from` immediately, the same as upstream remounting
+	   JavascriptAnimate via `key={animationId}`; no stale `t=1` frame leaks into
+	   the new animation's first render (GOTCHA-014-G). */
+	const [frame, setFrame] = createSignal<{ animationId: string; t: number }>(
+		untrack(() => ({ animationId: props.animationId, t: isActive() ? from : to })),
+	)
+	const time = createMemo(() => {
+		if (!isActive()) {
+			return to
+		}
+		const current = frame()
+		return current.animationId === props.animationId ? current.t : from
+	})
+
+	createEffect(
+		() =>
+			isActive() === false || !props.canBegin
+				? null
+				: {
+						animationId: props.animationId,
+						begin: props.begin,
+						controller: animationController(),
+						duration: props.duration,
+						easing: props.easing,
+						onAnimationEnd: props.onAnimationEnd,
+						onAnimationStart: props.onAnimationStart,
+					},
+		(run) => {
+			if (run == null) {
+				return undefined
+			}
+			const easingFunction = createEasingFunction(run.easing)
+			if (easingFunction == null) {
+				return undefined
+			}
+
+			const animation = new JavascriptAnimation({
+				animationBegin: run.begin,
+				animationDuration: run.duration,
+				animationId: run.animationId,
+				easing: easingFunction,
+				from,
+				onAnimationEnd: run.onAnimationEnd,
+				onAnimationStart: run.onAnimationStart,
+				to,
+			})
+
+			return run.controller(new RequestAnimationFrameTimeoutController(), animation, (value) =>
+				setFrame({ animationId: run.animationId, t: Number(value) }),
+			)
+		},
+	)
+
+	/* perf: invoke children ONCE at setup. The `time` accessor is
+	   reactive on its own, so consumers reading `t()` inside their createMemo
+	   subscribe to the frame signal directly. Building the subtree at setup and
+	   returning it directly lets attribute bindings update in place instead of
+	   re-creating every computation inside the children thunk per tick. */
+	/* eslint-disable-next-line solid/reactivity -- intentional one-time children() call at setup for perf (see comment above); time is a reactive accessor */
+	const subtree = props.children(time)
+	return subtree
+}

package/src/animation/easing.ts

@@ -0,0 +1,221 @@
+export const ACCURACY = 1e-4
+
+const cubicBezierFactor = (c1: number, c2: number) => [0, 3 * c1, 3 * c2 - 6 * c1, 3 * c1 - 3 * c2 + 1]
+
+const evaluatePolynomial = (params: ReadonlyArray<number>, animationElapsedTime: number) =>
+	params.map((param, i) => param * animationElapsedTime ** i).reduce((pre, curr) => pre + curr)
+
+const cubicBezier = (c1: number, c2: number) => (animationElapsedTime: number) => {
+	const params = cubicBezierFactor(c1, c2)
+
+	return evaluatePolynomial(params, animationElapsedTime)
+}
+
+const derivativeCubicBezier = (c1: number, c2: number) => (animationElapsedTime: number) => {
+	const params = cubicBezierFactor(c1, c2)
+	const newParams = [...params.map((param, i) => param * i).slice(1), 0]
+
+	return evaluatePolynomial(newParams, animationElapsedTime)
+}
+
+type CubicBezierTemplate = `cubic-bezier(${number},${number},${number},${number})`
+
+export type NamedBezier = "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | CubicBezierTemplate
+
+type BezierInput = [NamedBezier] | [number, number, number, number]
+
+export type BezierEasingFunction = {
+	isStepper: false
+	(animationElapsedTime: number): number
+}
+
+const parseCubicBezier = (easing: string): [number, number, number, number] | null => {
+	const easingParts = easing.split("(")
+	if (easingParts.length !== 2 || easingParts[0] !== "cubic-bezier") {
+		return null
+	}
+	const numbers = easingParts[1]?.split(")")[0]?.split(",")
+	if (numbers == null || numbers.length !== 4) {
+		return null
+	}
+	const coords = numbers.map((x: string) => parseFloat(x))
+	return [coords[0] as number, coords[1] as number, coords[2] as number, coords[3] as number]
+}
+
+const getBezierCoordinates = (...args: BezierInput): [number, number, number, number] => {
+	if (args.length === 1) {
+		switch (args[0]) {
+			case "linear":
+				return [0.0, 0.0, 1.0, 1.0]
+			case "ease":
+				return [0.25, 0.1, 0.25, 1.0]
+			case "ease-in":
+				return [0.42, 0.0, 1.0, 1.0]
+			case "ease-out":
+				return [0.42, 0.0, 0.58, 1.0]
+			case "ease-in-out":
+				return [0.0, 0.0, 0.58, 1.0]
+			default: {
+				const easing = parseCubicBezier(args[0])
+				if (easing) {
+					return easing
+				}
+			}
+		}
+	}
+
+	if (args.length === 4) {
+		return args
+	}
+
+	// Fallback for invalid inputs. The previous implementation was buggy and would lead to NaN.
+	// Returning linear easing is a safe default.
+	return [0.0, 0.0, 1.0, 1.0]
+}
+
+const createBezierEasing = (x1: number, y1: number, x2: number, y2: number): BezierEasingFunction => {
+	const curveX = cubicBezier(x1, x2)
+	const curveY = cubicBezier(y1, y2)
+	const derCurveX = derivativeCubicBezier(x1, x2)
+	const rangeValue = (value: number): number => {
+		if (value > 1) {
+			return 1
+		}
+		if (value < 0) {
+			return 0
+		}
+
+		return value
+	}
+
+	const bezier = (_animationElapsedTime: number) => {
+		const animationElapsedTime = _animationElapsedTime > 1 ? 1 : _animationElapsedTime
+		let x = animationElapsedTime
+
+		for (let i = 0; i < 8; ++i) {
+			const evalT = curveX(x) - animationElapsedTime
+			const derVal = derCurveX(x)
+
+			if (Math.abs(evalT - animationElapsedTime) < ACCURACY || derVal < ACCURACY) {
+				return curveY(x)
+			}
+
+			x = rangeValue(x - evalT / derVal)
+		}
+
+		return curveY(x)
+	}
+
+	bezier.isStepper = false as const
+
+	return bezier
+}
+
+// calculate cubic-bezier using Newton's method
+export const configBezier = (...args: BezierInput): BezierEasingFunction => {
+	return createBezierEasing(...getBezierCoordinates(...args))
+}
+
+type SpringInput = {
+	/**
+	 * The stiffness coefficient of the spring.
+	 * Higher values create a more forceful, faster pull towards the target.
+	 */
+	stiff?: number
+	/**
+	 * The damping coefficient (friction/resistance).
+	 * Higher values reduce bounciness and stop oscillation sooner. Lower values create more bounce.
+	 */
+	damping?: number
+	/**
+	 * The physics simulation time step in milliseconds.
+	 * Determines the granularity of the baked frames. 16.67ms roughly equals a 60fps frame delta.
+	 */
+	dt?: number
+}
+
+/**
+ * Creates a performance-optimized, progress-based spring easing function.
+ * It pre-calculates ("bakes") spring physics frames upfront based on a fixed duration,
+ * then returns a pure, lightweight function mapping progress (0 to 1) to the animated position.
+ * This approach is ideal for low-power devices because it removes heavy physics math from the frame loop.
+ */
+export const createSpringEasing = (config: SpringInput = {}): EasingFunction => {
+	const { stiff = 100, damping = 8, dt = 16.67 } = config
+	const destX = 1
+
+	const positions: number[] = [0]
+	let currX = 0
+	let currV = 0
+
+	// Safety valve to prevent accidental infinite loops if physics config is extreme
+	const maxIterations = 10000
+	let iterations = 0
+
+	// 1. Run the simulation until the spring completely stops moving
+	while (iterations < maxIterations) {
+		const FSpring = -(currX - destX) * stiff
+		const FDamping = currV * damping
+
+		currV += ((FSpring - FDamping) * dt) / 1000
+		currX += (currV * dt) / 1000
+
+		positions.push(currX)
+
+		// Stop only when position is essentially at 1.0 AND bounce velocity has died down
+		if (Math.abs(currX - destX) < ACCURACY && Math.abs(currV) < ACCURACY) {
+			break
+		}
+		iterations++
+	}
+
+	// Force the absolute final element to be exactly 1.0 for a perfect finish
+	positions[positions.length - 1] = destX
+	const maxIndex = positions.length - 1
+
+	// 2. The ultra-smooth runtime function mapping your 0..1 progress
+	return (t: number): number => {
+		if (t <= 0) return 0
+		if (t >= 1) return destX
+
+		// Scale t (0..1) proportionally across our entire pre-calculated array
+		const exactFrame = t * maxIndex
+		const index = Math.floor(exactFrame)
+		const fraction = exactFrame - index
+
+		// Blend between the two closest frames
+		return (positions[index] ?? 0) + ((positions[index + 1] ?? 0) - (positions[index] ?? 0)) * fraction
+	}
+}
+
+export type EasingFunction = (t: number) => number
+
+/**
+ * @inline
+ */
+export type EasingInput = NamedBezier | "spring" | EasingFunction
+
+export const createEasingFunction = (easing: EasingInput): EasingFunction | null => {
+	if (typeof easing === "string") {
+		switch (easing) {
+			case "ease":
+			case "ease-in-out":
+			case "ease-out":
+			case "ease-in":
+			case "linear":
+				return configBezier(easing)
+			case "spring":
+				return createSpringEasing()
+			default:
+				if (easing.split("(")[0] === "cubic-bezier") {
+					return configBezier(easing)
+				}
+		}
+	}
+
+	if (typeof easing === "function") {
+		return easing
+	}
+
+	return null
+}

package/src/animation/matchBy.ts

@@ -0,0 +1,164 @@
+import { getValueByDataKey } from "../util/ChartUtils"
+import type { DataKey } from "../util/types"
+import type {
+	AnimationItem,
+	AnimationMatchBy,
+	AnimationMatchByProp,
+} from "../state/types/AnimationSettings"
+
+export type { AnimationItem, AnimationMatchBy, AnimationMatchByProp }
+
+/**
+ * Match animation items by their array index (the default behavior).
+ *
+ * Previous items are paired with next items based on their position
+ * in the array, with proportional stretching when array lengths differ.
+ *
+ * @since 3.9
+ */
+export const matchByIndex = "index" as const
+
+/**
+ * Match animation items sequentially: previous item 0 pairs with next item 0,
+ * previous item 1 pairs with next item 1, and so on. Extra next items animate in;
+ * extra 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.
+ *
+ * @since 3.9
+ */
+export function matchByDataKey(
+	dataKey: DataKey<Record<string, unknown>>,
+): AnimationMatchBy<{ payload?: unknown }> {
+	return (item: { payload?: unknown }): string | number | null => {
+		if (item.payload == null || typeof item.payload !== "object") {
+			return null
+		}
+		const value = getValueByDataKey(item.payload as Record<string, unknown>, 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: Array<AnimationItem<T>> = []
+	for (const prev of removedPrevItems) {
+		tagged.push({ status: "removed", prev })
+	}
+	for (let i = 0; i < nextItems.length; i++) {
+		const prev = alignedPrevItems[i]
+		/* i is within bounds; noUncheckedIndexedAccess cannot see that */
+		const next = nextItems[i] as T
+		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
+}
+
+function matchByKey<T>(
+	prevItems: ReadonlyArray<T>,
+	nextItems: ReadonlyArray<T>,
+	matchBy: AnimationMatchBy<T>,
+): ReadonlyArray<AnimationItem<T>> {
+	const prevMap = buildPrevKeyMap(prevItems, matchBy)
+	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
+	})
+
+	const removedPrevItems: Array<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.
+ *
+ * On first render, all next items are returned as `{ status: 'added' }`.
+ * For key-based matching, unmatched previous items are `{ status: 'removed' }`.
+ */
+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" as const, next }))
+	}
+	if (matchBy === matchByIndex) {
+		return matchByIndexImpl(prevItems, nextItems)
+	}
+	if (matchBy === matchAppend) {
+		return matchAppendImpl(prevItems, nextItems)
+	}
+	return matchByKey(prevItems, nextItems, matchBy)
+}