@octanejs/recharts 0.1.15 → 0.1.17

package/src/cartesian/CartesianGrid.tsrx

@@ -0,0 +1,643 @@
+import * as React from 'octane';
+import { ReactElement, SVGProps } from 'octane';
+
+import { warn } from '../util/LogUtils';
+import { isNumber } from '../util/DataUtils';
+import { ChartOffsetInternal } from '../util/types';
+
+import {
+	AxisPropsNeededForTicksGenerator,
+	getCoordinatesOfGrid,
+	getTicksOfAxis,
+} from '../util/ChartUtils';
+import { getTicks, GetTicksInput } from './getTicks';
+import { defaultCartesianAxisProps } from './CartesianAxis';
+import { useChartHeight, useChartWidth, useOffsetInternal } from '../context/chartLayoutContext';
+import { AxisId } from '../state/cartesianAxisSlice';
+import {
+	selectAxisPropsNeededForCartesianGridTicksGenerator,
+} from '../state/selectors/axisSelectors';
+import { useAppSelector } from '../state/hooks';
+import { useIsPanorama } from '../context/PanoramaContext';
+import { RequiresDefaultProps, resolveDefaultProps } from '../util/resolveDefaultProps';
+import { svgPropertiesNoEvents } from '../util/svgPropertiesNoEvents';
+import { isPositiveNumber } from '../util/isWellBehavedNumber';
+import { ZIndexable, ZIndexLayer } from '../zIndex/ZIndexLayer';
+import { DefaultZIndexes } from '../zIndex/DefaultZIndexes';
+
+/**
+ * The <CartesianGrid horizontal
+ */
+export type GridLineTypeFunctionProps =
+	Omit<LineItemProps, 'key'> & {
+		// React does not pass the key through when calling cloneElement - so it might be undefined when cloning
+		key: LineItemProps['key'] | undefined;
+		// offset is not present in LineItemProps, but it is read from context and then passed to the GridLineType function and element
+		offset: ChartOffsetInternal;
+	};
+
+export type AxisPropsForCartesianGridTicksGeneration =
+	AxisPropsNeededForTicksGenerator & Omit<GetTicksInput, 'ticks' | 'viewBox'>;
+
+type GridLineType =
+	| SVGProps<SVGLineElement>
+	| ReactElement<SVGElement>
+	| ((props: GridLineTypeFunctionProps) => ReactElement<SVGElement>)
+	| boolean;
+
+export type HorizontalCoordinatesGenerator =
+	(props: {
+		yAxis: AxisPropsForCartesianGridTicksGeneration | undefined;
+		width: number;
+		height: number;
+		offset: ChartOffsetInternal;
+	}, syncWithTicks: boolean) => number[];
+
+export type VerticalCoordinatesGenerator =
+	(props: {
+		xAxis: AxisPropsForCartesianGridTicksGeneration | undefined;
+		width: number;
+		height: number;
+		offset: ChartOffsetInternal;
+	}, syncWithTicks: boolean) => number[];
+
+interface CartesianGridProps extends ZIndexable {
+	/**
+ * The width of grid. If undefined, covers the full width of the chart plot area.
+ */
+	width?: number;
+	/**
+ * The height of grid. If undefined, covers the full height of the chart plot area.
+ */
+	height?: number;
+	/**
+ * A function that generates the y-coordinates of all horizontal lines.
+ *
+ * @see {@link https://codesandbox.io/p/sandbox/cartesian-grid-with-coordinate-generators-my38cg?file=%2Fsrc%2FApp.tsx Cartesian grid with coordinate generators}
+ */
+	horizontalCoordinatesGenerator?: HorizontalCoordinatesGenerator;
+	/**
+ * A function that generates the x-coordinates of all vertical lines.
+ *
+ * @see {@link https://codesandbox.io/p/sandbox/cartesian-grid-with-coordinate-generators-my38cg?file=%2Fsrc%2FApp.tsx Cartesian grid with coordinate generators}
+ */
+	verticalCoordinatesGenerator?: VerticalCoordinatesGenerator;
+	/**
+ * The x-coordinate of grid.
+ * If left undefined, it will be computed from the chart's offset and margins.
+ */
+	x?: number;
+	/**
+ * The y-coordinate of grid.
+ * If left undefined, it will be computed from the chart's offset and margins.
+ */
+	y?: number;
+	/**
+ * If set false, no horizontal grid lines will be drawn.
+ *
+ * @defaultValue true
+ */
+	horizontal?: GridLineType;
+	/**
+ * If set false, no vertical grid lines will be drawn.
+ *
+ * @defaultValue true
+ */
+	vertical?: GridLineType;
+	/**
+ * Array of coordinates in pixels where to draw horizontal grid lines.
+ * Has priority over syncWithTicks and horizontalValues.
+ *
+ * @defaultValue []
+ */
+	horizontalPoints?: number[];
+	/**
+ * Array of coordinates in pixels where to draw vertical grid lines.
+ * Has priority over syncWithTicks and verticalValues.
+ *
+ * @defaultValue []
+ */
+	verticalPoints?: number[];
+	/**
+ * The background color used to fill the space between grid lines
+ *
+ * @defaultValue none
+ * @example <CartesianGrid fill="red" />
+ * @example <CartesianGrid fill="#ccc" />
+ */
+	fill?: string;
+	/**
+ * The opacity of the background used to fill the space between grid lines
+ *
+ * @example <CartesianGrid fill="red" fillOpacity={0.6} />
+ */
+	fillOpacity?: number | string;
+	/**
+ * Defines background color of stripes.
+ *
+ * The values from this array will be passed in as the `fill` property in a `rect` SVG element.
+ * For possible values see: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill#rect
+ *
+ * In case there are more stripes than colors, the colors will start from beginning.
+ * So for example: verticalFill['yellow', 'black'] produces a pattern of yellow|black|yellow|black
+ *
+ * If this is undefined, or an empty array, then there is no background fill.
+ * Note: Grid lines will be rendered above these background stripes.
+ *
+ * @defaultValue []
+ */
+	verticalFill?: string[];
+	/**
+ * Defines background color of stripes.
+ *
+ * The values from this array will be passed in as the `fill` property in a `rect` SVG element.
+ * For possible values see: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill#rect
+ *
+ * In case there are more stripes than colors, the colors will start from beginning.
+ * So for example: horizontalFill['yellow', 'black'] produces a pattern of yellow|black|yellow|black
+ *
+ * If this is undefined, or an empty array, then there is no background fill.
+ * Note: Grid lines will be rendered above these background stripes.
+ *
+ * @defaultValue []
+ */
+	horizontalFill?: string[];
+	/**
+ * If true, only the lines that correspond to the axes ticks values will be drawn.
+ * If false, extra lines could be added for each axis (at min and max coordinates), if there will not such ticks.
+ * horizontalPoints, verticalPoints, horizontalValues, verticalValues have priority over syncWithTicks.
+ *
+ * @defaultValue false
+ */
+	syncWithTicks?: boolean;
+	/**
+ * Array of values, where horizontal lines will be drawn. Numbers or strings, in dependence on axis type.
+ * Has priority over syncWithTicks but not over horizontalPoints.
+ */
+	horizontalValues?: number[] | string[];
+	/**
+ * Array of values, where vertical lines will be drawn. Numbers or strings, in dependence on axis type.
+ * Has priority over syncWithTicks but not over verticalPoints.
+ */
+	verticalValues?: number[] | string[];
+	/**
+ * The pattern of dashes and gaps used to paint the lines of the grid
+ *
+ * @example <CartesianGrid strokeDasharray="3 3" />
+ * @example <CartesianGrid strokeDasharray={[5, 5, 1, 5]} />
+ * @example <CartesianGrid strokeDasharray="5 5 1 5" />
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray stroke-dasharray on MDN}
+ */
+	strokeDasharray?: string | number[];
+	/**
+ * The id of XAxis which is corresponding to the data. Required when there are multiple XAxes.
+ * @defaultValue 0
+ */
+	xAxisId?: AxisId;
+	/**
+ * The id of YAxis which is corresponding to the data. Required when there are multiple YAxes.
+ * @defaultValue 0
+ */
+	yAxisId?: AxisId;
+	/**
+ * @defaultValue -100
+ */
+	zIndex?: number;
+}
+
+type AcceptedSvgProps = Omit<SVGProps<SVGLineElement>, 'offset'>;
+
+export type Props = AcceptedSvgProps & CartesianGridProps;
+
+type CartesianGridInternalProps =
+	AcceptedSvgProps & RequiresDefaultProps<CartesianGridProps, typeof defaultCartesianGridProps> & {
+		// x,y,width,height are not declared directly in default props but are resolved using offset, if undefined
+		x: number;
+		y: number;
+		width: number;
+		height: number;
+	};
+
+const Background = (
+	props: Pick<AcceptedSvgProps, 'fill' | 'fillOpacity' | 'x' | 'y' | 'width' | 'height' | 'ry'>,
+) => {
+	const { fill } = props;
+
+	if (!fill || fill === 'none') {
+		return null;
+	}
+
+	const { fillOpacity, x, y, width, height, ry } = props;
+
+	return <rect
+		x={x}
+		y={y}
+		ry={ry}
+		width={width}
+		height={height}
+		stroke="none"
+		fill={fill}
+		fillOpacity={fillOpacity}
+		className="recharts-cartesian-grid-bg"
+	/>;
+};
+
+type LineItemProps =
+	Props & {
+		offset: ChartOffsetInternal;
+		xAxis: undefined | AxisPropsForCartesianGridTicksGeneration;
+		yAxis: undefined | AxisPropsForCartesianGridTicksGeneration;
+		x1: number;
+		y1: number;
+		x2: number;
+		y2: number;
+		key: string;
+		index: number;
+	};
+
+function LineItem({
+	option,
+	lineItemProps,
+}: {
+	option: GridLineType;
+	lineItemProps: LineItemProps;
+}) {
+	let lineItem;
+
+	if (React.isValidElement(option)) {
+		// @ts-expect-error typescript does not see the props type when cloning an element
+		lineItem = React.cloneElement(option, lineItemProps);
+	} else if (typeof option === 'function') {
+		lineItem = option(lineItemProps);
+	} else {
+		const { x1, y1, x2, y2, key, ...others } = lineItemProps;
+		const { offset: __, ...restOfFilteredProps } = svgPropertiesNoEvents(others) ?? {};
+		lineItem = <line
+			{...restOfFilteredProps}
+			x1={x1}
+			y1={y1}
+			x2={x2}
+			y2={y2}
+			fill="none"
+			key={key}
+		/>;
+	}
+
+	return lineItem;
+}
+
+type GridLinesProps =
+	CartesianGridInternalProps & {
+		offset: GridLineTypeFunctionProps['offset'];
+		xAxis: GridLineTypeFunctionProps['xAxis'];
+		yAxis: GridLineTypeFunctionProps['yAxis'];
+	};
+
+function HorizontalGridLines(props: GridLinesProps) {
+	const { x, width, horizontal = true, horizontalPoints } = props;
+
+	if (!horizontal || !horizontalPoints || !horizontalPoints.length) {
+		return null;
+	}
+
+	const { xAxisId, yAxisId, ...otherLineItemProps } = props;
+
+	const items = horizontalPoints.map((entry, i) => {
+		const lineItemProps: LineItemProps = {
+			...otherLineItemProps,
+			x1: x,
+			y1: entry,
+			x2: x + width,
+			y2: entry,
+			key: `line-${i}`,
+			index: i,
+		};
+
+		return <LineItem key={`line-${i}`} option={horizontal} lineItemProps={lineItemProps} />;
+	});
+
+	return <g className="recharts-cartesian-grid-horizontal">{items}</g>;
+}
+
+function VerticalGridLines(props: GridLinesProps) {
+	const { y, height, vertical = true, verticalPoints } = props;
+
+	if (!vertical || !verticalPoints || !verticalPoints.length) {
+		return null;
+	}
+
+	const { xAxisId, yAxisId, ...otherLineItemProps } = props;
+
+	const items = verticalPoints.map((entry, i) => {
+		const lineItemProps: LineItemProps = {
+			...otherLineItemProps,
+			x1: entry,
+			y1: y,
+			x2: entry,
+			y2: y + height,
+			key: `line-${i}`,
+			index: i,
+		};
+
+		return <LineItem option={vertical} lineItemProps={lineItemProps} key={`line-${i}`} />;
+	});
+
+	return <g className="recharts-cartesian-grid-vertical">{items}</g>;
+}
+
+function HorizontalStripes(props: CartesianGridInternalProps) {
+	const {
+		horizontalFill,
+		fillOpacity,
+		x,
+		y,
+		width,
+		height,
+		horizontalPoints,
+		horizontal = true,
+	} = props;
+	if (!horizontal || !horizontalFill || !horizontalFill.length || horizontalPoints == null) {
+		return null;
+	}
+
+	const roundedSortedHorizontalPoints = horizontalPoints.map((e) => Math.round(e + y - y)).sort(
+		(a, b) => a - b,
+	);
+	// Why is this condition `!==` instead of `<=` ?
+	if (y !== roundedSortedHorizontalPoints[0]) {
+		roundedSortedHorizontalPoints.unshift(y);
+	}
+
+	const items = roundedSortedHorizontalPoints.map((entry, i) => {
+		// Why do we strip only the last stripe if it is invisible, and not all invisible stripes?
+		const nextPoint = roundedSortedHorizontalPoints[i + 1];
+		const lastStripe = nextPoint == null;
+		const lineHeight = lastStripe ? y + height - entry : nextPoint - entry;
+		if (lineHeight <= 0) {
+			return null;
+		}
+		const colorIndex = i % horizontalFill.length;
+		return <rect
+			key={`react-${i}`}
+			y={entry}
+			x={x}
+			height={lineHeight}
+			width={width}
+			stroke="none"
+			fill={horizontalFill[colorIndex]}
+			fillOpacity={fillOpacity}
+			className="recharts-cartesian-grid-bg"
+		/>;
+	});
+
+	return <g className="recharts-cartesian-gridstripes-horizontal">{items}</g>;
+}
+
+function VerticalStripes(props: CartesianGridInternalProps) {
+	const { vertical = true, verticalFill, fillOpacity, x, y, width, height, verticalPoints } = props;
+	if (!vertical || !verticalFill || !verticalFill.length || verticalPoints == null) {
+		return null;
+	}
+
+	const roundedSortedVerticalPoints = verticalPoints.map((e) => Math.round(e + x - x)).sort(
+		(a, b) => a - b,
+	);
+
+	if (x !== roundedSortedVerticalPoints[0]) {
+		roundedSortedVerticalPoints.unshift(x);
+	}
+
+	const items = roundedSortedVerticalPoints.map((entry, i) => {
+		const nextPoint = roundedSortedVerticalPoints[i + 1];
+		const lastStripe = nextPoint == null;
+		const lineWidth = lastStripe ? x + width - entry : nextPoint - entry;
+
+		if (lineWidth <= 0) {
+			return null;
+		}
+		const colorIndex = i % verticalFill.length;
+		return <rect
+			key={`react-${i}`}
+			x={entry}
+			y={y}
+			width={lineWidth}
+			height={height}
+			stroke="none"
+			fill={verticalFill[colorIndex]}
+			fillOpacity={fillOpacity}
+			className="recharts-cartesian-grid-bg"
+		/>;
+	});
+
+	return <g className="recharts-cartesian-gridstripes-vertical">{items}</g>;
+}
+
+const defaultVerticalCoordinatesGenerator: VerticalCoordinatesGenerator = (
+	{ xAxis, width, height, offset },
+	syncWithTicks,
+) => getCoordinatesOfGrid(
+	getTicks({
+		...defaultCartesianAxisProps,
+		...xAxis,
+		ticks: getTicksOfAxis(xAxis, true),
+		viewBox: { x: 0, y: 0, width, height },
+	}),
+	offset.left,
+	offset.left + offset.width,
+	syncWithTicks,
+);
+
+const defaultHorizontalCoordinatesGenerator: HorizontalCoordinatesGenerator = (
+	{ yAxis, width, height, offset },
+	syncWithTicks,
+) => getCoordinatesOfGrid(
+	getTicks({
+		...defaultCartesianAxisProps,
+		...yAxis,
+		ticks: getTicksOfAxis(yAxis, true),
+		viewBox: { x: 0, y: 0, width, height },
+	}),
+	offset.top,
+	offset.top + offset.height,
+	syncWithTicks,
+);
+
+export const defaultCartesianGridProps = {
+	horizontal: true,
+	vertical: true,
+	// The ordinates of horizontal grid lines
+	horizontalPoints: [],
+	// The abscissas of vertical grid lines
+	verticalPoints: [],
+
+	stroke: '#ccc',
+	fill: 'none',
+	// The fill of colors of grid lines
+	verticalFill: [],
+	horizontalFill: [],
+	xAxisId: 0,
+	yAxisId: 0,
+	syncWithTicks: false,
+	zIndex: DefaultZIndexes.grid,
+} as const satisfies Partial<Props>;
+
+/**
+ * Renders background grid with lines and fill colors in a Cartesian chart.
+ *
+ * @consumes CartesianChartContext
+ */
+export function CartesianGrid(props: Props) {
+	const chartWidth = useChartWidth();
+	const chartHeight = useChartHeight();
+	const offset = useOffsetInternal();
+	const propsIncludingDefaults: CartesianGridInternalProps = {
+		...resolveDefaultProps(props, defaultCartesianGridProps),
+		x: isNumber(props.x) ? props.x : offset.left,
+		y: isNumber(props.y) ? props.y : offset.top,
+		width: isNumber(props.width) ? props.width : offset.width,
+		height: isNumber(props.height) ? props.height : offset.height,
+	};
+
+	const {
+		xAxisId,
+		yAxisId,
+		x,
+		y,
+		width,
+		height,
+		syncWithTicks,
+		horizontalValues,
+		verticalValues,
+	} = propsIncludingDefaults;
+
+	const isPanorama = useIsPanorama();
+	const xAxis: AxisPropsForCartesianGridTicksGeneration | undefined = useAppSelector(
+		(state) => selectAxisPropsNeededForCartesianGridTicksGenerator(
+			state,
+			'xAxis',
+			xAxisId,
+			isPanorama,
+		),
+	);
+	const yAxis: AxisPropsForCartesianGridTicksGeneration | undefined = useAppSelector(
+		(state) => selectAxisPropsNeededForCartesianGridTicksGenerator(
+			state,
+			'yAxis',
+			yAxisId,
+			isPanorama,
+		),
+	);
+
+	if (!isPositiveNumber(width) || !isPositiveNumber(height) || !isNumber(x) || !isNumber(y)) {
+		return null;
+	}
+
+	/*
+ * verticalCoordinatesGenerator and horizontalCoordinatesGenerator are defined
+ * outside the propsIncludingDefaults because they were never part of the original props
+ * and they were never passed as a prop down to horizontal/vertical custom elements.
+ * If we add these two to propsIncludingDefaults then we are changing public API.
+ * Not a bad thing per se but also not necessary.
+ */
+	const verticalCoordinatesGenerator =
+		propsIncludingDefaults.verticalCoordinatesGenerator || defaultVerticalCoordinatesGenerator;
+	const horizontalCoordinatesGenerator =
+		propsIncludingDefaults.horizontalCoordinatesGenerator || defaultHorizontalCoordinatesGenerator;
+
+	let { horizontalPoints, verticalPoints } = propsIncludingDefaults;
+
+	// No horizontal points are specified
+	if (
+		(!horizontalPoints || !horizontalPoints.length) &&
+			typeof horizontalCoordinatesGenerator === 'function'
+	) {
+		const isHorizontalValues = horizontalValues && horizontalValues.length;
+
+		const generatorResult = horizontalCoordinatesGenerator(
+			{
+				yAxis: yAxis
+					? {
+							...yAxis,
+							ticks: isHorizontalValues ? horizontalValues : yAxis.ticks,
+						}
+					: undefined,
+				width: chartWidth ?? width,
+				height: chartHeight ?? height,
+				offset,
+			},
+			isHorizontalValues ? true : syncWithTicks,
+		);
+
+		warn(
+			Array.isArray(generatorResult),
+			`horizontalCoordinatesGenerator should return Array but instead it returned [${typeof generatorResult}]`,
+		);
+		if (Array.isArray(generatorResult)) {
+			horizontalPoints = generatorResult;
+		}
+	}
+
+	// No vertical points are specified
+	if (
+		(!verticalPoints || !verticalPoints.length) &&
+			typeof verticalCoordinatesGenerator === 'function'
+	) {
+		const isVerticalValues = verticalValues && verticalValues.length;
+		const generatorResult = verticalCoordinatesGenerator(
+			{
+				xAxis: xAxis
+					? {
+							...xAxis,
+							ticks: isVerticalValues ? verticalValues : xAxis.ticks,
+						}
+					: undefined,
+				width: chartWidth ?? width,
+				height: chartHeight ?? height,
+				offset,
+			},
+			isVerticalValues ? true : syncWithTicks,
+		);
+		warn(
+			Array.isArray(generatorResult),
+			`verticalCoordinatesGenerator should return Array but instead it returned [${typeof generatorResult}]`,
+		);
+		if (Array.isArray(generatorResult)) {
+			verticalPoints = generatorResult;
+		}
+	}
+
+	return <ZIndexLayer zIndex={propsIncludingDefaults.zIndex}>
+		<g className="recharts-cartesian-grid">
+			<Background
+				fill={propsIncludingDefaults.fill}
+				fillOpacity={propsIncludingDefaults.fillOpacity}
+				x={propsIncludingDefaults.x}
+				y={propsIncludingDefaults.y}
+				width={propsIncludingDefaults.width}
+				height={propsIncludingDefaults.height}
+				ry={propsIncludingDefaults.ry}
+			/>
+
+			<HorizontalStripes {...propsIncludingDefaults} horizontalPoints={horizontalPoints} />
+			<VerticalStripes {...propsIncludingDefaults} verticalPoints={verticalPoints} />
+
+			<HorizontalGridLines
+				{...propsIncludingDefaults}
+				offset={offset}
+				horizontalPoints={horizontalPoints}
+				xAxis={xAxis}
+				yAxis={yAxis}
+			/>
+
+			<VerticalGridLines
+				{...propsIncludingDefaults}
+				offset={offset}
+				verticalPoints={verticalPoints}
+				xAxis={xAxis}
+				yAxis={yAxis}
+			/>
+		</g>
+	</ZIndexLayer>;
+}
+
+CartesianGrid.displayName = 'CartesianGrid';