@octanejs/visx 0.1.0

package/src/xychart/utils/combineBarStackData.ts

@@ -0,0 +1,51 @@
+import type { ReactElement } from 'react';
+import type { AxisScale } from '@octanejs/visx/axis';
+import type { CombinedStackData, SeriesProps } from '../types';
+
+/** Returns the value which forms a stack group. */
+export const getStackValue = <XScale extends AxisScale, YScale extends AxisScale>(
+	d: Pick<CombinedStackData<XScale, YScale>, 'stack'>,
+) => d.stack;
+
+/**
+ * Merges `seriesChildren` `props.data` by their `stack` value which
+ * forms the stack grouping (`x` if vertical, `y` if horizontal)
+ * and returns `CombinedStackData[]`.
+ */
+export default function combineBarStackData<
+	XScale extends AxisScale,
+	YScale extends AxisScale,
+	Datum extends object,
+>(
+	seriesChildren: ReactElement<SeriesProps<XScale, YScale, Datum>>[],
+	horizontal?: boolean,
+): CombinedStackData<XScale, YScale>[] {
+	const dataByStackValue = new Map<string, CombinedStackData<XScale, YScale>>();
+
+	seriesChildren.forEach((child) => {
+		const { dataKey, data, xAccessor, yAccessor } = child.props;
+
+		// this should exist but double check
+		if (!xAccessor || !yAccessor) return;
+
+		const [stackFn, valueFn] = horizontal ? [yAccessor, xAccessor] : [xAccessor, yAccessor];
+
+		data.forEach((d) => {
+			const stack = stackFn(d);
+			const numericValue = valueFn(d);
+			const stackKey = String(stack);
+			if (!dataByStackValue.has(stackKey)) {
+				dataByStackValue.set(stackKey, {
+					stack,
+					positiveSum: 0,
+					negativeSum: 0,
+				});
+			}
+			const stackEntry = dataByStackValue.get(stackKey)!;
+			stackEntry[dataKey] = numericValue;
+			stackEntry[numericValue >= 0 ? 'positiveSum' : 'negativeSum'] += numericValue;
+		});
+	});
+
+	return Array.from(dataByStackValue.values());
+}

package/src/xychart/utils/findNearestDatumSingleDimension.ts

@@ -0,0 +1,64 @@
+import type { AxisScale } from '@octanejs/visx/axis';
+import type { ScaleInput } from '@octanejs/visx/scale';
+import { bisector, range as d3Range, bisectLeft } from 'd3-array';
+
+// @TODO make more robust to null/undefined scaled values
+/** Finds the nearest datum in a single direction (x or y) closest to the specified `scaledValue`. */
+export default function findNearestDatumSingleDimension<
+	Scale extends AxisScale,
+	Datum extends object,
+>({
+	scale,
+	accessor,
+	scaledValue,
+	data,
+}: {
+	scale: Scale;
+	accessor: (d: Datum) => ScaleInput<Scale>;
+	scaledValue: number;
+	data: Datum[];
+}) {
+	const coercedScale = scale as AxisScale; // broaden type before type guards below
+
+	let nearestDatum: Datum;
+	let nearestDatumIndex: number;
+	// if scale has .invert(), convert svg coord to nearest data value
+	if ('invert' in coercedScale && typeof coercedScale.invert === 'function') {
+		const bisect = bisector(accessor).left;
+		// find closest data value, then map that to closest datum
+		const dataValue = Number(coercedScale.invert(scaledValue));
+		const index = bisect(data, dataValue);
+		// take the two datum nearest this index, and compute which is closer
+		const nearestDatum0 = data[index - 1];
+		const nearestDatum1 = data[index];
+		nearestDatum =
+			!nearestDatum0 ||
+			Math.abs(dataValue - accessor(nearestDatum0)) > Math.abs(dataValue - accessor(nearestDatum1))
+				? nearestDatum1
+				: nearestDatum0;
+		nearestDatumIndex = nearestDatum === nearestDatum0 ? index - 1 : index;
+	} else if ('step' in coercedScale && typeof coercedScale.step !== 'undefined') {
+		// band scales don't have an invert function but they do have discrete domains
+		// so we manually invert
+		const domain = scale.domain();
+		const range = scale.range().map(Number);
+		const sortedRange = [...range].sort((a, b) => a - b); // bisectLeft assumes sort
+		const rangePoints = d3Range(sortedRange[0], sortedRange[1], coercedScale.step());
+		const domainIndex = bisectLeft(rangePoints, scaledValue);
+		// y-axis scales may have reverse ranges, correct for this
+		const sortedDomain = range[0] < range[1] ? domain : domain.reverse();
+		const domainValue = sortedDomain[domainIndex - 1];
+		const index = data.findIndex((d) => String(accessor(d)) === String(domainValue));
+		nearestDatum = data[index];
+		nearestDatumIndex = index;
+	} else {
+		console.warn('[visx/xychart/findNearestDatum] encountered incompatible scale type, bailing');
+		return null;
+	}
+
+	if (nearestDatum == null || nearestDatumIndex == null) return null;
+
+	const distance = Math.abs(Number(coercedScale(accessor(nearestDatum))) - scaledValue);
+
+	return { datum: nearestDatum, index: nearestDatumIndex, distance };
+}

package/src/xychart/utils/findNearestDatumX.ts

@@ -0,0 +1,34 @@
+import type { AxisScale } from '@octanejs/visx/axis';
+import findNearestDatumSingleDimension from './findNearestDatumSingleDimension';
+import type { NearestDatumArgs, NearestDatumReturnType } from '../types';
+
+export default function findNearestDatumX<
+	XScale extends AxisScale,
+	YScale extends AxisScale,
+	Datum extends object,
+>({
+	xScale: scale,
+	xAccessor: accessor,
+	yScale,
+	yAccessor,
+	point,
+	data,
+}: NearestDatumArgs<XScale, YScale, Datum>): NearestDatumReturnType<Datum> {
+	if (!point) return null;
+
+	const nearestDatum = findNearestDatumSingleDimension<XScale, Datum>({
+		scale,
+		accessor,
+		scaledValue: point.x,
+		data,
+	});
+
+	return nearestDatum
+		? {
+				datum: nearestDatum.datum,
+				index: nearestDatum.index,
+				distanceX: nearestDatum.distance,
+				distanceY: Math.abs(Number(yScale(yAccessor(nearestDatum.datum))) - point.y),
+			}
+		: null;
+}

package/src/xychart/utils/findNearestDatumXY.ts

@@ -0,0 +1,42 @@
+import type { AxisScale } from '@octanejs/visx/axis';
+import { voronoi } from '@octanejs/visx/voronoi';
+import type { NearestDatumArgs, NearestDatumReturnType } from '../types';
+
+/* finds the datum nearest to svgMouseX/Y using a voronoi */
+export default function findNearestDatumXY<
+	XScale extends AxisScale,
+	YScale extends AxisScale,
+	Datum extends object,
+>({
+	width,
+	height,
+	xScale,
+	yScale,
+	xAccessor,
+	yAccessor,
+	point,
+	data,
+}: NearestDatumArgs<XScale, YScale, Datum>): NearestDatumReturnType<Datum> {
+	if (!point) return null;
+
+	const scaledX = (d: Datum) => Number(xScale(xAccessor(d)));
+	const scaledY = (d: Datum) => Number(yScale(yAccessor(d)));
+
+	// Create a voronoi for each datum's x,y coordinate
+	const voronoiInstance = voronoi({
+		x: scaledX,
+		y: scaledY,
+		width,
+		height,
+	});
+
+	const nearestDatum = voronoiInstance(data).find(point.x, point.y);
+
+	if (!nearestDatum) return null;
+
+	const { data: datum, index } = nearestDatum;
+	const distanceX = Math.abs(scaledX(datum) - point.x);
+	const distanceY = Math.abs(scaledY(datum) - point.y);
+
+	return { datum, index, distanceX, distanceY };
+}

package/src/xychart/utils/findNearestDatumY.ts

@@ -0,0 +1,34 @@
+import type { AxisScale } from '@octanejs/visx/axis';
+import findNearestDatumSingleDimension from './findNearestDatumSingleDimension';
+import type { NearestDatumArgs, NearestDatumReturnType } from '../types';
+
+export default function findNearestDatumY<
+	XScale extends AxisScale,
+	YScale extends AxisScale,
+	Datum extends object,
+>({
+	yScale: scale,
+	yAccessor: accessor,
+	xScale,
+	xAccessor,
+	point,
+	data,
+}: NearestDatumArgs<XScale, YScale, Datum>): NearestDatumReturnType<Datum> {
+	if (!point) return null;
+
+	const nearestDatum = findNearestDatumSingleDimension<YScale, Datum>({
+		scale,
+		accessor,
+		scaledValue: point.y,
+		data,
+	});
+
+	return nearestDatum
+		? {
+				datum: nearestDatum.datum,
+				index: nearestDatum.index,
+				distanceY: nearestDatum.distance,
+				distanceX: Math.abs(Number(xScale(xAccessor(nearestDatum.datum))) - point.x),
+			}
+		: null;
+}

package/src/xychart/utils/findNearestGroupDatum.ts

@@ -0,0 +1,50 @@
+import type { PositionScale } from '@octanejs/visx/shape';
+import type { ScaleTypeToD3Scale } from '@octanejs/visx/scale';
+import type { NearestDatumArgs } from '../types';
+import findNearestDatumX from './findNearestDatumX';
+import findNearestDatumY from './findNearestDatumY';
+
+/**
+ * This is a wrapper around findNearestDatumX/Y for BarGroup, accounting for a
+ * Bar's group scale offset (which findNearestDatum does not).
+ */
+export default function findNearestGroupDatum<
+	XScale extends PositionScale,
+	YScale extends PositionScale,
+	Datum extends object,
+>(
+	nearestDatumArgs: NearestDatumArgs<XScale, YScale, Datum>,
+	groupScale: ScaleTypeToD3Scale<string, string>['band'],
+	horizontal?: boolean,
+) {
+	const { dataKey, xAccessor, yAccessor, xScale, yScale, point } = nearestDatumArgs;
+	const datum = (horizontal ? findNearestDatumY : findNearestDatumX)(nearestDatumArgs);
+
+	if (!datum || !point) return null;
+
+	const barGroupOffset = groupScale(dataKey);
+	const barWidth = groupScale.step();
+
+	if (horizontal) {
+		const groupPosition = yScale(yAccessor(datum.datum));
+		const barStart = (groupPosition ?? Infinity) + (barGroupOffset ?? Infinity);
+		const barEnd = barStart + barWidth;
+		const barMiddle = (barStart + barEnd) / 2;
+		const cursorIsOnBar = point.y >= barStart && point.y <= barEnd;
+		return {
+			...datum,
+			distanceX: 0, // we want all group bars to have same X distance so only Y distance matters
+			distanceY: cursorIsOnBar ? 0 : Math.abs(point.y - barMiddle),
+		};
+	}
+	const groupPosition = xScale(xAccessor(datum.datum));
+	const barStart = (groupPosition ?? Infinity) + (barGroupOffset ?? Infinity);
+	const barEnd = barStart + barWidth;
+	const barMiddle = (barStart + barEnd) / 2;
+	const cursorIsOnBar = point.x >= barStart && point.x <= barEnd;
+	return {
+		...datum,
+		distanceY: 0, // we want all group bars to have same Y distance so only X distance matters
+		distanceX: cursorIsOnBar ? 0 : Math.abs(point.x - barMiddle),
+	};
+}

package/src/xychart/utils/findNearestStackDatum.ts

@@ -0,0 +1,44 @@
+import type { AxisScale } from '@octanejs/visx/axis';
+import { getFirstItem, getSecondItem } from '@octanejs/visx/shape';
+import findNearestDatumY from './findNearestDatumY';
+import findNearestDatumX from './findNearestDatumX';
+import type { BarStackDatum, NearestDatumArgs } from '../types';
+
+/**
+ * This is a wrapper around findNearestDatumX/Y for BarStack, accounting for a
+ * Bar's d0 and d1, not just d1 (which findNearestDatum uses). Additionally,
+ * returns the BarSeries original `Datum`, not the `BarStackDatum` so
+ * Tooltip typing is correct.
+ */
+export default function findNearestStackDatum<
+	XScale extends AxisScale,
+	YScale extends AxisScale,
+	Datum extends object,
+>(
+	nearestDatumArgs: NearestDatumArgs<XScale, YScale, BarStackDatum<XScale, YScale>>,
+	seriesData: Datum[],
+	horizontal?: boolean,
+) {
+	const { xScale, yScale, point } = nearestDatumArgs;
+	const datum = (horizontal ? findNearestDatumY : findNearestDatumX)(nearestDatumArgs);
+	const seriesDatum = datum?.index == null ? null : seriesData[datum.index];
+
+	return datum && seriesDatum && point
+		? {
+				index: datum.index,
+				datum: seriesDatum,
+				distanceX: horizontal // if mouse is ON the stack series, set 0 distance
+					? point.x >= Number(xScale(getFirstItem(datum.datum)) ?? Infinity) &&
+						point.x <= Number(xScale(getSecondItem(datum.datum)) ?? -Infinity)
+						? 0
+						: datum.distanceX
+					: datum.distanceX,
+				distanceY: horizontal
+					? datum.distanceY // if mouse is ON the stack series, set 0 distance
+					: point.y <= Number(yScale(getFirstItem(datum.datum)) ?? -Infinity) &&
+						  point.y >= Number(yScale(getSecondItem(datum.datum)) ?? Infinity)
+						? 0
+						: datum.distanceY,
+			}
+		: null;
+}

package/src/xychart/utils/getBarStackRegistryData.ts

@@ -0,0 +1,49 @@
+import type { AxisScale } from '@octanejs/visx/axis';
+import { getFirstItem, getSecondItem } from '@octanejs/visx/shape';
+import { extent } from 'd3-array';
+import type { BarStackData, BarStackDatum, DataRegistryEntry } from '../types';
+
+const getStack = <XScale extends AxisScale, YScale extends AxisScale>(
+	bar: BarStackDatum<XScale, YScale>,
+) => bar?.data?.stack;
+
+// returns average of top + bottom of bar (the middle) as this enables more accurately
+// finding the nearest datum to a FocusEvent (which is based on the middle of the rect bounding box)
+const getNumericValue = <XScale extends AxisScale, YScale extends AxisScale>(
+	bar: BarStackDatum<XScale, YScale>,
+) => (getFirstItem(bar) + getSecondItem(bar)) / 2;
+
+/** Constructs the `DataRegistryEntry`s for a BarStack, using the stacked data. */
+export default function getBarStackRegistryData<XScale extends AxisScale, YScale extends AxisScale>(
+	stackedData: BarStackData<XScale, YScale>,
+	comprehensiveDomain: [number, number],
+	horizontal?: boolean,
+) {
+	const [xAccessor, yAccessor] = horizontal
+		? [getNumericValue, getStack]
+		: [getStack, getNumericValue];
+	return stackedData
+		.map((data, index) => {
+			const entry: DataRegistryEntry<XScale, YScale, BarStackDatum<XScale, YScale>> = {
+				key: data.key,
+				data,
+				xAccessor,
+				yAccessor,
+			};
+
+			// update the numeric domain to account for full data stack
+			// only need to do this for one key
+			if (comprehensiveDomain.length > 0 && index === 0) {
+				if (horizontal) {
+					entry.xScale = (scale) =>
+						scale.domain(extent(scale.domain().concat(comprehensiveDomain))) as typeof scale;
+				} else {
+					entry.yScale = (scale) =>
+						scale.domain(extent(scale.domain().concat(comprehensiveDomain))) as typeof scale;
+				}
+			}
+
+			return entry;
+		})
+		.filter((entry) => entry) as DataRegistryEntry<XScale, YScale, BarStackDatum<XScale, YScale>>[];
+}

package/src/xychart/utils/getChildrenAndGrandchildrenWithProps.ts

@@ -0,0 +1,24 @@
+import type { ReactElement, ReactNode } from 'react';
+import { Children } from 'octane';
+
+/** Returns whether the ReactNode has props (and therefore is an `Element` versus primitive type) */
+function isChildWithProps<P extends object>(child: ReactNode): child is ReactElement<P> {
+	return !!child && typeof child === 'object' && 'props' in child && child.props != null;
+}
+
+/**
+ * Returns children and grandchildren of type ReactNode.
+ * Flattens children one level to support Fragments and Array type children.
+ */
+export default function getChildrenAndGrandchildrenWithProps<P extends object>(
+	children: ReactNode,
+): ReactElement<P>[] {
+	return Children.toArray(children)
+		.flatMap((child) => {
+			if (isChildWithProps(child) && (child.props as any).children) {
+				return (child.props as any).children;
+			}
+			return child;
+		})
+		.filter((child) => isChildWithProps<P>(child)) as unknown as ReactElement<P>[];
+}

package/src/xychart/utils/getScaleBandwidth.ts

@@ -0,0 +1,7 @@
+import type { AxisScale } from '@octanejs/visx/axis';
+
+export default function getScaleBandwidth<Scale extends AxisScale>(scale?: Scale) {
+	// Broaden type before using 'xxx' in s as typeguard.
+	const s = scale as AxisScale;
+	return s && 'bandwidth' in s ? (s?.bandwidth() ?? 0) : 0;
+}

package/src/xychart/utils/getScaleBaseline.ts

@@ -0,0 +1,24 @@
+import type { AxisScale } from '@octanejs/visx/axis';
+import { coerceNumber } from '@octanejs/visx/scale';
+import isValidNumber from '../typeguards/isValidNumber';
+
+/**
+ * Returns the output value of a scale's baseline value, which is either zero
+ * or the minimum scale value if its domain doesn't include zero.
+ */
+export default function getScaleBaseline<Scale extends AxisScale>(scale: Scale) {
+	const [a, b] = scale.range().map((rangeBoundary) => coerceNumber(rangeBoundary) ?? 0);
+	const isDescending = a != null && b != null && b < a;
+	const maybeScaleZero = scale(0);
+	const [minOutput, maxOutput] = isDescending ? [b, a] : [a, b];
+
+	// if maybeScaleZero _is_ a number, but the scale is not clamped and it's outside the domain
+	// fallback to the scale's minimum
+	return isDescending
+		? isValidNumber(maybeScaleZero)
+			? Math.min(Math.max(minOutput, maybeScaleZero), maxOutput)
+			: maxOutput
+		: isValidNumber(maybeScaleZero)
+			? Math.max(maybeScaleZero, minOutput)
+			: minOutput;
+}

package/src/xychart/utils/getScaledValueFactory.ts

@@ -0,0 +1,21 @@
+import type { AxisScale } from '@octanejs/visx/axis';
+import type { ScaleInput } from '@octanejs/visx/scale';
+import isValidNumber from '../typeguards/isValidNumber';
+import getScaleBandwidth from './getScaleBandwidth';
+
+/** Returns a function that takes a Datum as input and returns a scaled value, correcting for the scale's bandwidth if applicable. */
+export default function getScaledValueFactory<Scale extends AxisScale, Datum>(
+	scale: Scale,
+	accessor: (d: Datum) => ScaleInput<Scale>,
+	align: 'start' | 'center' | 'end' = 'center',
+) {
+	return (d: Datum) => {
+		const scaledValue = scale(accessor(d));
+		if (isValidNumber(scaledValue)) {
+			const bandwidthOffset =
+				(align === 'start' ? 0 : getScaleBandwidth(scale)) / (align === 'center' ? 2 : 1);
+			return scaledValue + bandwidthOffset;
+		}
+		return NaN;
+	};
+}

package/src/xychart/utils/isDiscreteScale.ts

@@ -0,0 +1,9 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { AxisScaleOutput } from '@octanejs/visx/axis';
+import type { ScaleConfig } from '@octanejs/visx/scale';
+
+export default function isDiscreteScale(scaleConfig: ScaleConfig<AxisScaleOutput, any, any>) {
+	return (
+		scaleConfig?.type === 'band' || scaleConfig?.type === 'ordinal' || scaleConfig?.type === 'point'
+	);
+}