@solidports/recharts 0.1.0

package/src/util/useAnimationId.ts

@@ -0,0 +1,31 @@
+/* eslint-disable import/no-cycle */
+import { createMemo } from 'solid-js';
+import { uniqueId } from "./DataUtils"
+import { structurallyEqual } from "./structurallyEqual"
+
+/* React `useAnimationId(input, prefix)` regenerates id when `input !== prev` by
+   reference. React renders hand fresh `props` objects per render, so refs flip
+   on parent updates. Solid props proxies stay stable across data updates — we
+   must compare CONTENT, not reference (see structurallyEqual below). */
+/* Solid port (was: setAnimationId inside a memo that also read animationId()
+   formed a write-after-read cycle, OOM under fresh-each-call refs). Drop the
+   signal — keep previous input + current id in plain mutable state, recompute
+   synchronously when tracked input CONTENT changes. Reference equality alone
+   misfires under Solid because selectors return fresh arrays even when content
+   is unchanged. */
+const UNINITIALIZED = Symbol("useAnimationId.uninitialized")
+
+export function useAnimationId(input: () => unknown, prefix: string = "animation-"): () => string {
+	let prevInput: unknown = UNINITIALIZED
+	let currentId = uniqueId(prefix)
+
+	const animationId = createMemo(() => {
+		const currentInput = input()
+		if (prevInput !== UNINITIALIZED && !structurallyEqual(prevInput, currentInput)) {
+			currentId = uniqueId(prefix)
+		}
+		prevInput = currentInput
+		return currentId
+	})
+	return animationId
+}

package/src/util/useElementOffset.ts

@@ -0,0 +1,110 @@
+import { createSignal, untrack, createEffect } from 'solid-js';
+const EPS = 1
+
+/**
+ * Stores the `offsetHeight`, `offsetLeft`, `offsetTop`, and `offsetWidth` of a DOM element.
+ */
+export type ElementOffset = {
+	/**
+	 * Height of an element, including vertical padding and borders, as an integer.
+	 *
+	 * Typically, offsetHeight is a measurement in pixels of the element's CSS height, including any borders, padding, and horizontal scrollbars (if rendered). It does not include the height of pseudo-elements such as ::before or ::after
+	 *
+	 * https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetHeight
+	 */
+	height: number
+	/**
+	 * Number of pixels that the upper left corner of the current element is offset to the left within the HTMLElement.offsetParent node
+	 *
+	 * https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetLeft
+	 */
+	left: number
+	/**
+	 * Distance from the outer border of the current element (including its margin) to the top padding edge of the offsetParent, the closest positioned ancestor element.
+	 *
+	 * https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetTop
+	 */
+	top: number
+	/**
+	 * Layout width of an element as an integer.
+	 *
+	 * Typically, offsetWidth is a measurement in pixels of the element's CSS width, including any borders, padding, and vertical scrollbars (if rendered). It does not include the width of pseudo-elements such as ::before or ::after.
+	 *
+	 * https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetWidth
+	 */
+	width: number
+}
+
+export type SetElementOffset = (node: HTMLElement | null) => void
+
+/**
+ * Listen to element layout changes.
+ *
+ * Pass the returned setter as a ref callback: `<div ref={updateElementOffset}>`.
+ *
+ * @param extraDeps Accessor returning a list of values that should re-trigger a measurement.
+ *   Equivalent to React's `useElementOffset(extraDependencies)` — useful when the
+ *   element re-renders children (payload, label) but the layout box of the parent
+ *   must be re-read to compute a transform.
+ */
+export function useElementOffset(
+	extraDeps?: () => readonly unknown[],
+): [() => ElementOffset, SetElementOffset] {
+	const [lastBoundingBox, setLastBoundingBox] = createSignal<ElementOffset>({
+		height: 0,
+		left: 0,
+		top: 0,
+		width: 0,
+	})
+	const [node, setNode] = createSignal<HTMLElement | null>(null)
+
+	const measure = (target: HTMLElement) => {
+		const rect = target.getBoundingClientRect()
+		const current = untrack(lastBoundingBox)
+		if (
+			Math.abs(rect.height - current.height) > EPS ||
+			Math.abs(rect.left - current.left) > EPS ||
+			Math.abs(rect.top - current.top) > EPS ||
+			Math.abs(rect.width - current.width) > EPS
+		) {
+			setLastBoundingBox({
+				height: rect.height,
+				left: rect.left,
+				top: rect.top,
+				width: rect.width,
+			})
+		}
+	}
+
+	/* Measure after the node attaches and whenever any tracked dep changes — mirrors
+	   React's ref callback (called at commit, with children in place) and
+	   useCallback([extraDependencies]), which forces a fresh ref callback. A Solid ref
+	   fires before dynamic children are inserted, so the ref itself does not measure.
+	   Without the deps the bounding box is read once at mount (often 0×0 for a hidden
+	   tooltip) and never updates when payload/active flips. */
+	createEffect(
+		() => {
+			extraDeps?.()
+			return node()
+		},
+		(target) => {
+			if (target != null) measure(target)
+		},
+	)
+
+	/* ResizeObserver covers the case where children grow/shrink (formatter,
+	   payload row count) without an explicit dep change. Guarded for SSR /
+	   environments without RO support (e.g. very old jsdom). */
+	createEffect(node, (target) => {
+		if (target == null || typeof ResizeObserver === "undefined") return undefined
+		const ro = new ResizeObserver(() => measure(target))
+		ro.observe(target)
+		return () => ro.disconnect()
+	})
+
+	const updateBoundingBox: SetElementOffset = (next) => {
+		setNode(next)
+	}
+
+	return [lastBoundingBox, updateBoundingBox]
+}

package/src/util/useId.ts

@@ -0,0 +1,8 @@
+import { createUniqueId } from 'solid-js';
+/**
+ * Generates a unique ID using Solid's createUniqueId.
+ * This is SSR-safe in Solid.
+ *
+ * @returns A unique ID that remains consistent across renders.
+ */
+export const useId: () => string = createUniqueId

package/src/util/usePrefersReducedMotion.ts

@@ -0,0 +1,48 @@
+import { Global } from "./Global"
+
+const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)"
+
+/* One live MediaQueryList for the page (re-queried only if `matchMedia` itself is replaced).
+   Every animated shape reads it on mount, so a query per instance shows up on chart switch. */
+let queriedWith: typeof window.matchMedia | undefined
+let mediaQuery: MediaQueryList | undefined
+
+function readPrefersReducedMotion(): boolean {
+	if (Global.isSsr) {
+		return false
+	}
+	if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+		return false
+	}
+	if (mediaQuery === undefined || queriedWith !== window.matchMedia) {
+		queriedWith = window.matchMedia
+		mediaQuery = window.matchMedia(REDUCED_MOTION_QUERY)
+	}
+	return mediaQuery.matches
+}
+
+/**
+ * Reads the user's `prefers-reduced-motion` system preference.
+ * Returns `true` when the user prefers reduced motion, `false` otherwise.
+ * SSR-safe: always returns `false` during server-side rendering.
+ *
+ * Components run once in Solid, so the value is read at mount, as upstream's first render
+ * does. Upstream re-renders on a preference change; a snapshot here never would, so no
+ * change listener is kept per instance.
+ */
+export function usePrefersReducedMotion(): boolean {
+	return readPrefersReducedMotion()
+}
+
+/**
+ * `'auto'` follows reduced-motion and is off during SSR; a boolean is returned as-is.
+ */
+export function resolveIsAnimationActive(
+	isActive: boolean | "auto",
+	prefersReducedMotion: boolean,
+): boolean {
+	if (isActive === "auto") {
+		return Global.isSsr === false && prefersReducedMotion === false
+	}
+	return isActive
+}

package/src/util/useReportScale.ts

@@ -0,0 +1,24 @@
+/* eslint-disable import/no-cycle */
+import { createEffect, createSignal, untrack } from 'solid-js';
+import { useChartStore } from "../state/RechartsStoreContext"
+import { selectContainerScale } from "../state/selectors/containerSelectors"
+import { isWellBehavedNumber } from "./isWellBehavedNumber"
+
+export function useReportScale() {
+	const ctx = useChartStore()
+	const [ref, setRef] = createSignal<HTMLElement | null>(null)
+
+	createEffect(ref, (el) => {
+		if (el == null || ctx == null) {
+			return
+		}
+		const scale = untrack(() => selectContainerScale(ctx.store))
+		const rect = el.getBoundingClientRect()
+		const newScale = rect.width / el.offsetWidth
+		if (isWellBehavedNumber(newScale) && newScale !== scale) {
+			ctx.setStore("layout", "scale", newScale)
+		}
+	})
+
+	return setRef
+}

package/src/util/useUniqueId.ts

@@ -0,0 +1,30 @@
+import { useId } from "./useId"
+
+/**
+ * Generates a unique ID. It uses Solid's createUniqueId() for SSR safety.
+ *
+ * The ID will stay the same across renders, and you can optionally provide a prefix.
+ *
+ * @param [prefix] - An optional prefix for the generated ID.
+ * @param [customId] - An optional custom ID to override the generated one.
+ * @returns The unique ID.
+ */
+export function useUniqueId(prefix?: string, customId?: string): string {
+	const generatedId = useId()
+
+	if (customId) {
+		return customId
+	}
+
+	return prefix ? `${prefix}-${generatedId}` : generatedId
+}
+
+/**
+ * The useUniqueId hook returns a unique ID that is either reused from external props or generated internally.
+ * Either way the ID is now guaranteed to be present so no more nulls or undefined.
+ */
+export type WithIdRequired<T> = T & {
+	id: string
+}
+
+export type WithoutId<T> = Omit<T, "id">

package/src/zIndex/DefaultZIndexes.ts

@@ -0,0 +1,84 @@
+/* eslint-disable import/no-cycle, sort-keys */
+/**
+ * A collection of all default zIndex values used by Recharts.
+ *
+ * You can reuse these, or you can define your own.
+ */
+export const DefaultZIndexes = {
+	/**
+	 * CartesianGrid and PolarGrid
+	 */
+	grid: -100,
+	/**
+	 * Background of Bar and RadialBar.
+	 * This is not visible by default but can be enabled by setting background={true} on Bar or RadialBar.
+	 */
+	barBackground: -50,
+
+	/*
+	 * other chart elements or custom elements without specific zIndex
+	 * render in here, at zIndex 0
+	 */
+
+	/**
+	 * Area, Pie, Radar, and ReferenceArea
+	 */
+	area: 100,
+
+	/**
+	 * Cursor is embedded inside Tooltip and controlled by it.
+	 * The Tooltip itself has a separate portal and is not included in the zIndex system;
+	 * Cursor is the decoration inside the chart area. CursorRectangle is a rectangle box.
+	 * It renders below bar so that in a stacked bar chart the cursor rectangle does not hide the other bars.
+	 */
+	cursorRectangle: 200,
+
+	/**
+	 * Bar and RadialBar
+	 */
+	bar: 300,
+
+	/**
+	 * Line and ReferenceLine, and ErrorBor
+	 */
+	line: 400,
+
+	/**
+	 * XAxis and YAxis and PolarAngleAxis and PolarRadiusAxis ticks and lines and children
+	 */
+	axis: 500,
+
+	/**
+	 * Scatter and ReferenceDot,
+	 * and Dots of Line and Area and Radar if they have dot=true
+	 */
+	scatter: 600,
+
+	/**
+	 * Hovering over a Bar or RadialBar renders a highlight rectangle
+	 */
+	activeBar: 1000,
+
+	/**
+	 * Cursor is embedded inside Tooltip and controlled by it.
+	 * The Tooltip itself has a separate portal and is not included in the zIndex system;
+	 * Cursor is the decoration inside the chart area, usually a cross or a box.
+	 * CursorLine is a line cursor rendered in Line, Area, Scatter, Radar charts.
+	 * It renders above the Line and Scatter so that it is always visible.
+	 * It renders below active dot so that the dot is always visible and shows the current point.
+	 * We're also assuming that the active dot is small enough that it does not fully cover the cursor line.
+	 *
+	 * This also applies to the radial cursor in RadialBarChart.
+	 */
+	cursorLine: 1100,
+
+	/**
+	 * Hovering over a Point in Line, Area, Scatter, Radar renders a highlight dot
+	 */
+	activeDot: 1200,
+
+	/**
+	 * LabelList and Label, including Axis labels
+	 */
+	label: 2000,
+} as const satisfies Record<string, number>

package/src/zIndex/ZIndexLayer.tsx

@@ -0,0 +1,121 @@
+/* eslint-disable import/no-cycle */
+import type { JSX } from '@solidjs/web';
+import { createEffect, createMemo, Show, untrack } from 'solid-js';
+import { Portal } from '@solidjs/web';
+import { useChartStore } from "../state/RechartsStoreContext"
+import { selectZIndexPortalElement } from "./zIndexSelectors"
+import { useIsInChartContext } from "../context/chartLayoutContext"
+import { useIsPanorama } from "../context/PanoramaContext"
+import { teardownWrite } from "../state/teardownWrite"
+
+/**
+ * @since 3.4
+ */
+export interface ZIndexable {
+	/**
+	 * Z-Index of this component and its children. The higher the value,
+	 * the more on top it will be rendered.
+	 * Components with higher zIndex will appear in front of components with lower zIndex.
+	 * If undefined or 0, the content is rendered in the default layer without portals.
+	 *
+	 * @since 3.4
+	 * @defaultValue 0
+	 * @see {@link https://recharts.github.io/en-US/guide/zIndex/ Z-Index and layers guide}
+	 */
+	zIndex?: number
+}
+
+type ZIndexLayerProps = {
+	/**
+	 * Z-Index of this component and its children.
+	 *
+	 * The higher the value, the more on top it will be rendered.
+	 * Components with higher zIndex will appear in front of components with lower zIndex.
+	 *
+	 * If `undefined` or `0`, the content is rendered in the default layer without portals.
+	 */
+	zIndex: number | undefined
+	/**
+	 * The content to render inside this zIndex layer.
+	 * Undefined children are allowed and will render nothing and will still report the zIndex to the portal system.
+	 */
+	children?: JSX.Element
+}
+
+/**
+ * A layer that renders its children into a portal corresponding to the given zIndex.
+ * We can't use regular CSS `z-index` because SVG does not support it.
+ * So instead, we create separate DOM nodes for each zIndex layer
+ * and render the children into the corresponding DOM node using portals.
+ *
+ * This component must be used inside a Chart component.
+ *
+ * @param zIndex numeric zIndex value, higher values are rendered on top of lower values
+ * @param children the content to render inside this zIndex layer
+ *
+ * @since 3.4
+ */
+export function ZIndexLayer(props: ZIndexLayerProps) {
+	/*
+	 * If we are outside of chart, then we can't rely on the zIndex portal state,
+	 * so we just render normally.
+	 */
+	const isInChartContext = createMemo(() => useIsInChartContext())
+	/*
+	 * If zIndex is undefined then we render normally without portals.
+	 * Also, if zIndex is 0, we render normally without portals,
+	 * because 0 is the default layer that does not need a portal.
+	 */
+	const shouldRenderInPortal = () =>
+		isInChartContext() && props.zIndex !== undefined && props.zIndex !== 0
+
+	const isPanorama = useIsPanorama()
+
+	const ctx = useChartStore()
+
+	/*
+	 * Because zIndexes are dynamic (meaning, we're not working with a predefined set of layers,
+	 * but we allow users to define any zIndex at any time), we need to register
+	 * the requested zIndex in the global store. This way, the ZIndexPortals component
+	 * can render the corresponding portals and only the requested ones.
+	 */
+	createEffect(
+		() => (shouldRenderInPortal() ? (props.zIndex ?? 0) : null),
+		(z) => {
+			if (z == null || ctx == null) {
+				return undefined
+			}
+			if (untrack(() => ctx.store.zIndex.zIndexMap[z]) == null) {
+				ctx.setStore("zIndex", "zIndexMap", z, {
+					consumers: 0,
+					element: undefined,
+					panoramaElement: undefined,
+				})
+			}
+			ctx.setStore("zIndex", "zIndexMap", z, "consumers", (c: number) => c + 1)
+			return () => {
+				teardownWrite(() => {
+					ctx.setStore("zIndex", "zIndexMap", z, "consumers", (c: number) => Math.max(0, c - 1))
+				})
+			}
+		},
+	)
+
+	const portalElement = createMemo(() =>
+		ctx ? selectZIndexPortalElement(ctx.store, props.zIndex, isPanorama) : undefined,
+	)
+
+	return (
+		<Show when={shouldRenderInPortal()} fallback={props.children}>
+			<Show when={portalElement()}>
+				{/* mount is an SVG <g>; Solid 2's Portal inserts children between text
+				   markers without a wrapper element, so SVG content stays valid. */}
+				{(mount) => (
+					<Portal mount={mount()}>
+						{props.children}
+					</Portal>
+				)}
+			</Show>
+		</Show>
+	)
+}

package/src/zIndex/ZIndexPortal.tsx

@@ -0,0 +1,79 @@
+import type { JSX } from '@solidjs/web';
+import { createMemo, For, createEffect, untrack } from 'solid-js';
+import { useChartStore } from "../state/RechartsStoreContext"
+import { selectAllRegisteredZIndexes } from "./zIndexSelectors"
+import { teardownWrite } from "../state/teardownWrite"
+
+function ZIndexSvgPortal(props: { zIndex: number; isPanorama: boolean }) {
+	let ref: SVGGElement | undefined
+	const ctx = useChartStore()
+
+	createEffect(
+		() => ({ isPanorama: props.isPanorama, zIndex: props.zIndex }),
+		({ isPanorama, zIndex }) => {
+			if (ref == null || ctx == null) {
+				return undefined
+			}
+			const key = isPanorama ? "panoramaElement" : "element"
+			const ensureEntry = () => {
+				if (untrack(() => ctx.store.zIndex.zIndexMap[zIndex]) == null) {
+					ctx.setStore("zIndex", "zIndexMap", zIndex, {
+						consumers: 0,
+						element: undefined,
+						panoramaElement: undefined,
+					})
+				}
+			}
+			ensureEntry()
+			ctx.setStore("zIndex", "zIndexMap", zIndex, key, ref)
+			return () => {
+				teardownWrite(() => {
+					ensureEntry()
+					ctx.setStore("zIndex", "zIndexMap", zIndex, key, undefined)
+				})
+			}
+		},
+	)
+
+	/* these g elements should not be tabbable */
+	return <g tabindex={-1} ref={ref} class={`recharts-zIndex-layer_${props.zIndex}`} />
+}
+
+export function AllZIndexPortals(props: { children?: JSX.Element; isPanorama: boolean }) {
+	const ctx = useChartStore()
+	const allRegisteredZIndexes = createMemo(() =>
+		ctx ? selectAllRegisteredZIndexes(ctx.store) : undefined,
+	)
+
+	const negativeZIndexes = createMemo(() => {
+		const all = allRegisteredZIndexes()
+		return all ? all.filter((zIndex) => zIndex < 0) : []
+	})
+	/* zero is the default layer and does not need a portal */
+	const positiveZIndexes = createMemo(() => {
+		const all = allRegisteredZIndexes()
+		return all ? all.filter((zIndex) => zIndex > 0) : []
+	})
+
+	/* `props.children` always lives in this same JSX position. The earlier
+	 * `<Show when={hasAny()} fallback={props.children}>` shape re-mounted the
+	 * subtree every time `hasAny()` flipped — and child mount/unmount fires
+	 * `addZIndexLayer` / `removeZIndexLayer` from each `ZIndexLayer` createEffect,
+	 * which flips `hasAny()` again. That feedback loop is the BarStack hang
+	 * (Bar's `<ZIndexLayer zIndex={300}>` toggles `hasAny()` between false ↔ true
+	 * on every cycle, re-mounting Bar, re-running registration, OOM). React's
+	 * `if (!all || all.length === 0) return children` is a single, stable
+	 * subtree — replicate that by always rendering children in one position
+	 * and conditionally rendering the portal Fors around them. */
+	return (
+		<>
+			<For each={negativeZIndexes()}>
+				{(zIndex) => <ZIndexSvgPortal zIndex={zIndex} isPanorama={props.isPanorama} />}
+			</For>
+			{props.children}
+			<For each={positiveZIndexes()}>
+				{(zIndex) => <ZIndexSvgPortal zIndex={zIndex} isPanorama={props.isPanorama} />}
+			</For>
+		</>
+	)
+}

package/src/zIndex/getZIndexFromUnknown.ts

@@ -0,0 +1,14 @@
+import { isWellBehavedNumber } from "../util/isWellBehavedNumber"
+
+export function getZIndexFromUnknown(input: unknown, defaultZIndex: number): number {
+	if (
+		input &&
+		typeof input === "object" &&
+		"zIndex" in input &&
+		typeof input.zIndex === "number" &&
+		isWellBehavedNumber(input.zIndex)
+	) {
+		return input.zIndex
+	}
+	return defaultZIndex
+}

package/src/zIndex/zIndexSelectors.ts

@@ -0,0 +1,48 @@
+import type { ChartState } from "../state/store"
+import { DefaultZIndexes } from "./DefaultZIndexes"
+
+/**
+ * Given a zIndex, returns the corresponding portal element reference.
+ * If no zIndex is provided or if the zIndex is not registered, returns undefined.
+ *
+ * It also returns undefined in case the z-index portal has not been rendered yet.
+ */
+export function selectZIndexPortalElement(
+	state: ChartState,
+	zIndex: number | undefined,
+	isPanorama: boolean,
+): Element | undefined {
+	if (zIndex == null) {
+		return undefined
+	}
+	const entry = state.zIndex.zIndexMap[zIndex]
+	if (entry == null) {
+		return undefined
+	}
+	if (isPanorama) {
+		return entry.panoramaElement
+	}
+	return entry.element
+}
+
+/* Upstream memoizes with a result equality check: an equal list keeps its reference. */
+const lastRegisteredZIndexes = new WeakMap<object, ReadonlyArray<number>>()
+
+export function selectAllRegisteredZIndexes(state: ChartState): ReadonlyArray<number> {
+	const zIndexMap = state.zIndex.zIndexMap
+	const allNumbers = Object.keys(zIndexMap)
+		.map((zIndexStr) => parseInt(zIndexStr, 10))
+		.concat(Object.values(DefaultZIndexes))
+	const uniqueNumbers = Array.from(new Set(allNumbers)).sort((a, b) => a - b)
+	const key = state.zIndex as object
+	const previous = lastRegisteredZIndexes.get(key)
+	if (
+		previous != null &&
+		previous.length === uniqueNumbers.length &&
+		previous.every((value, index) => value === uniqueNumbers[index])
+	) {
+		return previous
+	}
+	lastRegisteredZIndexes.set(key, uniqueNumbers)
+	return uniqueNumbers
+}