@octanejs/recharts 0.1.41 → 0.1.42

package/src/animation/easing.ts

@@ -0,0 +1,235 @@
+// Adapted from recharts@3.9.2, commit b3451050c027a23957ffa50a2665c9119df21e47.
+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]!, coords[1]!, coords[2]!, coords[3]!];
+};
+
+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.js → matchBy.ts}

@@ -1,68 +1,5 @@
-// Vendored verbatim from recharts@3.9.2 es6/animation/matchBy.js (framework-agnostic).
-// Do not edit — update by re-vendoring when the recharts devDependency moves.
-function _slicedToArray(r, e) {
-	return (
-		_arrayWithHoles(r) ||
-		_iterableToArrayLimit(r, e) ||
-		_unsupportedIterableToArray(r, e) ||
-		_nonIterableRest()
-	);
-}
-function _nonIterableRest() {
-	throw new TypeError(
-		'Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.',
-	);
-}
-function _unsupportedIterableToArray(r, a) {
-	if (r) {
-		if ('string' == typeof r) return _arrayLikeToArray(r, a);
-		var t = {}.toString.call(r).slice(8, -1);
-		return (
-			'Object' === t && r.constructor && (t = r.constructor.name),
-			'Map' === t || 'Set' === t
-				? Array.from(r)
-				: 'Arguments' === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t)
-					? _arrayLikeToArray(r, a)
-					: void 0
-		);
-	}
-}
-function _arrayLikeToArray(r, a) {
-	(null == a || a > r.length) && (a = r.length);
-	for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e];
-	return n;
-}
-function _iterableToArrayLimit(r, l) {
-	var t =
-		null == r ? null : ('undefined' != typeof Symbol && r[Symbol.iterator]) || r['@@iterator'];
-	if (null != t) {
-		var e,
-			n,
-			i,
-			u,
-			a = [],
-			f = !0,
-			o = !1;
-		try {
-			if (((i = (t = t.call(r)).next), 0 === l)) {
-				if (Object(t) !== t) return;
-				f = !1;
-			} else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0);
-		} catch (r) {
-			((o = !0), (n = r));
-		} finally {
-			try {
-				if (!f && null != t.return && ((u = t.return()), Object(u) !== u)) return;
-			} finally {
-				if (o) throw n;
-			}
-		}
-		return a;
-	}
-}
-function _arrayWithHoles(r) {
-	if (Array.isArray(r)) return r;
-}
+// Adapted from recharts@3.9.2, commit b3451050c027a23957ffa50a2665c9119df21e47.
+import { DataKey } from '../util/types';
 import { getValueByDataKey } from '../util/ChartUtils';
 
 /**
@@ -75,6 +12,10 @@ import { getValueByDataKey } from '../util/ChartUtils';
  * @since 3.9
  * @see {@link https://recharts.github.io/en-US/guide/animations Animation guide}
  */
+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.
@@ -88,6 +29,7 @@ import { getValueByDataKey } from '../util/ChartUtils';
  * @since 3.9
  * @see {@link https://recharts.github.io/en-US/guide/animations Animation guide}
  */
+export type AnimationMatchBy<T> = (item: T, index: number) => string | number | null;
 
 /**
  * The union of all accepted `animationMatchBy` prop values:
@@ -96,6 +38,8 @@ import { getValueByDataKey } from '../util/ChartUtils';
  * @since 3.9
  * @see {@link https://recharts.github.io/en-US/guide/animations Animation guide}
  */
+export type AnimationMatchByProp<T> =
+	typeof matchByIndex | typeof matchAppend | AnimationMatchBy<T>;
 
 /**
  * Match animation items by their array index (the default behavior).
@@ -112,7 +56,7 @@ import { getValueByDataKey } from '../util/ChartUtils';
  * @since 3.9
  * @see {@link https://recharts.github.io/en-US/guide/animations Animation guide}
  */
-export var matchByIndex = 'index';
+export const matchByIndex = 'index' as const;
 
 /**
  * Match animation items sequentially: previous item 0 pairs with next item 0,
@@ -130,7 +74,7 @@ export var matchByIndex = 'index';
  * @since 3.9
  * @see {@link https://recharts.github.io/en-US/guide/animations Animation guide}
  */
-export var matchAppend = 'append';
+export const matchAppend = 'append' as const;
 
 /**
  * Create a matching function that pairs items by a data key from their payload.
@@ -151,66 +95,74 @@ export var matchAppend = 'append';
  * @since 3.9
  * @see {@link https://recharts.github.io/en-US/guide/animations Animation guide}
  */
-export function matchByDataKey(dataKey) {
-	return (item) => {
+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;
-		var value = getValueByDataKey(item.payload, dataKey);
+		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(alignedPrevItems, nextItems) {
-	var removedPrevItems = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : [];
-	var tagged = [];
+
+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 you chart behaves differently you may want to customize your matching function.
 	 */
-	for (var prev of removedPrevItems) {
-		tagged.push({
-			status: 'removed',
-			prev,
-		});
+	for (const prev of removedPrevItems) {
+		tagged.push({ status: 'removed', prev });
 	}
-	for (var i = 0; i < nextItems.length; i++) {
+	for (let i = 0; i < nextItems.length; i++) {
 		// This function intentionally pairs by array index. The strategy-specific functions above are
 		// responsible for producing an alignedPrevItems array whose indices already correspond to nextItems.
-		var _prev = alignedPrevItems[i];
-		var next = nextItems[i];
-		if (_prev != null) {
-			tagged.push({
-				status: 'matched',
-				prev: _prev,
-				next,
-			});
+		const prev = alignedPrevItems[i];
+		const next = nextItems[i]!;
+		if (prev != null) {
+			tagged.push({ status: 'matched', prev, next });
 		} else {
-			tagged.push({
-				status: 'added',
-				next,
-			});
+			tagged.push({ status: 'added', next });
 		}
 	}
 	return tagged;
 }
-function matchByIndexImpl(prevItems, nextItems) {
-	var factor = prevItems.length / nextItems.length;
-	var alignedPrevItems = nextItems.map((_, i) => prevItems[Math.floor(i * factor)]);
+
+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(prevItems, nextItems) {
-	var alignedPrevItems = nextItems.map((_, i) => prevItems[i]);
+
+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(prevItems, matchBy) {
-	var prevMap = new Map();
-	for (var i = 0; i < prevItems.length; i++) {
-		var _item = prevItems[i];
-		if (_item == null) continue;
-		var key = matchBy(_item, i);
+
+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);
+			prevMap.set(key, item);
 		}
 	}
 	return prevMap;
@@ -221,15 +173,20 @@ function buildPrevKeyMap(prevItems, matchBy) {
  *
  * @internal
  */
-function matchByKey(prevItems, nextItems, matchBy) {
-	var prevMap = buildPrevKeyMap(prevItems, matchBy);
+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
-	var matchedKeys = new Set();
-	var alignedPrevItems = nextItems.map((next, i) => {
-		var key = matchBy(next, i);
+	const matchedKeys = new Set<string | number>();
+
+	const alignedPrevItems = nextItems.map((next, i) => {
+		const key = matchBy(next, i);
 		if (key != null) {
-			var prev = prevMap.get(key);
+			const prev = prevMap.get(key);
 			if (prev !== undefined) {
 				matchedKeys.add(key);
 				return prev;
@@ -239,15 +196,13 @@ function matchByKey(prevItems, nextItems, matchBy) {
 	});
 
 	// Removed = prev items whose keys were not matched to any next item
-	var removedPrevItems = [];
-	for (var _ref3 of prevMap) {
-		var _ref2 = _slicedToArray(_ref3, 2);
-		var key = _ref2[0];
-		var _item2 = _ref2[1];
+	const removedPrevItems: T[] = [];
+	for (const [key, item] of prevMap) {
 		if (!matchedKeys.has(key)) {
-			removedPrevItems.push(_item2);
+			removedPrevItems.push(item);
 		}
 	}
+
 	return tagAlignedItems(alignedPrevItems, nextItems, removedPrevItems);
 }
 
@@ -259,15 +214,16 @@ function matchByKey(prevItems, nextItems, matchBy) {
  *
  * @internal
  */
-export function matchAnimationItems(prevItems, nextItems, matchBy) {
+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,
-		}));
+		return nextItems.map((next) => ({ status: 'added', next }));
 	}
 	if (matchBy === matchByIndex) {
 		return matchByIndexImpl(prevItems, nextItems);

package/src/animation/timeoutController.ts

@@ -0,0 +1,71 @@
+// Adapted from recharts@3.9.2, commit b3451050c027a23957ffa50a2665c9119df21e47.
+/**
+ * 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.ts

@@ -3,6 +3,7 @@
 // requestAnimationFrame).
 import { createContext, useContext, useMemo } from 'octane';
 import { animationControllerImpl } from './AnimationControllerImpl';
+import type { AnimationController } from './AnimationController';
 
 const AnimationControllerContext = createContext(animationControllerImpl);
 
@@ -13,7 +14,9 @@ const AnimationControllerContext = createContext(animationControllerImpl);
  */
 export const AnimationControllerProvider = AnimationControllerContext.Provider;
 
-export function useAnimationController(animationControllerFromProps: unknown) {
+export function useAnimationController(
+	animationControllerFromProps?: AnimationController,
+): AnimationController {
 	const animationControllerFromContext = useContext(AnimationControllerContext);
 	return useMemo(
 		() => animationControllerFromProps ?? animationControllerFromContext,

package/src/animation/useAnimationStartSnapshot.ts

@@ -3,9 +3,9 @@
 // visible frame" ref is only writable after the new cycle's t=0 handshake.
 import { useCallback, useRef } from 'octane';
 
-export function useAnimationStartSnapshot(
+export function useAnimationStartSnapshot<T>(
 	animationInput: unknown,
-	previousValueRef: { current: any },
+	previousValueRef: { current: T },
 ) {
 	// Identity of the animation cycle currently being served.
 	const previousAnimationInputRef = useRef(animationInput);
@@ -20,7 +20,7 @@ export function useAnimationStartSnapshot(
 		isReadyToCommitRef.current = false;
 	}
 	const syncStepValue = useCallback(
-		(stepValue: any, animationElapsedTime: number, canCommit = true) => {
+		(stepValue: T, animationElapsedTime: number, canCommit = true) => {
 			if (animationElapsedTime === 0) {
 				// t=0 handshake: the new animation has rendered its starting frame.
 				isReadyToCommitRef.current = true;

package/src/animation/util.ts

@@ -0,0 +1,12 @@
+// Adapted from recharts@3.9.2, commit b3451050c027a23957ffa50a2665c9119df21e47.
+/*
+ * @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(',');