@solidports/recharts 0.1.0

package/package.json

@@ -0,0 +1,98 @@
+{
+	"author": "Lovro Žagar",
+	"bugs": "https://github.com/lovrozagar/solidports/issues",
+	"dependencies": {
+		"clsx": "2.1.1",
+		"decimal.js-light": "2.5.1",
+		"es-toolkit": "1.49.0",
+		"eventemitter3": "5.0.4",
+		"tiny-invariant": "1.3.3",
+		"victory-vendor": "37.3.6"
+	},
+	"description": "SolidJS 1:1 port of Recharts charting library",
+	"devDependencies": {
+		"@solidjs/signals": "2.0.0-rc.13",
+		"@solidjs/testing-library": "1.0.0-beta.3",
+		"@solidjs/vite-plugin": "3.0.0-next.47",
+		"@solidjs/web": "2.0.0-rc.13",
+		"@testing-library/dom": "10.4.1",
+		"@testing-library/jest-dom": "6.9.1",
+		"@types/bun": "latest",
+		"@types/node": "26.1.1",
+		"jsdom": "29.1.1",
+		"solid-js": "2.0.0-rc.13",
+		"ts-morph": "28.0.0",
+		"tsup": "8.5.1",
+		"tsup-preset-solid": "2.2.0",
+		"typescript": "7.0.2",
+		"vitest": "4.1.10",
+		"vitest-axe": "0.1.0"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"solid": "./src/index.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"src",
+		"README.md",
+		"LICENSE",
+		"NOTICE"
+	],
+	"homepage": "https://github.com/lovrozagar/solidports/tree/main/packages/recharts#readme",
+	"keywords": [
+		"solid",
+		"solidjs",
+		"chart",
+		"charts",
+		"charting",
+		"recharts",
+		"data-visualization"
+	],
+	"license": "MIT",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"name": "@solidports/recharts",
+	"peerDependencies": {
+		"@solidjs/web": ">=2.0.0-rc.13",
+		"solid-js": ">=2.0.0-rc.13"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/lovrozagar/solidports.git",
+		"directory": "packages/recharts"
+	},
+	"scripts": {
+		"build": "tsup",
+		"check": "bun run typecheck && bun run lint && bun run test",
+		"dev": "tsup --watch",
+		"lint": "oxlint src test",
+		"lint:fix": "oxlint --fix src test",
+		"parity": "bun scripts/parity-audit.ts",
+		"release": "bun run build && changeset publish",
+		"test": "vitest run",
+		"test:perf": "RECHARTS_PERF=1 vitest run test/perf",
+		"test:watch": "vitest",
+		"triage": "bun scripts/triage-tests.ts",
+		"type:check": "tsc --noEmit",
+		"typecheck": "tsc --noEmit",
+		"upstream:apply": "bun scripts/sync-upstream.ts apply",
+		"upstream:diff": "bun scripts/sync-upstream.ts diff",
+		"upstream:fetch": "bun scripts/sync-upstream.ts fetch",
+		"upstream:pin": "bun scripts/sync-upstream.ts pin",
+		"upstream:status": "bun scripts/sync-upstream.ts status"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"types": "./dist/index.d.ts",
+	"version": "0.1.0"
+}

package/src/animation/AnimatedItems.tsx

@@ -0,0 +1,183 @@
+import { createEffect, createMemo, createSignal, Show, untrack } from "solid-js"
+import type { Accessor } from "solid-js"
+import type { JSX } from "@solidjs/web"
+import { JavascriptAnimate } from "./JavascriptAnimate"
+import type { EasingInput } from "./easing"
+import { useAnimationId } from "../util/useAnimationId"
+import { matchAnimationItems, matchByIndex } from "./matchBy"
+import type { AnimationItem, AnimationMatchByProp } from "./matchBy"
+import { useAnimationStartSnapshot } from "./useAnimationStartSnapshot"
+import type { CartesianLayout, PolarLayout } from "../util/types"
+import type { AnimationInterpolateFn } from "../state/types/AnimationSettings"
+
+export type { AnimationInterpolateFn }
+
+/**
+ * Tracks animation state and provides callbacks for animation start/end.
+ *
+ * @param onAnimationStart optional callback to call when animation starts
+ * @param onAnimationEnd optional callback to call when animation ends
+ */
+export function useAnimationCallbacks(
+	onAnimationStart: Accessor<(() => void) | undefined> = () => undefined,
+	onAnimationEnd: Accessor<(() => void) | undefined> = () => undefined,
+): {
+	isAnimating: Accessor<boolean>
+	handleAnimationStart: () => void
+	handleAnimationEnd: () => void
+} {
+	const [isAnimating, setIsAnimating] = createSignal(false)
+
+	const handleAnimationStart = () => {
+		const callback = untrack(onAnimationStart)
+		if (typeof callback === "function") {
+			callback()
+		}
+		setIsAnimating(true)
+	}
+
+	const handleAnimationEnd = () => {
+		const callback = untrack(onAnimationEnd)
+		if (typeof callback === "function") {
+			callback()
+		}
+		setIsAnimating(false)
+	}
+
+	return { handleAnimationEnd, handleAnimationStart, isAnimating }
+}
+
+export type AnimatedItemsProps<ItemType, LayoutType extends CartesianLayout | PolarLayout> = {
+	/**
+	 * Opaque input to detect when a new animation should start.
+	 * When this value changes, a new animation begins.
+	 */
+	animationInput: unknown
+	/** Prefix for the generated animation ID */
+	animationIdPrefix: string
+	/** The target items to animate towards */
+	items: ReadonlyArray<ItemType> | undefined
+	/** Ref holding previous items — used to detect first render vs data update */
+	previousItemsRef: { current: ReadonlyArray<ItemType> | null | undefined }
+	/** Whether animation is active */
+	isAnimationActive: boolean | "auto"
+	/** Delay in ms before animation begins */
+	animationBegin: number
+	/** Duration of animation in ms */
+	animationDuration: number
+	/** Easing function or named easing */
+	animationEasing: EasingInput
+	/** Called when the animation begins */
+	onAnimationStart?: () => void
+	/** Called when the animation completes */
+	onAnimationEnd?: () => void
+	/** The interpolation function — either the default or user-provided */
+	animationInterpolateFn: AnimationInterpolateFn<ItemType, LayoutType>
+	/**
+	 * Strategy for matching previous items to next items during animation.
+	 *
+	 * - `matchByIndex` (default): match by array index with proportional stretching
+	 * - `matchAppend`: match 1:1 by index, extras animate in as new
+	 * - A function `(item, index) => key`: match by the returned key value
+	 */
+	animationMatchBy?: AnimationMatchByProp<ItemType>
+	/**
+	 * Optional guard for updating previousItemsRef. Default: `(animationElapsedTime) => animationElapsedTime > 0`.
+	 * Line uses `(animationElapsedTime) => animationElapsedTime > 0 && totalLength > 0` to avoid updating before SVG path is measured.
+	 */
+	shouldUpdatePreviousRef?: (animationElapsedTime: number) => boolean
+	/**
+	 * Render with interpolated items and animation state. Invoked once; the
+	 * accessors update in place on every animation frame.
+	 *
+	 * @param items The interpolated items at the current animation frame
+	 * @param animationElapsedTime The normalized time (0-1), useful for additional animation effects
+	 * @param isEntrance Whether this is the first render (entrance animation) or a data update animation.
+	 */
+	children: (
+		items: Accessor<ReadonlyArray<ItemType>>,
+		animationElapsedTime: Accessor<number>,
+		isEntrance: Accessor<boolean>,
+	) => JSX.Element
+	layout: LayoutType
+}
+
+/**
+ * A reusable animation wrapper for array-based chart data.
+ *
+ * Encapsulates the common animation pattern shared by Bar, Scatter, Funnel, Pie,
+ * Radar, RadialBar, Area, and Line:
+ * 1. Track previous items in a ref
+ * 2. Wrap in JavascriptAnimate
+ * 3. Update ref when animationElapsedTime > 0
+ *
+ * @since 3.9
+ */
+export function AnimatedItems<ItemType, LayoutType extends CartesianLayout | PolarLayout>(
+	props: AnimatedItemsProps<ItemType, LayoutType>,
+) {
+	const animationId = useAnimationId(
+		() => props.animationInput,
+		untrack(() => props.animationIdPrefix),
+	)
+	const animationStartItems = useAnimationStartSnapshot(
+		animationId,
+		/* eslint-disable-next-line solid/reactivity -- the ref box is a stable mutable container owned by the caller */
+		props.previousItemsRef,
+	)
+	/* Memoized so per-frame reads do not re-run the caller's selector chain. */
+	const items = createMemo(() => props.items)
+	const animationItems = createMemo<ReadonlyArray<AnimationItem<ItemType>> | null>(() =>
+		matchAnimationItems(
+			animationStartItems.frozenStartValue() ?? null,
+			items(),
+			props.animationMatchBy ?? matchByIndex,
+		),
+	)
+
+	return (
+		<JavascriptAnimate
+			animationId={animationId()}
+			begin={props.animationBegin}
+			duration={props.animationDuration}
+			isActive={props.isAnimationActive}
+			easing={props.animationEasing}
+			onAnimationEnd={props.onAnimationEnd}
+			onAnimationStart={props.onAnimationStart}
+		>
+			{(animationElapsedTime: Accessor<number>) => {
+				/* Fixed per render like upstream: a lazy read (e.g. on hover) would see the
+				   unpublished t=1 refresh. */
+				const isEntrance = createMemo(() => animationStartItems.startValue() == null)
+				const stepData = createMemo(() => {
+					const current = items()
+					if (current == null) {
+						return current
+					}
+					return props.animationInterpolateFn(animationItems(), animationElapsedTime(), props.layout)
+				})
+				createEffect(
+					() => {
+						const t = animationElapsedTime()
+						const step = stepData()
+						const canUpdate =
+							props.shouldUpdatePreviousRef != null ? props.shouldUpdatePreviousRef(t) : t > 0
+						return { canUpdate, step, t }
+					},
+					({ canUpdate, step, t }) => {
+						animationStartItems.syncStepValue(step ?? null, t, canUpdate)
+					},
+				)
+				return (
+					<Show when={stepData() != null}>
+						{props.children(
+							() => stepData() as ReadonlyArray<ItemType>,
+							animationElapsedTime,
+							isEntrance,
+						)}
+					</Show>
+				)
+			}}
+		</JavascriptAnimate>
+	)
+}

package/src/animation/AnimationController.ts

@@ -0,0 +1,33 @@
+import type { CancelableTimeout, TimeoutController } from "./timeoutController"
+import type { AnimationHandle } from "./AnimationHandle"
+
+/**
+ * It's actually always the case that JavaScript-based animations produce numbers,
+ * and CSS transition-based animations always produce strings,
+ * but it's so much easier to just have them together than to deal with all the generics.
+ *
+ * @see {@link https://recharts.github.io/en-US/guide/animations/ Animation guide}
+ *
+ * @since 3.9
+ */
+export type OnAnimationStateUpdate = (newState: number | string) => void
+
+/**
+ * AnimationController accepts the animation state machine (= RechartsAnimation) plus a timeout controller,
+ * and manages the animation by calling the tick method of the animation state machine at the right time.
+ *
+ * One controller is only responsible for one animation. Every new animation will create a new controller.
+ *
+ * The animation state machine is responsible for calculating the animation progress
+ * and calling the onAnimationStart and onAnimationEnd callbacks at the right time,
+ * while the AnimationController is responsible for calling the tick method of the animation state machine.
+ *
+ * @see {@link https://recharts.github.io/en-US/guide/animations/ Animation guide}
+ *
+ * @since 3.9
+ */
+export type AnimationController = (
+	timeoutController: TimeoutController,
+	animationHandle: AnimationHandle,
+	listener: OnAnimationStateUpdate,
+) => CancelableTimeout

package/src/animation/AnimationControllerImpl.ts

@@ -0,0 +1,36 @@
+import type { AnimationController, OnAnimationStateUpdate } from "./AnimationController"
+import type { AnimationHandle } from "./AnimationHandle"
+import type { CancelableTimeout, TimeoutController } from "./timeoutController"
+
+/**
+ * JavaScript animations require trigger and repaint as soon as possible,
+ * so this class uses the timeoutController to trigger updates as quickly as the controller allows.
+ *
+ * JavaScript animation progress is represented as a stream of values. The exact type depends on the animationHandle type.
+ * Each individual consumer is then responsible for mapping those values onto a React component.
+ */
+export const animationControllerImpl: AnimationController = (
+	timeoutController: TimeoutController,
+	animationHandle: AnimationHandle,
+	listener: OnAnimationStateUpdate,
+): CancelableTimeout => {
+	let cancellable: CancelableTimeout | undefined
+	const nextUpdate = (now: number) => {
+		const timeRemaining = animationHandle.tick(now)
+		if (animationHandle.getState() === "active") {
+			listener(animationHandle.getInterpolated())
+			if (animationHandle.getProgress() === 1) {
+				animationHandle.complete()
+				cancellable = undefined
+				return
+			}
+			cancellable = timeoutController.setTimeout(nextUpdate, timeRemaining)
+			return
+		}
+		cancellable = timeoutController.setTimeout(nextUpdate, timeRemaining)
+	}
+
+	cancellable = timeoutController.setTimeout(nextUpdate, 0)
+
+	return () => cancellable?.()
+}

package/src/animation/AnimationHandle.ts

@@ -0,0 +1,307 @@
+// eslint-disable-next-line max-classes-per-file
+import { interpolate } from "../util/DataUtils"
+import type { EasingFunction, NamedBezier } from "./easing"
+
+const INIT = "init" as const
+const PENDING = "pending" as const
+const ACTIVE = "active" as const
+const COMPLETED = "completed" as const
+
+export type AnimationState = typeof INIT | typeof PENDING | typeof ACTIVE | typeof COMPLETED
+
+type AnimationStateCallback = () => void
+
+function duration(time: number): number {
+	return Math.max(0, time)
+}
+
+abstract class RechartsAnimation<T, E> {
+	/**
+	 * Returns the absolute time after the animationBegin delay has been completed,
+	 * and when the animationDuration started ticking.
+	 */
+	public getAnimationStartedTime(): number | undefined {
+		return this.animationStartedTime
+	}
+
+	/**
+	 * Returns the absolute time of when the animation began - now it will wait for {animationBegin} ms before the transition starts
+	 */
+	public getBeginStartedTime(): number | undefined {
+		return this.beginStartedTime
+	}
+
+	private readonly onAnimationEnd: undefined | AnimationStateCallback
+
+	private progress: number
+
+	private animationStartedTime: number | undefined
+
+	private beginStartedTime: number | undefined
+
+	protected readonly animationDuration: number
+
+	private readonly animationBegin: number
+
+	private readonly from: T
+
+	private readonly to: T
+
+	protected readonly easing: E
+
+	private readonly animationId: string
+
+	constructor(param: {
+		animationId: string
+		onAnimationStart: undefined | AnimationStateCallback
+		onAnimationEnd: undefined | AnimationStateCallback
+		animationDuration: number
+		animationBegin: number
+		from: T
+		to: T
+		easing: E
+	}) {
+		this.animationId = param.animationId
+		this.onAnimationEnd = param.onAnimationEnd
+		this.animationDuration = duration(param.animationDuration)
+		this.animationBegin = duration(param.animationBegin)
+		this.progress = 0
+		this.from = param.from
+		this.to = param.to
+		this.easing = param.easing
+		// Mimic what the previous animationManager was doing - call onAnimationStart immediately and synchronously
+		param.onAnimationStart?.()
+	}
+
+	private state: AnimationState = INIT
+
+	/**
+	 * Returns the state machine current state
+	 * - `init`:       animation had just been created. It immediately calls `onAnimationStart`
+	 * - `pending`:    animation is now paused for `animationBegin` milliseconds until the transition begins
+	 * - `active`:     animation is transitioning items on screen
+	 * - `completed`:  animation has completed its transition and executed `onAnimationEnd`.
+	 *                 This state is final and the animation is no longer allowed to transition to other states.
+	 */
+	public getState() {
+		return this.state
+	}
+
+	/**
+	 * Returns the easing input or function
+	 */
+	public getEasing(): E {
+		return this.easing
+	}
+
+	/**
+	 * Returns the configuration - the duration of the transition.
+	 * Does not change in time, does not change when state changes, this is a static value.
+	 */
+	public getAnimationDuration(): number {
+		return this.animationDuration
+	}
+
+	/**
+	 * Sets the current time of the animation. The animation sets its internal state and progress accordingly.
+	 * This is current, absolute time; not additive!
+	 * This allows you to essentially "travel back in time" based on the value you pass in here.
+	 *
+	 * Returns the (relative) time remaining until the current activity is over.
+	 * Meaning: if the state is in a middle of a delay, returns the time left until the delay is finished.
+	 * If the state is in the middle of a transition, returns time left until that transition is complete.
+	 * This is useful because it's the same number you can take and put into setTimeout(fn, X)
+	 * as that's how much time we need to wait until the next state transition happens.
+	 */
+	public tick(now: number): number {
+		if (this.getState() === INIT) {
+			this.state = PENDING
+			this.beginStartedTime = now
+			return this.animationBegin
+		}
+
+		if (this.getState() === PENDING) {
+			if (this.beginStartedTime == null) {
+				throw new Error("@solidports/recharts: pending animation has no begin time")
+			}
+			const timeElapsed = now - this.beginStartedTime
+			if (timeElapsed >= this.animationBegin) {
+				this.state = ACTIVE
+				this.animationStartedTime = now
+				// The state flipped just now so the elapsed time is zero
+				return this.nextAnimationUpdate(0)
+			}
+			return duration(this.animationBegin - timeElapsed)
+		}
+
+		if (this.getState() === ACTIVE) {
+			if (this.animationStartedTime == null) {
+				throw new Error("@solidports/recharts: active animation has no start time")
+			}
+			const timeElapsed = now - this.animationStartedTime
+			this.setProgress(timeElapsed / this.animationDuration)
+			return this.nextAnimationUpdate(timeElapsed)
+		}
+
+		// state === COMPLETED, nothing interesting is going to happen
+		return 0
+	}
+
+	private setProgress(newProgress: number) {
+		this.progress = Math.min(1, Math.max(0, newProgress))
+	}
+
+	/**
+	 * Returns an abstract "progress" which is number between 0 and 1 which shows the distance of transition.
+	 * This progress depends on the animation state:
+	 * - `init`: 0
+	 * - `pending`: 0
+	 * - `active`: transitioning between [0, 1] based on the time elapsed
+	 * - `completed`: 1
+	 *
+	 * The progress is hard-capped to be between 0 and 1 (inclusive) to avoid overshooting caused by coarse timers.
+	 * For this reason, the easing function must be applied _after_ this animation state,
+	 * so that one has a chance to construct dynamic "overshoot" animations.
+	 *
+	 * The progress is linear with time.
+	 * If you wish for easing, use `getInterpolated()` instead.
+	 */
+	public getProgress(): number {
+		return this.progress
+	}
+
+	/**
+	 * Completes the animation. Completed animation:
+	 * - cannot be manipulated anymore
+	 * - its progress is set to 1
+	 * - tick function doesn't do anything
+	 * - getState() always returns 'completed'
+	 */
+	public complete() {
+		this.progress = 1
+		if (this.state === "active") {
+			// Do not call callbacks if the animation was interrupted before it even started!
+			this.onAnimationEnd?.()
+		}
+		this.state = COMPLETED
+	}
+
+	/**
+	 * Returns the starting value of the animation.
+	 * Does not include progress, easing, interpolation, none of that - just the static starting value
+	 */
+	public getFrom() {
+		return this.from
+	}
+
+	/**
+	 * Returns the end value of the animation.
+	 * Does not include progress, easing, interpolation, none of that - just the static end value
+	 */
+	public getTo() {
+		return this.to
+	}
+
+	/**
+	 * Unique identifier of an animation
+	 */
+	public getAnimationId(): string {
+		return this.animationId
+	}
+
+	/**
+	 * Returns the configuration - the duration of delay in between animation initialization, and transition.
+	 * Does not change in time, does not change when state changes, this is a static value.
+	 */
+	getAnimationBegin(): number {
+		return this.animationBegin
+	}
+
+	/**
+	 * Returns value of the transition at the current time.
+	 * The exact details differ based on the animation type
+	 */
+	public abstract getInterpolated(): T
+
+	/**
+	 * Returns the duration of time of when the controller should ask for the next update
+	 */
+	protected abstract nextAnimationUpdate(timeElapsed: number): number
+}
+
+/**
+ * Animation handle representing a Javascript-based animation.
+ * This animation requires one render cycle for each frame, and it calls setTimeout as quickly as possible
+ *
+ * @since 3.9
+ */
+export class JavascriptAnimation extends RechartsAnimation<number, EasingFunction> {
+	// eslint-disable-next-line class-methods-use-this
+	protected nextAnimationUpdate(): number {
+		/*
+		 * JavaScript-based animations have to update as soon as possible,
+		 * so we return 0 here to indicate that the next update should be scheduled immediately
+		 * and it should trigger render on every occasion.
+		 */
+		return 0
+	}
+
+	/**
+	 * Returns value of the animation after its easing function had been applied.
+	 * This value, unlike getProgress(), can escape the [0..1] range
+	 * because this is entirely within the easing function control. Spring typically does this.
+	 */
+	public getInterpolated(): number {
+		return this.easing(interpolate(this.getFrom(), this.getTo(), this.getProgress()))
+	}
+}
+
+/**
+ * Animation handle representing a CSS transition.
+ * This animation requires only one render, and the actual transition is then handled by the browser.
+ *
+ * @since 3.9
+ */
+export class CSSTransitionAnimation extends RechartsAnimation<string, NamedBezier> {
+	protected nextAnimationUpdate(timeElapsed: number): number {
+		/**
+		 * CSS transitions do not need DOM updates past the initial render
+		 * so here we just instruct the controller to wait until the animation duration is over.
+		 */
+		return duration(this.animationDuration - timeElapsed)
+	}
+
+	/**
+	 * Returns the final value of the animation (the `to`).
+	 *
+	 * CSS transitions leave both interpolation and easing to the browser,
+	 * so all we need to do here is return the final state
+	 * and let browser handle the rest.
+	 */
+	public getInterpolated(): string {
+		return this.getTo()
+	}
+}
+
+/**
+ * Recharts animation state machine.
+ *
+ * Possible transitions are:
+ * - `init`: starting state - `onAnimationStart` executes
+ * - `init` to `pending` - `animationBegin` duration begins
+ * - `pending` to `active` - `animationDuration` duration begins, timer ticks decide the progress
+ * - `active` to `completed` - `onAnimationEnd` executes
+ *
+ * The state always moves in this direction, cannot move backwards.
+ *
+ * The animation queue is static and consists of four elements:
+ * - `onAnimationStart`: function that is called when the animation is created
+ * - `animationBegin`: delay between `onAnimationStart` and the transition
+ * - the transition itself, takes `animationDuration` ms to finish
+ * - `onAnimationEnd`: function that is called when the animation is moving from `active` to `completed`
+ *
+ * @see {@link https://recharts.github.io/en-US/guide/animations/ Animation guide}
+ *
+ * @since 3.9
+ */
+export type AnimationHandle = JavascriptAnimation | CSSTransitionAnimation