@delacour/react-native-charts 0.1.0-alpha.4

package/src/cartesian/marks/chart-area.tsx

@@ -0,0 +1,83 @@
+import { LinearGradient, Path, vec } from "@shopify/react-native-skia";
+import { type ReactElement, useMemo } from "react";
+import type { ChartAnimation } from "../../animation/animation.types";
+import { useAnimatedPath } from "../../animation/use-animated-path";
+import type { ChartPoint, ChartSegment } from "../../core/chart.types";
+import { buildAreaPath } from "../../core/curve/build-area";
+import type { CurveType } from "../../core/curve/curves";
+import { toSkPath } from "../../skia/build-path";
+import { useChartContext } from "../cartesian-chart.context";
+
+export type ChartAreaProps = {
+	readonly yKey?: string;
+	readonly points?: readonly ChartPoint[];
+	/**
+	 * Stacked segments to draw as a band, from each one's `y0` up to its `y`.
+	 *
+	 * Usually `chart.stacked[key]`. Takes precedence over `yKey` and `points`,
+	 * and a gap in the band closes against `baseline` as a gap in a fill does.
+	 */
+	readonly segments?: readonly ChartSegment[];
+	/** A flat fill. Give this or `gradient`, not both. */
+	readonly color?: string;
+	/** Top-to-bottom stops. Two or more; the last is usually transparent. */
+	readonly gradient?: readonly string[];
+	/** Canvas y the fill closes against — an x on a horizontal chart. Defaults to the plot rect's bottom, or its left. */
+	readonly baseline?: number;
+	readonly curve?: CurveType;
+	readonly connectMissingData?: boolean;
+	readonly opacity?: number;
+	readonly animation?: ChartAnimation;
+};
+
+/**
+ * The region between a series and a baseline.
+ *
+ * The gradient runs the height of the **plot rect**, not of the path's own
+ * bounds. Anchoring it to the path would make the same data fade differently
+ * as the domain changed, so two charts side by side would disagree about what
+ * a colour meant.
+ */
+export function ChartArea({
+	yKey,
+	points,
+	segments,
+	color,
+	gradient,
+	baseline,
+	curve,
+	connectMissingData,
+	opacity,
+	animation,
+}: ChartAreaProps): ReactElement {
+	const chart = useChartContext();
+	const series = segments ?? points ?? (yKey === undefined ? [] : (chart.points[yKey] ?? []));
+	const { orientation } = chart;
+	const floor = baseline ?? (orientation === "horizontal" ? chart.bounds.left : chart.bounds.bottom);
+
+	const path = useMemo(
+		() =>
+			toSkPath(
+				buildAreaPath(series, {
+					baseline: floor,
+					curve: curve ?? chart.curve,
+					connectMissingData,
+					lower: segments?.map((segment) => segment.y0),
+					orientation,
+				})
+			),
+		[series, segments, floor, curve, chart.curve, connectMissingData, orientation]
+	);
+
+	const animated = useAnimatedPath(path, animation ?? chart.animation);
+
+	return (
+		<Path color={gradient ? undefined : color} opacity={opacity} path={animated} style="fill">
+			{gradient === undefined ? null : (
+				<LinearGradient colors={[...gradient]} end={vec(0, chart.bounds.bottom)} start={vec(0, chart.bounds.top)} />
+			)}
+		</Path>
+	);
+}
+
+ChartArea.displayName = "DelacourCharts.ChartArea";

package/src/cartesian/marks/chart-bar-group.tsx

@@ -0,0 +1,132 @@
+import { Path } from "@shopify/react-native-skia";
+import { type ReactElement, useEffect, useMemo } from "react";
+import type { ChartAnimation } from "../../animation/animation.types";
+import { useAnimatedPath } from "../../animation/use-animated-path";
+import type { ChartOrientation, ChartPoint } from "../../core/chart.types";
+import { type Band, groupLayout, resolveBand } from "../../core/geometry/band";
+import { buildBarsPath, resolveBaseline } from "../../core/shape/build-bars";
+import type { CornerRadii } from "../../core/shape/rect-path";
+import { toSkPath } from "../../skia/build-path";
+import { useChartContext } from "../cartesian-chart.context";
+import { categorySpan } from "./chart-bar";
+
+export type ChartBarGroupProps = {
+	/** The series to draw side by side, in order. */
+	readonly yKeys: readonly string[];
+	/** One colour per key, cycled when there are fewer. */
+	readonly colors: readonly string[];
+	/** The fraction of each step left empty between groups. Defaults to 0.2. */
+	readonly betweenGroupPadding?: number;
+	/** The fraction of each bar's slot left empty. Defaults to 0.2. */
+	readonly withinGroupPadding?: number;
+	/** An exact bar width, instead of a fraction of the slot. */
+	readonly barWidth?: number;
+	/** Size groups as if the plot held this many, so charts of different lengths match. */
+	readonly barCount?: number;
+	readonly roundedCorners?: CornerRadii;
+	readonly opacity?: number;
+	readonly animation?: ChartAnimation;
+	/** Reports the resolved step and bar width, for a legend or a label that wants them. */
+	readonly onBarSizeChange?: (band: Band) => void;
+};
+
+/**
+ * Several series as bars side by side within each step.
+ *
+ * Takes `yKeys` rather than child marks because a Skia tree gains nothing
+ * from identity matching: the group has to know how many series there are
+ * before any of them can know its offset, and reading that off children is
+ * the same information arriving later.
+ *
+ * One `<Path>` per series, each with its own animation, so a series that is
+ * added or removed morphs on its own without disturbing its neighbours.
+ */
+export function ChartBarGroup({
+	yKeys,
+	colors,
+	betweenGroupPadding,
+	withinGroupPadding,
+	barWidth,
+	barCount,
+	roundedCorners,
+	opacity,
+	animation,
+	onBarSizeChange,
+}: ChartBarGroupProps): ReactElement {
+	const chart = useChartContext();
+	const { bounds, xPositions, orientation } = chart;
+	const valueScale = orientation === "horizontal" ? chart.xScale : chart.yScale;
+
+	const layout = useMemo(() => {
+		const band = resolveBand({ xPositions, plotWidth: categorySpan(bounds, orientation), barCount });
+		const group = groupLayout({
+			step: band.step,
+			seriesCount: yKeys.length,
+			betweenGroupPadding,
+			withinGroupPadding,
+			barWidth,
+		});
+		return { step: band.step, bandwidth: group.bandwidth, offsets: group.offsets };
+	}, [xPositions, bounds, orientation, barCount, yKeys.length, betweenGroupPadding, withinGroupPadding, barWidth]);
+
+	const baseline = resolveBaseline(valueScale, bounds, orientation);
+
+	useEffect(() => {
+		onBarSizeChange?.({ step: layout.step, bandwidth: layout.bandwidth });
+	}, [layout.step, layout.bandwidth, onBarSizeChange]);
+
+	return (
+		<>
+			{yKeys.map((key, index) => (
+				<GroupedBarSeries
+					animation={animation ?? chart.animation}
+					bandwidth={layout.bandwidth}
+					baseline={baseline}
+					color={colors[index % colors.length] ?? colors[0] ?? "transparent"}
+					key={key}
+					offset={layout.offsets[index] ?? 0}
+					opacity={opacity}
+					orientation={orientation}
+					points={chart.points[key] ?? []}
+					roundedCorners={roundedCorners}
+				/>
+			))}
+		</>
+	);
+}
+
+ChartBarGroup.displayName = "DelacourCharts.ChartBarGroup";
+
+type GroupedBarSeriesProps = {
+	readonly points: readonly ChartPoint[];
+	readonly bandwidth: number;
+	readonly baseline: number;
+	readonly offset: number;
+	readonly orientation: ChartOrientation;
+	readonly roundedCorners?: CornerRadii;
+	readonly color: string;
+	readonly opacity?: number;
+	readonly animation: ChartAnimation;
+};
+
+/** One series of the group. A component of its own so each path owns its hooks. */
+function GroupedBarSeries({
+	points,
+	bandwidth,
+	baseline,
+	offset,
+	orientation,
+	roundedCorners,
+	color,
+	opacity,
+	animation,
+}: GroupedBarSeriesProps): ReactElement {
+	const path = useMemo(
+		() => toSkPath(buildBarsPath(points, { bandwidth, baseline, offset, roundedCorners, orientation })),
+		[points, bandwidth, baseline, offset, roundedCorners, orientation]
+	);
+	const animated = useAnimatedPath(path, animation);
+	return <Path color={color} opacity={opacity} path={animated} style="fill" />;
+}
+
+GroupedBarSeries.displayName = "DelacourCharts.ChartBarGroup.Series";

package/src/cartesian/marks/chart-bar-stack.tsx

@@ -0,0 +1,209 @@
+import { Path } from "@shopify/react-native-skia";
+import { type ReactElement, useMemo } from "react";
+import type { ChartAnimation } from "../../animation/animation.types";
+import { useAnimatedPath } from "../../animation/use-animated-path";
+import type { ChartOrientation, ChartSegment } from "../../core/chart.types";
+import { resolveBand } from "../../core/geometry/band";
+import { barRects, barsPathFromRects, resolveBaseline } from "../../core/shape/build-bars";
+import type { CornerRadii } from "../../core/shape/rect-path";
+import { toSkPath } from "../../skia/build-path";
+import { useChartContext } from "../cartesian-chart.context";
+import { categorySpan } from "./chart-bar";
+
+/** Where one segment sits in its stack, for `barOptions`. */
+export type ChartBarStackSegmentInfo = {
+	readonly seriesIndex: number;
+	readonly datumIndex: number;
+	/** The segment furthest from zero on its side of the axis — the stack's outer end. */
+	readonly isTop: boolean;
+	/** The segment nearest zero on its side of the axis. */
+	readonly isBottom: boolean;
+	/** The first datum. */
+	readonly isStart: boolean;
+	/** The last datum. */
+	readonly isEnd: boolean;
+};
+
+export type ChartBarStackSegmentOptions = {
+	/** `topLeft`/`topRight` are the value end, which for a negative segment is its canvas bottom. */
+	readonly roundedCorners?: CornerRadii;
+};
+
+export type ChartBarStackProps = {
+	/** The series to stack, bottom first. Each must be in the chart's `stackKeys`. */
+	readonly yKeys: readonly string[];
+	/** One colour per key, cycled when there are fewer. */
+	readonly colors: readonly string[];
+	/** The fraction of each step left empty. Defaults to 0.25. */
+	readonly innerPadding?: number;
+	/** An exact bar width, instead of a fraction of the step. */
+	readonly barWidth?: number;
+	/** Size bars as if the plot held this many, so charts of different lengths match. */
+	readonly barCount?: number;
+	/**
+	 * Per-segment options — the way to round only the outermost segment.
+	 *
+	 * Corners are the only per-segment option because a series is one `<Path>`
+	 * node, and a path has one colour and one opacity. Per-datum colour would
+	 * need a node per bar, which is what this design exists to avoid.
+	 */
+	readonly barOptions?: (info: ChartBarStackSegmentInfo) => ChartBarStackSegmentOptions;
+	readonly opacity?: number;
+	readonly animation?: ChartAnimation;
+};
+
+/**
+ * Several series stacked on one another within each step.
+ *
+ * Reads `chart.stacked`, not `chart.points`: the root stacks in data space so
+ * that the y domain covers the totals, and a mark that stacked for itself
+ * would draw past the top of the plot. A key missing from the root's
+ * `stackKeys` has no stacked series and draws nothing.
+ *
+ * One `<Path>` per series, so the segments of one series morph together and
+ * a series can be added or removed without re-keying the others.
+ */
+export function ChartBarStack({
+	yKeys,
+	colors,
+	innerPadding = 0.25,
+	barWidth,
+	barCount,
+	barOptions,
+	opacity,
+	animation,
+}: ChartBarStackProps): ReactElement {
+	const chart = useChartContext();
+	const { bounds, xPositions, stacked, orientation } = chart;
+	const valueScale = orientation === "horizontal" ? chart.xScale : chart.yScale;
+
+	const bandwidth = useMemo(
+		() =>
+			resolveBand({ xPositions, plotWidth: categorySpan(bounds, orientation), innerPadding, barWidth, barCount })
+				.bandwidth,
+		[xPositions, bounds, orientation, innerPadding, barWidth, barCount]
+	);
+	const baseline = resolveBaseline(valueScale, bounds, orientation);
+
+	// Which series is the outer end of each column, on each side of zero. A
+	// null segment is skipped, so the series above a gap is the outer end.
+	const ends = useMemo(() => stackEnds(yKeys.map((key) => stacked[key] ?? [])), [yKeys, stacked]);
+
+	return (
+		<>
+			{yKeys.map((key, seriesIndex) => (
+				<StackedBarSeries
+					animation={animation ?? chart.animation}
+					bandwidth={bandwidth}
+					barOptions={barOptions}
+					baseline={baseline}
+					color={colors[seriesIndex % colors.length] ?? colors[0] ?? "transparent"}
+					ends={ends}
+					key={key}
+					opacity={opacity}
+					orientation={orientation}
+					segments={stacked[key] ?? []}
+					seriesIndex={seriesIndex}
+				/>
+			))}
+		</>
+	);
+}
+
+ChartBarStack.displayName = "DelacourCharts.ChartBarStack";
+
+/** Per datum: the series index nearest and furthest from zero, per sign. */
+type StackEnds = readonly {
+	readonly firstPositive: number;
+	readonly lastPositive: number;
+	readonly firstNegative: number;
+	readonly lastNegative: number;
+}[];
+
+/** Which side of zero a segment lies on, or `null` for a gap. */
+function segmentSign(segment: ChartSegment | undefined): "positive" | "negative" | null {
+	if (segment === undefined || segment.yValue === null || segment.y0Value === null) return null;
+	return segment.yValue < segment.y0Value ? "negative" : "positive";
+}
+
+function stackEnds(series: readonly (readonly ChartSegment[])[]): StackEnds {
+	const length = Math.max(0, ...series.map((segments) => segments.length));
+	const ends: {
+		firstPositive: number;
+		lastPositive: number;
+		firstNegative: number;
+		lastNegative: number;
+	}[] = [];
+	for (let datum = 0; datum < length; datum += 1) {
+		const end = { firstPositive: -1, lastPositive: -1, firstNegative: -1, lastNegative: -1 };
+		series.forEach((segments, index) => {
+			const sign = segmentSign(segments[datum]);
+			if (sign === "negative") {
+				if (end.firstNegative === -1) end.firstNegative = index;
+				end.lastNegative = index;
+			} else if (sign === "positive") {
+				if (end.firstPositive === -1) end.firstPositive = index;
+				end.lastPositive = index;
+			}
+		});
+		ends.push(end);
+	}
+	return ends;
+}
+
+type StackedBarSeriesProps = {
+	readonly segments: readonly ChartSegment[];
+	readonly seriesIndex: number;
+	readonly ends: StackEnds;
+	readonly bandwidth: number;
+	readonly baseline: number;
+	readonly orientation: ChartOrientation;
+	readonly barOptions?: (info: ChartBarStackSegmentInfo) => ChartBarStackSegmentOptions;
+	readonly color: string;
+	readonly opacity?: number;
+	readonly animation: ChartAnimation;
+};
+
+/** One series of the stack. A component of its own so each path owns its hooks. */
+function StackedBarSeries({
+	segments,
+	seriesIndex,
+	ends,
+	bandwidth,
+	baseline,
+	orientation,
+	barOptions,
+	color,
+	opacity,
+	animation,
+}: StackedBarSeriesProps): ReactElement {
+	const path = useMemo(() => {
+		const rects = barRects(segments, { bandwidth, baseline, orientation });
+		const corners = barOptions === undefined ? undefined : rects.map((rect) => barOptions(segmentInfo(rect.index)));
+		return toSkPath(
+			barsPathFromRects(
+				rects,
+				corners?.map((options) => options.roundedCorners),
+				orientation
+			)
+		);
+
+		function segmentInfo(datumIndex: number): ChartBarStackSegmentInfo {
+			const end = ends[datumIndex];
+			const negative = segmentSign(segments[datumIndex]) === "negative";
+			return {
+				seriesIndex,
+				datumIndex,
+				isTop: end !== undefined && (negative ? end.lastNegative : end.lastPositive) === seriesIndex,
+				isBottom: end !== undefined && (negative ? end.firstNegative : end.firstPositive) === seriesIndex,
+				isStart: datumIndex === 0,
+				isEnd: datumIndex === segments.length - 1,
+			};
+		}
+	}, [segments, seriesIndex, ends, bandwidth, baseline, orientation, barOptions]);
+
+	const animated = useAnimatedPath(path, animation);
+	return <Path color={color} opacity={opacity} path={animated} style="fill" />;
+}
+
+StackedBarSeries.displayName = "DelacourCharts.ChartBarStack.Series";

package/src/cartesian/marks/chart-bar.tsx

@@ -0,0 +1,195 @@
+import { Path, type SkFont, Text } from "@shopify/react-native-skia";
+import { type ReactElement, type ReactNode, useEffect, useMemo } from "react";
+import type { ChartAnimation } from "../../animation/animation.types";
+import { useAnimatedPath } from "../../animation/use-animated-path";
+import type { ChartBounds, ChartOrientation, ChartPoint } from "../../core/chart.types";
+import { resolveBand } from "../../core/geometry/band";
+import { categoryDomainCovers } from "../../core/geometry/category-domain";
+import { pickAxisRoles } from "../../core/geometry/chart-layout";
+import { type BarRect, barRects, barsPathFromRects, resolveBaseline } from "../../core/shape/build-bars";
+import type { CornerRadii } from "../../core/shape/rect-path";
+import { type BarLabelPosition, barLabelAnchor } from "../../core/text/bar-label";
+import type { LabelMetrics } from "../../core/text/label-anchor";
+import { toSkPath } from "../../skia/build-path";
+import { fontMetrics, measureLabelWidth } from "../../skia/font";
+import { useChartContext } from "../cartesian-chart.context";
+import type { ChartContextValue } from "../cartesian-chart.types";
+
+export type ChartBarLabels = {
+	/** Defaults to `top` — the value end, which flips below a negative bar. */
+	readonly position?: BarLabelPosition;
+	/** Defaults to the chart's font. Nothing draws while it is `null`. */
+	readonly font?: SkFont | null;
+	readonly color: string;
+	/** Defaults to the value as a string. Return `""` to skip a bar. */
+	readonly formatLabel?: (point: ChartPoint, index: number) => string;
+	/** Space between the bar and the label. */
+	readonly gap?: number;
+	readonly opacity?: number;
+};
+
+export type ChartBarProps = {
+	/** Which series to draw. Read from the chart's context. */
+	readonly yKey?: string;
+	/** The points to draw, when they are not coming from context. */
+	readonly points?: readonly ChartPoint[];
+	readonly color?: string;
+	readonly opacity?: number;
+	/** The fraction of each step left empty. Defaults to 0.2. */
+	readonly innerPadding?: number;
+	/** An exact bar width, instead of a fraction of the step. */
+	readonly barWidth?: number;
+	/** Size bars as if the plot held this many, so charts of different lengths match. */
+	readonly barCount?: number;
+	/** `topLeft`/`topRight` are the value end; a negative bar rounds its bottom instead. */
+	readonly roundedCorners?: CornerRadii;
+	readonly animation?: ChartAnimation;
+	/** A value printed against each bar. */
+	readonly labels?: ChartBarLabels;
+	/** Skia children of the path — a gradient, a shader. */
+	readonly children?: ReactNode;
+};
+
+/**
+ * One bar per datum, standing on zero.
+ *
+ * Every bar in the series is one `<Path>`, and every corner of every bar is a
+ * cubic, so a change of data morphs rather than snaps — see `rectPath`. A gap
+ * is a zero-height bar at the baseline for the same reason.
+ *
+ * The width comes from `resolveBand` against the chart's x positions: there is
+ * no band scale here, so the step is measured. The chart's x domain has to be
+ * padded by half a step each side for the first and last bars to sit inside
+ * the plot; the development-only warning below names the prop that does it.
+ */
+export function ChartBar({
+	yKey,
+	points,
+	color,
+	opacity,
+	innerPadding,
+	barWidth,
+	barCount,
+	roundedCorners,
+	animation,
+	labels,
+	children,
+}: ChartBarProps): ReactElement {
+	const chart = useChartContext();
+	const series = points ?? (yKey === undefined ? [] : (chart.points[yKey] ?? []));
+	const { bounds, xPositions, orientation } = chart;
+	const valueScale = orientation === "horizontal" ? chart.xScale : chart.yScale;
+
+	const rects = useMemo(() => {
+		const band = resolveBand({
+			xPositions,
+			plotWidth: categorySpan(bounds, orientation),
+			innerPadding,
+			barWidth,
+			barCount,
+		});
+		return barRects(series, {
+			bandwidth: band.bandwidth,
+			baseline: resolveBaseline(valueScale, bounds, orientation),
+			orientation,
+		});
+	}, [series, xPositions, bounds, valueScale, orientation, innerPadding, barWidth, barCount]);
+
+	const path = useMemo(
+		() => toSkPath(barsPathFromRects(rects, roundedCorners, orientation)),
+		[rects, roundedCorners, orientation]
+	);
+	const animated = useAnimatedPath(path, animation ?? chart.animation);
+
+	useBarDomainWarning(series, chart);
+
+	return (
+		<>
+			<Path color={color} opacity={opacity} path={animated} style="fill">
+				{children}
+			</Path>
+			{labels === undefined ? null : <BarLabels chart={chart} labels={labels} rects={rects} series={series} />}
+		</>
+	);
+}
+
+ChartBar.displayName = "DelacourCharts.ChartBar";
+
+/** The plot's extent along the category axis — its width, or its height when horizontal. */
+export function categorySpan(bounds: ChartBounds, orientation: ChartOrientation): number {
+	return orientation === "horizontal" ? bounds.bottom - bounds.top : bounds.right - bounds.left;
+}
+
+/**
+ * Warns, in development, when the x domain cannot hold the first or last bar.
+ *
+ * The domain the root measures ends exactly at the outermost data, so a bar
+ * centred there is half off the plot. There is no way for a mark to widen the
+ * domain — the root owns it — so this says which prop to reach for.
+ */
+function useBarDomainWarning(series: readonly ChartPoint[], chart: ChartContextValue): void {
+	const { xStep, orientation } = chart;
+	// The category scale is `yScale` on a horizontal chart; asking by role is
+	// what stopped this warning firing on every horizontal bar.
+	const categoryScale = pickAxisRoles(chart.xScale, chart.yScale, orientation).category;
+
+	useEffect(() => {
+		if (!__DEV__ || categoryDomainCovers(series, categoryScale, xStep.value)) return;
+		console.warn(
+			"[@delacour/react-native-charts] the x domain does not cover the first or last bar, so it is drawn half " +
+				"outside the plot. Pass domainPadding={{ x: 0.5 }} to the chart to pad the domain by half a step each side."
+		);
+	}, [series, categoryScale, xStep.value]);
+}
+
+type BarLabelsProps = {
+	readonly chart: ChartContextValue;
+	readonly labels: ChartBarLabels;
+	readonly rects: readonly BarRect[];
+	readonly series: readonly ChartPoint[];
+};
+
+/** One Skia `<Text>` per bar with a value. Draws nothing while the font is `null`. */
+function BarLabels({ chart, labels, rects, series }: BarLabelsProps): ReactElement | null {
+	const font = labels.font === undefined ? chart.font : labels.font;
+	const metrics: LabelMetrics = labels.font === undefined ? chart.fontMetrics : fontMetrics(labels.font);
+	if (font === null) return null;
+	const position = labels.position ?? "top";
+	const format = labels.formatLabel ?? defaultBarLabel;
+
+	return (
+		<>
+			{rects.map((rect, index) => {
+				const point = series[index];
+				if (point === undefined || point.yValue === null) return null;
+				const text = format(point, index);
+				if (text === "") return null;
+				const anchor = barLabelAnchor({
+					rect,
+					position,
+					width: measureLabelWidth(font, text),
+					metrics,
+					gap: labels.gap,
+					orientation: chart.orientation,
+				});
+				return (
+					<Text
+						color={labels.color}
+						font={font}
+						key={`${index}-${text}`}
+						opacity={labels.opacity}
+						text={text}
+						x={anchor.x}
+						y={anchor.y}
+					/>
+				);
+			})}
+		</>
+	);
+}
+
+BarLabels.displayName = "DelacourCharts.ChartBar.Labels";
+
+function defaultBarLabel(point: ChartPoint): string {
+	return point.yValue === null ? "" : String(point.yValue);
+}