solid-recharts 0.1.0

package/NEXT_SESSION_PROMPT.md

@@ -0,0 +1,114 @@
+# Session goal: grow the test suite (and fix what it surfaces)
+
+You are continuing a faithful port of **recharts 3.8.1 → SolidJS 2.0** living at
+`/Users/thomas/Downloads/solid-recharts/packages/solid-recharts`. The feature port is ~80%
+complete; **test coverage is the gap** — ~1217 cases vs recharts' ~3658 (~33%). Your job this
+session is to **port reference specs into the Solid suite**, and **fix any real port bugs the
+new tests surface**. Quality over volume: every test must be faithful and must pass for the
+right reason.
+
+## The reference
+
+recharts 3.8.1 source + tests are checked out at:
+
+- `/Users/thomas/Documents/Github/recharts-reference/src`
+- `/Users/thomas/Documents/Github/recharts-reference/test`
+
+Port the reference spec's _intent and exact assertions_ (golden numbers, geometry, counts),
+adapting only the React→Solid mechanics.
+
+## Non-negotiable conventions (these OVERRIDE defaults)
+
+1. **Gate after EVERY change**: `vp check --fix` (lint/format/type — must end at _0 errors_;
+   10 warnings is the known steady-state baseline) AND `vp test run` (must stay fully green).
+   Do NOT use `npx vitest` — use `vp test run <pattern>`.
+2. **No `any`, no `as`, no non-null `!` in src, no `@ts-expect-error`.** The lint is
+   type-aware and WILL catch these (it already caught a bad test this project). Use typed
+   coercion / helpers instead.
+3. **Faithful porting.** If a feature is genuinely deferred in the port (check the file's
+   header comment), don't assert it — write a _subset_ spec mirroring the existing ported
+   specs' style, and note in the spec header which reference assertions you omitted and why.
+   If the spec fails because the **port has a real bug or missing-but-claimed feature, FIX the
+   port** (faithfully to recharts), don't weaken the test.
+4. **Document deviations** in spec/source header comments (the codebase does this consistently
+   — match the surrounding style, comment density, and naming).
+
+## Solid 2.0 gotchas that WILL bite (all learned the hard way — see memory)
+
+- A global guard in `test/setup.ts` **fails any test on a non-allowlisted Solid diagnostic**
+  (STRICT_READ_UNTRACKED etc). Common fixes:
+  - Don't read a reactive/accessor value directly in `<Show when={...}>` static children —
+    use the accessor-child form `<Show when={obj()}>{(v) => ...}</Show>` with a TRUTHY object
+    `when`, OR a plain **ternary** in JSX for a captured non-reactive const (a
+    `<Show when={capturedConst}>` still trips STRICT_READ).
+  - Bake values into `<For>`-item descriptors; don't render recursive hierarchies via
+    components that read reactive `props.*`.
+- **`mouseenter`/`mouseleave` do NOT bubble.** Item handlers live on the wrapping node
+  `<Layer>` — `fireEvent.mouseEnter` the Layer `g`, not the inner shape.
+- **Bar item-hover tooltip needs `<Tooltip shared={false}>`** (shared tooltips use the
+  axis/mouse path, not item-enter).
+- Solid 2.0 **defers propagation to a flush boundary**: after a sync signal set, a memo read
+  in the same tick is stale until `flush()`. Tests call `flush()` after render and after
+  `fireEvent`. Use local values (not re-read memos) inside event handlers.
+- Test wrappers: use `props.children`, never destructure `{children}` (breaks the store).
+
+## Exact commands
+
+```
+cd /Users/thomas/Downloads/solid-recharts/packages/solid-recharts
+vp test run <Name>      # run one spec (substring match), e.g. vp test run ChartUtils
+vp test run             # full suite (currently 1217 passing / 115 files)
+vp check --fix          # the gate (0 errors / 10 warnings = clean)
+```
+
+## Prioritized worklist (port in this order — fastest/safest first)
+
+**Tier 1 — pure-function specs (no DOM, no flake, highest value).** These pin exact numeric
+behavior of code we already ship but barely test. Reference paths under `…/recharts-reference/test/`:
+
+- `util/ChartUtils.spec.tsx`, `util/BarUtils.spec.tsx`, `util/DataUtils.spec.ts` (extend ours)
+- `util/round.spec.ts`, `util/isWellBehavedNumber.spec.ts`, `util/getRelativeCoordinate.spec.ts`
+- `util/ChartUtils/{truncateByDomain,getStackedData,getCateCoordinateOfLine}.spec.*`
+- `util/scale/{getNiceTickValues,arithmetic,createCategoricalInverse}.spec.ts`
+- `util/cursor/{getCursorRectangle,getCursorPoints,getRadialCursorPoints}.spec.ts`
+- `util/payload/getUniqPayload.spec.ts`, `util/tooltip/translate.spec.ts`
+- `util/CartesianUtils/{CartesianUtils,rectWithPoints}.spec.ts`, `util/PolarUtils.spec.ts`
+- `util/resolveDefaultProps.spec.tsx` (NB: our port uses Solid `merge`, not resolveDefaultProps
+  — adapt or skip with a note), `util/isDomainSpecifiedByUser.spec.ts`, `util/TickUtils.spec.ts`
+- Also untested port units with NO ref-named spec but clearly testable: `src/util/getSliced.ts`,
+  `getEveryNth.ts`, `getActiveCoordinate.ts`, `YAxisUtils.ts`, `getRadiusAndStrokeWidthFromDot.ts`,
+  `ReduceCSSCalc.ts` — write fresh unit specs from the port's behavior + reference src.
+
+**Tier 2 — state selectors (test through the store; medium effort).**
+`state/selectors/*.spec.tsx` — `dataSelectors`, `axisSelectors`, `legendSelectors`,
+`lineSelectors`, `pieSelectors`, `scatterSelectors`, `radialBarSelectors`, `selectChartOffset`,
+`combiners/combineActiveTooltipIndex`. Use the existing `test/helper/render` + store patterns.
+
+**Tier 3 — component/integration specs (deepen behavior).**
+`component/{Text,Label,LabelList,Legend,DefaultTooltipContent,Cursor,ResponsiveContainer}.spec.tsx`,
+`cartesian/{Area,Line,Bar/Bar,Scatter,CartesianAxis,CartesianGrid,ErrorBar,Brush}.spec.tsx`,
+`polar/{Pie/Pie,Radar,RadialBar/RadialBar,PolarGrid,PolarAngleAxis,PolarRadiusAxis}.spec.tsx`,
+`chart/{ComposedChart,RadarChart,ScatterChart,CategoricalChart}.spec.tsx`. These are big in the
+reference — port the parity-critical subset and document omissions (the existing `*.spec.tsx`
+headers show the house style).
+
+## Working rhythm
+
+1. Pick the next worklist item. Read the reference spec + the port's source.
+2. Port the spec into the mirrored path under `test/` (match existing naming/structure).
+3. `vp test run <Name>`. If it fails: decide — port bug (fix src faithfully) vs deferred feature
+   (subset the spec + document). Never weaken a test to hide a real gap.
+4. `vp check --fix`. Confirm 0 errors.
+5. Periodically run the full `vp test run` to catch cross-file regressions.
+6. Update `MEMORY.md` + a memory file when you learn something non-obvious or finish a cluster.
+
+## Context to load first
+
+Read the memory index at
+`/Users/thomas/.claude/projects/-Users-thomas-Downloads-solid-recharts/memory/MEMORY.md` and the
+files it points to (especially `expectclean-or-diagnostics-silent.md`,
+`solid2-reactivity-timing.md`, `root-config-and-lint.md`, `custom-shape-render-props.md`) — they
+encode the gate, the diagnostic guard, and the reactivity rules above.
+
+Start with **Tier 1** and report progress in batches (files ported, tests added, any port bugs
+fixed). Keep the suite green the whole way.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "solid-recharts",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "tiny-invariant": "^1.3.3",
+    "victory-vendor": "^37.0.2"
+  },
+  "devDependencies": {
+    "axe-core": "^4.12.0",
+    "vitest-axe": "^0.1.0",
+    "@solid-recharts/testing-library": "0.0.0"
+  },
+  "peerDependencies": {
+    "@solidjs/web": "^2.0.0-beta.14",
+    "solid-js": "^2.0.0-beta.14"
+  },
+  "scripts": {
+    "pretest": "node ../../scripts/verify-reference.mjs",
+    "test": "vp test run",
+    "test:watch": "vp test",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/animation/AnimatedItems.tsx

@@ -0,0 +1,169 @@
+// Ported from recharts 3.9.0 src/animation/AnimatedItems.tsx.
+//
+// Solid 2.0 port of the reusable array-data animation wrapper shared by all the
+// graphical items (Bar/Scatter/Funnel/Pie/Radar/RadialBar/Area/Line).
+// Deviations from the React reference:
+//   - React re-renders to advance frames; here the frame driver is `JavascriptAnimate`,
+//     which holds a `t` signal and re-invokes the render-prop child reactively from JSX.
+//   - `useRef` → a plain `{ current }` ref object ([[useAnimationStartSnapshot]]).
+//   - `useState` → `createSignal`; `useMemo` → `createMemo`.
+//   - The animation is driven by the v3.9 engine ([[AnimationHandle]] +
+//     [[AnimationController]]) via `JavascriptAnimate`, so a test can inject a
+//     deterministic controller through `AnimationControllerProvider`.
+//   - A keyed `<Show when={animationId()}>` wraps the driver so a new animation
+//     cycle remounts it cleanly (same NO_OWNER-safe shape Bar already used).
+import { createMemo, createSignal, untrack, Show } from "solid-js";
+import type { JSX } from "@solidjs/web";
+import { useAnimationId } from "../util/useAnimationId";
+import { noop } from "../util/DataUtils";
+import { useAnimationStartSnapshot, type MutableRef } from "./useAnimationStartSnapshot";
+import {
+  matchAnimationItems,
+  matchByIndex,
+  type AnimationItem,
+  type AnimationMatchByProp,
+} from "./matchBy";
+import type { CartesianLayout, PolarLayout } from "../util/types";
+import type { EasingInput } from "./easing";
+import { JavascriptAnimate } from "./JavascriptAnimate";
+
+/**
+ * Tracks animation start/end and exposes an `isAnimating` accessor.
+ */
+export function useAnimationCallbacks(
+  onAnimationStart?: () => void,
+  onAnimationEnd?: () => void,
+): {
+  isAnimating: () => boolean;
+  handleAnimationStart: () => void;
+  handleAnimationEnd: () => void;
+} {
+  // ownedWrite: handleAnimationEnd can fire from the driver's effect-cleanup when
+  // a mid-animation chart is disposed (route/soft navigation) — a legal teardown.
+  const [isAnimating, setIsAnimating] = createSignal(false, { ownedWrite: true });
+
+  const handleAnimationStart = (): void => {
+    onAnimationStart?.();
+    setIsAnimating(true);
+  };
+
+  const handleAnimationEnd = (): void => {
+    onAnimationEnd?.();
+    setIsAnimating(false);
+  };
+
+  return { isAnimating, handleAnimationStart, handleAnimationEnd };
+}
+
+/**
+ * Interpolates tagged animation items at a given normalized time. Receives the
+ * matched/added/removed changes and returns the items Recharts will render.
+ *
+ * @since 3.9
+ */
+export type AnimationInterpolateFn<ItemType, LayoutType extends CartesianLayout | PolarLayout> = (
+  items: ReadonlyArray<AnimationItem<ItemType>> | null,
+  animationElapsedTime: number,
+  layout: LayoutType,
+) => ReadonlyArray<ItemType>;
+
+export type AnimatedItemsProps<ItemType, LayoutType extends CartesianLayout | PolarLayout> = {
+  /** Opaque input to detect when a new animation should start (changes by reference → new cycle). */
+  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: MutableRef<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. */
+  animationMatchBy?: AnimationMatchByProp<ItemType>;
+  /** Optional guard for committing the previous-items ref. Default: `(t) => t > 0`. */
+  shouldUpdatePreviousRef?: (animationElapsedTime: number) => boolean;
+  /** Render with interpolated items + animation state. */
+  children: (
+    items: ReadonlyArray<ItemType>,
+    animationElapsedTime: number,
+    isEntrance: boolean,
+  ) => JSX.Element;
+  layout: LayoutType;
+};
+
+/**
+ * A reusable animation wrapper for array-based chart data.
+ *
+ * @since 3.9
+ */
+export function AnimatedItems<ItemType, LayoutType extends CartesianLayout | PolarLayout>(
+  props: AnimatedItemsProps<ItemType, LayoutType>,
+): JSX.Element {
+  const animationId = useAnimationId(() => props.animationInput, props.animationIdPrefix);
+  const snapshot = useAnimationStartSnapshot<ReadonlyArray<ItemType> | null | undefined>(
+    animationId,
+    props.previousItemsRef,
+  );
+
+  const rawPrevItems = createMemo<ReadonlyArray<ItemType> | null>(
+    () => snapshot.startValue() ?? null,
+  );
+  const animationItems = createMemo<ReadonlyArray<AnimationItem<ItemType>> | null>(() =>
+    matchAnimationItems(rawPrevItems(), props.items, props.animationMatchBy ?? matchByIndex),
+  );
+
+  return (
+    <Show when={animationId()} keyed>
+      {(keyedAnimationId) => (
+        <JavascriptAnimate
+          animationId={keyedAnimationId}
+          duration={props.animationDuration}
+          begin={props.animationBegin}
+          easing={props.animationEasing}
+          isActive={props.isAnimationActive}
+          onAnimationStart={props.onAnimationStart ?? noop}
+          onAnimationEnd={props.onAnimationEnd ?? noop}
+        >
+          {(animationElapsedTime) => {
+            const items = props.items;
+            // Match upstream's OBSERVABLE `isEntrance`: true only DURING the entrance
+            // animation (no prev items AND not yet settled). React's snapshot refreshes
+            // the frozen start value at t=1 so its isEntrance flips false on the settled
+            // frame; our memo-based snapshot can't, so we encode that result here with
+            // `< 1` instead — keeping every consumer (and future ones) in parity without
+            // a per-consumer `&& t < 1` guard. (See useAnimationStartSnapshot.)
+            const isEntrance = rawPrevItems() == null && animationElapsedTime < 1;
+            const stepData =
+              items == null
+                ? items
+                : props.animationInterpolateFn(
+                    animationItems(),
+                    animationElapsedTime,
+                    untrack(() => props.layout),
+                  );
+            const canUpdate = props.shouldUpdatePreviousRef
+              ? props.shouldUpdatePreviousRef(animationElapsedTime)
+              : animationElapsedTime > 0;
+            snapshot.syncStepValue(stepData, animationElapsedTime, canUpdate);
+            if (stepData == null) {
+              return null;
+            }
+            return props.children(stepData, animationElapsedTime, isEntrance);
+          }}
+        </JavascriptAnimate>
+      )}
+    </Show>
+  );
+}

package/src/animation/AnimationController.ts

@@ -0,0 +1,24 @@
+// Ported from recharts 3.9.0 src/animation/AnimationController.ts. Pure types.
+import type { CancelableTimeout, TimeoutController } from "./timeoutController";
+import type { AnimationHandle } from "./AnimationHandle";
+
+/**
+ * JavaScript-based animations produce numbers, and CSS transition-based animations produce strings.
+ *
+ * @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 creates a new controller.
+ *
+ * @since 3.9
+ */
+export type AnimationController = (
+  timeoutController: TimeoutController,
+  animationHandle: AnimationHandle,
+  listener: OnAnimationStateUpdate,
+) => CancelableTimeout;

package/src/animation/AnimationControllerImpl.ts

@@ -0,0 +1,37 @@
+// Ported from recharts 3.9.0 src/animation/AnimationControllerImpl.ts. Pure logic.
+import type { AnimationController, OnAnimationStateUpdate } from "./AnimationController";
+import type { AnimationHandle } from "./AnimationHandle";
+import type { CancelableTimeout, TimeoutController } from "./timeoutController";
+
+/**
+ * JavaScript animations require triggering a repaint as soon as possible, so this
+ * 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 consumer maps those values onto a component.
+ */
+export const animationControllerImpl: AnimationController = (
+  timeoutController: TimeoutController,
+  animationHandle: AnimationHandle,
+  listener: OnAnimationStateUpdate,
+): CancelableTimeout => {
+  let cancellable: CancelableTimeout | undefined;
+  const nextUpdate = (now: number): void => {
+    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,273 @@
+// Ported from recharts 3.9.0 src/animation/AnimationHandle.ts.
+// Pure state machine — no framework surface — so behavior is byte-identical to recharts.
+import { interpolate } from "../util/DataUtils";
+import type { ProgressEasingFn, 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`.
+   */
+  public getState(): AnimationState {
+    return this.state;
+  }
+
+  /**
+   * Returns the easing input or function
+   */
+  public getEasing(): E {
+    return this.easing;
+  }
+
+  /**
+   * Returns the configuration - the duration of the transition.
+   */
+  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!
+   *
+   * Returns the (relative) time remaining until the current activity is over — the same number you can
+   * put into setTimeout(fn, X) 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();
+      }
+      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();
+      }
+      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): void {
+    this.progress = Math.min(1, Math.max(0, newProgress));
+  }
+
+  /**
+   * Returns an abstract "progress" which is a number between 0 and 1 showing the distance of transition.
+   * - `init`: 0
+   * - `pending`: 0
+   * - `active`: transitioning between [0, 1] based on the time elapsed
+   * - `completed`: 1
+   *
+   * The progress is hard-capped to [0, 1] to avoid overshooting caused by coarse timers,
+   * so the easing function must be applied _after_ this animation state.
+   *
+   * The progress is linear with time. If you wish for easing, use `getInterpolated()` instead.
+   */
+  public getProgress(): number {
+    return this.progress;
+  }
+
+  /**
+   * Completes the animation. A completed animation cannot be manipulated anymore, its progress is set
+   * to 1, the tick function is a no-op and getState() always returns 'completed'.
+   */
+  public complete(): void {
+    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 (no progress, easing, or interpolation).
+   */
+  public getFrom(): T {
+    return this.from;
+  }
+
+  /**
+   * Returns the end value of the animation (no progress, easing, or interpolation).
+   */
+  public getTo(): T {
+    return this.to;
+  }
+
+  /**
+   * Unique identifier of an animation
+   */
+  public getAnimationId(): string {
+    return this.animationId;
+  }
+
+  /**
+   * Returns the configuration - the duration of delay between animation initialization and transition.
+   */
+  getAnimationBegin(): number {
+    return this.animationBegin;
+  }
+
+  /**
+   * Returns value of the transition at the current time. Details differ by animation type.
+   */
+  public abstract getInterpolated(): T;
+
+  /**
+   * Returns the duration of time after which 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, ProgressEasingFn> {
+  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.
+     */
+    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 that is
+   * entirely within the easing function's 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 the browser handle the rest.
+   */
+  public getInterpolated(): string {
+    return this.getTo();
+  }
+}
+
+/**
+ * Recharts animation state machine handle.
+ *
+ * @since 3.9
+ */
+export type AnimationHandle = JavascriptAnimation | CSSTransitionAnimation;