@octanejs/recharts 0.1.16 → 0.1.17

package/src/cartesian/CartesianGrid.tsrx.d.ts

@@ -0,0 +1,219 @@
+import * as React from 'octane';
+import { ReactElement, SVGProps } from 'octane';
+import { ChartOffsetInternal } from '../util/types';
+import { AxisPropsNeededForTicksGenerator } from '../util/ChartUtils';
+import { GetTicksInput } from './getTicks';
+import { AxisId } from '../state/cartesianAxisSlice';
+import { ZIndexable } from '../zIndex/ZIndexLayer';
+/**
+ * The <CartesianGrid horizontal
+ */
+export type GridLineTypeFunctionProps = Omit<LineItemProps, 'key'> & {
+	key: LineItemProps['key'] | undefined;
+	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 LineItemProps = Props & {
+	offset: ChartOffsetInternal;
+	xAxis: undefined | AxisPropsForCartesianGridTicksGeneration;
+	yAxis: undefined | AxisPropsForCartesianGridTicksGeneration;
+	x1: number;
+	y1: number;
+	x2: number;
+	y2: number;
+	key: string;
+	index: number;
+};
+export declare const defaultCartesianGridProps: {
+	readonly horizontal: true;
+	readonly vertical: true;
+	readonly horizontalPoints: [];
+	readonly verticalPoints: [];
+	readonly stroke: '#ccc';
+	readonly fill: 'none';
+	readonly verticalFill: [];
+	readonly horizontalFill: [];
+	readonly xAxisId: 0;
+	readonly yAxisId: 0;
+	readonly syncWithTicks: false;
+	readonly zIndex: -100;
+};
+/**
+ * Renders background grid with lines and fill colors in a Cartesian chart.
+ *
+ * @consumes CartesianChartContext
+ */
+export declare function CartesianGrid(props: Props): React.JSX.Element | null;
+export declare namespace CartesianGrid {
+	var displayName: string;
+}
+export {};

package/src/cartesian/ErrorBar.tsrx

@@ -0,0 +1,322 @@
+/**
+ * @fileOverview Render a group of error bar
+ */
+import * as React from 'octane';
+import { SVGProps } from 'octane';
+import { Layer } from '../container/Layer';
+import { EasingInput, DataKey, RectangleCoordinate } from '../util/types';
+import { BarRectangleItem } from './Bar';
+import { LinePointItem } from './Line';
+import { ScatterPointItem } from './Scatter';
+import { ReportErrorBarSettings, useErrorBarContext } from '../context/ErrorBarContext';
+import { useXAxis, useYAxis } from '../hooks';
+import { resolveDefaultProps } from '../util/resolveDefaultProps';
+import { svgPropertiesNoEvents } from '../util/svgPropertiesNoEvents';
+import { useChartLayout } from '../context/chartLayoutContext';
+import { CSSTransitionAnimate, extractCssEasing } from '../animation/CSSTransitionAnimate';
+import { ZIndexable, ZIndexLayer } from '../zIndex/ZIndexLayer';
+import { DefaultZIndexes } from '../zIndex/DefaultZIndexes';
+
+export interface ErrorBarDataItem {
+	x: number | undefined;
+	y: number | undefined;
+	value: number;
+	errorVal?: number[] | number;
+}
+
+/**
+ * So usually the direction is decided by the chart layout.
+ * Horizontal layout means error bars are vertical means direction=y
+ * Vertical layout means error bars are horizontal means direction=x
+ *
+ * Except! In Scatter chart, error bars can go both ways.
+ *
+ * So this property is only ever used in Scatter chart, and ignored elsewhere.
+ */
+export type ErrorBarDirection = 'x' | 'y';
+
+export type ErrorBarDataPointFormatter<
+	T extends BarRectangleItem | LinePointItem | ScatterPointItem,
+> =
+	(entry: T, dataKey: DataKey<
+		T,
+		number[] | number
+	>, direction: ErrorBarDirection) => ErrorBarDataItem;
+
+/**
+ * External ErrorBar props, visible for users of the library
+ */
+interface ErrorBarProps<DataPointType = any, DataValueType = any> extends ZIndexable {
+	/**
+ * Decides how to extract the value of this ErrorBar from the data:
+ * - `string`: the name of the field in the data object;
+ * - `number`: the index of the field in the data;
+ * - `function`: a function that receives the data object and returns the value of this ErrorBar.
+ *
+ * The error values can be a single value for symmetric error bars;
+ * or an array of a lower and upper error value for asymmetric error bars.
+ */
+	dataKey: DataKey<DataPointType, DataValueType>;
+	/**
+ * Width of the error bar ends (the serifs) in pixels.
+ * This is not the total width of the error bar, but just the width of the little lines at the ends.
+ *
+ * The total width of the error bar is determined by the data value plus/minus the error value.
+ *
+ * @defaultValue 5
+ */
+	width?: number;
+	/**
+ * Direction of the error bar. Usually determined by chart layout, except in Scatter chart.
+ * In Scatter chart, "x" means horizontal error bars, "y" means vertical error bars.
+ */
+	direction?: ErrorBarDirection;
+	/**
+ * @defaultValue true
+ */
+	isAnimationActive?: boolean;
+	/**
+ * @defaultValue 0
+ */
+	animationBegin?: number;
+	/**
+ * @defaultValue 400
+ */
+	animationDuration?: number;
+	/**
+ * @defaultValue ease-in-out
+ */
+	animationEasing?: EasingInput;
+	/**
+ * The width of the stroke
+ */
+	strokeWidth?: number | string;
+	/**
+ * The stroke color. If "none", no line will be drawn.
+ *
+ * @defaultValue black
+ */
+	stroke?: string;
+	/**
+ * @defaultValue 400
+ */
+	zIndex?: number;
+}
+
+export type Props = SVGProps<SVGLineElement> & ErrorBarProps;
+
+/**
+ * Props after defaults, and required props have been applied.
+ */
+type ErrorBarInternalProps =
+	SVGProps<SVGLineElement> & {
+		dataKey: DataKey<any>;
+		/** the width of the error bar ends */
+		width: number;
+		/**
+ * Only used for ScatterChart with error bars in two directions.
+ * Only accepts a value of "x" or "y" and makes the error bars lie in that direction.
+ */
+		direction: ErrorBarDirection;
+		isAnimationActive: boolean;
+		animationBegin: number;
+		animationDuration: number;
+		animationEasing: EasingInput;
+	};
+
+function ErrorBarImpl(props: ErrorBarInternalProps) {
+	const {
+		direction,
+		width,
+		dataKey,
+		isAnimationActive,
+		animationBegin,
+		animationDuration,
+		animationEasing,
+		...others
+	} = props;
+	const svgProps = svgPropertiesNoEvents(others);
+
+	const { data, dataPointFormatter, xAxisId, yAxisId, errorBarOffset: offset } =
+		useErrorBarContext();
+
+	const xAxis = useXAxis(xAxisId);
+	const yAxis = useYAxis(yAxisId);
+
+	if (xAxis?.scale == null || yAxis?.scale == null || data == null) {
+		return null;
+	}
+
+	// ErrorBar requires type number XAxis, why?
+	if (direction === 'x' && xAxis.type !== 'number') {
+		return null;
+	}
+
+	const errorBars = data.map((entry: any, dataIndex: number) => {
+		const { x, y, value, errorVal } = dataPointFormatter(entry, dataKey, direction);
+
+		if (errorVal == null || x == null || y == null) {
+			return null;
+		}
+
+		const lineCoordinates: Array<RectangleCoordinate> = [];
+		let lowBound: number, highBound: number;
+
+		if (Array.isArray(errorVal)) {
+			const [low, high] = errorVal;
+			if (low == null || high == null) {
+				return null;
+			}
+			lowBound = low;
+			highBound = high;
+		} else {
+			lowBound = highBound = errorVal;
+		}
+
+		if (direction === 'x') {
+			// error bar for horizontal charts, the y is fixed, x is a range value
+			const { scale } = xAxis;
+
+			const yMid = y + offset;
+			const yMin = yMid + width;
+			const yMax = yMid - width;
+
+			const xMin = scale.map(value - lowBound);
+			const xMax = scale.map(value + highBound);
+
+			if (xMin != null && xMax != null) {
+				// the right line of |--|
+				lineCoordinates.push({ x1: xMax, y1: yMin, x2: xMax, y2: yMax });
+				// the middle line of |--|
+				lineCoordinates.push({ x1: xMin, y1: yMid, x2: xMax, y2: yMid });
+				// the left line of |--|
+				lineCoordinates.push({ x1: xMin, y1: yMin, x2: xMin, y2: yMax });
+			}
+		} else if (direction === 'y') {
+			// error bar for horizontal charts, the x is fixed, y is a range value
+			const { scale } = yAxis;
+
+			const xMid = x + offset;
+			const xMin = xMid - width;
+			const xMax = xMid + width;
+
+			const yMin = scale.map(value - lowBound);
+			const yMax = scale.map(value + highBound);
+
+			if (yMin != null && yMax != null) {
+				// the top line
+				lineCoordinates.push({ x1: xMin, y1: yMax, x2: xMax, y2: yMax });
+				// the middle line
+				lineCoordinates.push({ x1: xMid, y1: yMin, x2: xMid, y2: yMax });
+				// the bottom line
+				lineCoordinates.push({ x1: xMin, y1: yMin, x2: xMax, y2: yMin });
+			}
+		}
+
+		const scaleDirection: string =
+			direction === 'x' ? 'scaleX' : 'scaleY';
+
+		const transformOrigin =
+			direction === 'x' ? `${x}px ${y + offset}px` : `${x + offset}px ${y}px`;
+
+		return <Layer
+			className="recharts-errorBar"
+			key={`bar-${x}-${y}-${value}-${dataIndex}`}
+			{...svgProps}
+		>{lineCoordinates.map((c, lineIndex) => {
+			const lineStyle = isAnimationActive ? { transformOrigin } : undefined;
+			return <CSSTransitionAnimate
+				animationId={`error-bar-${direction}_${c.x1}-${c.x2}-${c.y1}-${c.y2}`}
+				from={`${scaleDirection}(0)`}
+				to={`${scaleDirection}(1)`}
+				attributeName="transform"
+				begin={animationBegin}
+				easing={extractCssEasing(animationEasing)}
+				isActive={isAnimationActive}
+				duration={animationDuration}
+				key={`errorbar-${dataIndex}-${c.x1}-${c.y1}-${c.x2}-${c.y2}-${lineIndex}`}
+			>
+				{(style) => <line {...c} style={{ ...lineStyle, ...style }} />}
+			</CSSTransitionAnimate>;
+		})}</Layer>;
+	});
+
+	return <Layer className="recharts-errorBars">{errorBars}</Layer>;
+}
+
+function useErrorBarDirection(
+	directionFromProps: ErrorBarDirection | undefined,
+): ErrorBarDirection {
+	const layout = useChartLayout();
+	if (directionFromProps != null) {
+		return directionFromProps;
+	}
+	if (layout != null) {
+		return layout === 'horizontal' ? 'y' : 'x';
+	}
+	return 'x';
+}
+
+export const errorBarDefaultProps = {
+	stroke: 'black',
+	strokeWidth: 1.5,
+	width: 5,
+	offset: 0,
+	isAnimationActive: true,
+	animationBegin: 0,
+	animationDuration: 400,
+	animationEasing: 'ease-in-out',
+	zIndex: DefaultZIndexes.line,
+} as const satisfies Partial<Props>;
+
+/**
+ * ErrorBar renders whiskers to represent error margins on a chart.
+ *
+ * It must be a child of a graphical element.
+ *
+ * ErrorBar expects data in one of the following forms:
+ * - Symmetric error bars: a single error value representing both lower and upper bounds.
+ * - Asymmetric error bars: an array of two values representing lower and upper bounds separately. First value is the lower bound, second value is the upper bound.
+ *
+ * The values provided are relative to the main data value.
+ * For example, if the main data value is 10 and the error value is 2,
+ * the error bar will extend from 8 to 12 for symmetric error bars.
+ *
+ * In other words, what ErrorBar will render is:
+ * - For symmetric error bars: [value - errorVal, value + errorVal]
+ * - For asymmetric error bars: [value - errorVal[0], value + errorVal[1]]
+ *
+ * In stacked or ranged Bar charts, ErrorBar will use the higher data value
+ * as the reference point for calculating the error bar positions.
+ *
+ * @consumes ErrorBarContext
+ */
+export function ErrorBar(outsideProps: Props) {
+	const realDirection: ErrorBarDirection = useErrorBarDirection(outsideProps.direction);
+	const props = resolveDefaultProps(outsideProps, errorBarDefaultProps);
+	const {
+		width,
+		isAnimationActive,
+		animationBegin,
+		animationDuration,
+		animationEasing,
+		zIndex,
+	} = props;
+
+	return <>
+		<ReportErrorBarSettings dataKey={props.dataKey} direction={realDirection} />
+		<ZIndexLayer zIndex={zIndex}>
+			<ErrorBarImpl
+				{...props}
+				direction={realDirection}
+				width={width}
+				isAnimationActive={isAnimationActive}
+				animationBegin={animationBegin}
+				animationDuration={animationDuration}
+				animationEasing={animationEasing}
+			/>
+		</ZIndexLayer>
+	</>;
+}
+
+ErrorBar.displayName = 'ErrorBar';

package/src/cartesian/ErrorBar.tsrx.d.ts

@@ -0,0 +1,131 @@
+/**
+ * @fileOverview Render a group of error bar
+ */
+import * as React from 'octane';
+import { SVGProps } from 'octane';
+import { EasingInput, DataKey } from '../util/types';
+import { BarRectangleItem } from './Bar';
+import { LinePointItem } from './Line';
+import { ScatterPointItem } from './Scatter';
+import { ZIndexable } from '../zIndex/ZIndexLayer';
+export interface ErrorBarDataItem {
+	x: number | undefined;
+	y: number | undefined;
+	value: number;
+	errorVal?: number[] | number;
+}
+/**
+ * So usually the direction is decided by the chart layout.
+ * Horizontal layout means error bars are vertical means direction=y
+ * Vertical layout means error bars are horizontal means direction=x
+ *
+ * Except! In Scatter chart, error bars can go both ways.
+ *
+ * So this property is only ever used in Scatter chart, and ignored elsewhere.
+ */
+export type ErrorBarDirection = 'x' | 'y';
+export type ErrorBarDataPointFormatter<
+	T extends BarRectangleItem | LinePointItem | ScatterPointItem,
+> = (
+	entry: T,
+	dataKey: DataKey<T, number[] | number>,
+	direction: ErrorBarDirection,
+) => ErrorBarDataItem;
+/**
+ * External ErrorBar props, visible for users of the library
+ */
+interface ErrorBarProps<DataPointType = any, DataValueType = any> extends ZIndexable {
+	/**
+	 * Decides how to extract the value of this ErrorBar from the data:
+	 * - `string`: the name of the field in the data object;
+	 * - `number`: the index of the field in the data;
+	 * - `function`: a function that receives the data object and returns the value of this ErrorBar.
+	 *
+	 * The error values can be a single value for symmetric error bars;
+	 * or an array of a lower and upper error value for asymmetric error bars.
+	 */
+	dataKey: DataKey<DataPointType, DataValueType>;
+	/**
+	 * Width of the error bar ends (the serifs) in pixels.
+	 * This is not the total width of the error bar, but just the width of the little lines at the ends.
+	 *
+	 * The total width of the error bar is determined by the data value plus/minus the error value.
+	 *
+	 * @defaultValue 5
+	 */
+	width?: number;
+	/**
+	 * Direction of the error bar. Usually determined by chart layout, except in Scatter chart.
+	 * In Scatter chart, "x" means horizontal error bars, "y" means vertical error bars.
+	 */
+	direction?: ErrorBarDirection;
+	/**
+	 * @defaultValue true
+	 */
+	isAnimationActive?: boolean;
+	/**
+	 * @defaultValue 0
+	 */
+	animationBegin?: number;
+	/**
+	 * @defaultValue 400
+	 */
+	animationDuration?: number;
+	/**
+	 * @defaultValue ease-in-out
+	 */
+	animationEasing?: EasingInput;
+	/**
+	 * The width of the stroke
+	 */
+	strokeWidth?: number | string;
+	/**
+	 * The stroke color. If "none", no line will be drawn.
+	 *
+	 * @defaultValue black
+	 */
+	stroke?: string;
+	/**
+	 * @defaultValue 400
+	 */
+	zIndex?: number;
+}
+export type Props = SVGProps<SVGLineElement> & ErrorBarProps;
+export declare const errorBarDefaultProps: {
+	readonly stroke: 'black';
+	readonly strokeWidth: 1.5;
+	readonly width: 5;
+	readonly offset: 0;
+	readonly isAnimationActive: true;
+	readonly animationBegin: 0;
+	readonly animationDuration: 400;
+	readonly animationEasing: 'ease-in-out';
+	readonly zIndex: 400;
+};
+/**
+ * ErrorBar renders whiskers to represent error margins on a chart.
+ *
+ * It must be a child of a graphical element.
+ *
+ * ErrorBar expects data in one of the following forms:
+ * - Symmetric error bars: a single error value representing both lower and upper bounds.
+ * - Asymmetric error bars: an array of two values representing lower and upper bounds separately. First value is the lower bound, second value is the upper bound.
+ *
+ * The values provided are relative to the main data value.
+ * For example, if the main data value is 10 and the error value is 2,
+ * the error bar will extend from 8 to 12 for symmetric error bars.
+ *
+ * In other words, what ErrorBar will render is:
+ * - For symmetric error bars: [value - errorVal, value + errorVal]
+ * - For asymmetric error bars: [value - errorVal[0], value + errorVal[1]]
+ *
+ * In stacked or ranged Bar charts, ErrorBar will use the higher data value
+ * as the reference point for calculating the error bar positions.
+ *
+ * @consumes ErrorBarContext
+ */
+export declare function ErrorBar(outsideProps: Props): React.JSX.Element;
+export declare namespace ErrorBar {
+	var displayName: string;
+}
+export {};