@octanejs/visx 0.1.0

package/src/xychart/theme/colors.ts

@@ -0,0 +1,174 @@
+// source https://yeun.github.io/open-color/
+export const allColors: {
+	[hue: string]: [string, string, string, string, string, string, string, string, string, string];
+} = {
+	red: [
+		'#fff5f5',
+		'#ffe3e3',
+		'#ffc9c9',
+		'#ffa8a8',
+		'#ff8787',
+		'#ff6b6b',
+		'#fa5252',
+		'#f03e3e',
+		'#e03131',
+		'#c92a2a',
+	],
+	pink: [
+		'#fff0f6',
+		'#ffdeeb',
+		'#fcc2d7',
+		'#faa2c1',
+		'#f783ac',
+		'#f06595',
+		'#e64980',
+		'#d6336c',
+		'#c2255c',
+		'#a61e4d',
+	],
+	grape: [
+		'#f8f0fc',
+		'#f3d9fa',
+		'#eebefa',
+		'#e599f7',
+		'#da77f2',
+		'#cc5de8',
+		'#be4bdb',
+		'#ae3ec9',
+		'#9c36b5',
+		'#862e9c',
+	],
+	violet: [
+		'#f3f0ff',
+		'#e5dbff',
+		'#d0bfff',
+		'#b197fc',
+		'#9775fa',
+		'#845ef7',
+		'#7950f2',
+		'#7048e8',
+		'#6741d9',
+		'#5f3dc4',
+	],
+	indigo: [
+		'#edf2ff',
+		'#dbe4ff',
+		'#bac8ff',
+		'#91a7ff',
+		'#748ffc',
+		'#5c7cfa',
+		'#4c6ef5',
+		'#4263eb',
+		'#3b5bdb',
+		'#364fc7',
+	],
+	blue: [
+		'#e8f7ff',
+		'#ccedff',
+		'#a3daff',
+		'#72c3fc',
+		'#4dadf7',
+		'#329af0',
+		'#228ae6',
+		'#1c7cd6',
+		'#1b6ec2',
+		'#1862ab',
+	],
+	cyan: [
+		'#e3fafc',
+		'#c5f6fa',
+		'#99e9f2',
+		'#66d9e8',
+		'#3bc9db',
+		'#22b8cf',
+		'#15aabf',
+		'#1098ad',
+		'#0c8599',
+		'#0b7285',
+	],
+	teal: [
+		'#e6fcf5',
+		'#c3fae8',
+		'#96f2d7',
+		'#63e6be',
+		'#38d9a9',
+		'#20c997',
+		'#12b886',
+		'#0ca678',
+		'#099268',
+		'#087f5b',
+	],
+	green: [
+		'#ebfbee',
+		'#d3f9d8',
+		'#b2f2bb',
+		'#8ce99a',
+		'#69db7c',
+		'#51cf66',
+		'#40c057',
+		'#37b24d',
+		'#2f9e44',
+		'#2b8a3e',
+	],
+	lime: [
+		'#f4fce3',
+		'#e9fac8',
+		'#d8f5a2',
+		'#c0eb75',
+		'#a9e34b',
+		'#94d82d',
+		'#82c91e',
+		'#74b816',
+		'#66a80f',
+		'#5c940d',
+	],
+	yellow: [
+		'#fff9db',
+		'#fff3bf',
+		'#ffec99',
+		'#ffe066',
+		'#ffd43b',
+		'#fcc419',
+		'#fab005',
+		'#f59f00',
+		'#f08c00',
+		'#e67700',
+	],
+	orange: [
+		'#fff4e6',
+		'#ffe8cc',
+		'#ffd8a8',
+		'#ffc078',
+		'#ffa94d',
+		'#ff922b',
+		'#fd7e14',
+		'#f76707',
+		'#e8590c',
+		'#d9480f',
+	],
+	gray: [
+		'#f8f9fa',
+		'#f1f3f5',
+		'#e9ecef',
+		'#dee2e6',
+		'#ced4da',
+		'#adb5bd',
+		'#868e96',
+		'#495057',
+		'#343a40',
+		'#212529',
+	],
+};
+
+export const grayColors = allColors.gray;
+export const textColor = grayColors[7];
+
+export const defaultColors = [
+	allColors.cyan[9],
+	allColors.cyan[3],
+	allColors.yellow[5],
+	allColors.red[4],
+	allColors.grape[8],
+	allColors.grape[5],
+	allColors.pink[9],
+];

package/src/xychart/theme/themes/dark.ts

@@ -0,0 +1,24 @@
+import { allColors, grayColors } from '../colors';
+import buildChartTheme from '../buildChartTheme';
+
+export default buildChartTheme({
+	backgroundColor: '#222',
+	colors: [
+		allColors.cyan[4],
+		allColors.teal[1],
+		allColors.yellow[2],
+		allColors.red[4],
+		allColors.grape[3],
+		allColors.grape[6],
+		allColors.pink[3],
+	],
+	tickLength: 4,
+	svgLabelSmall: {
+		fill: grayColors[2],
+	},
+	svgLabelBig: {
+		fill: grayColors[0],
+	},
+	gridColor: grayColors[4],
+	gridColorDark: grayColors[1],
+});

package/src/xychart/theme/themes/light.ts

@@ -0,0 +1,16 @@
+import { defaultColors, grayColors } from '../colors';
+import buildChartTheme from '../buildChartTheme';
+
+export default buildChartTheme({
+	backgroundColor: '#fff',
+	colors: defaultColors,
+	tickLength: 4,
+	svgLabelSmall: {
+		fill: grayColors[7],
+	},
+	svgLabelBig: {
+		fill: grayColors[9],
+	},
+	gridColor: grayColors[5],
+	gridColorDark: grayColors[9],
+});

package/src/xychart/typeguards/events.ts

@@ -0,0 +1,12 @@
+import type { FocusEvent, PointerEvent } from 'react';
+
+type EventType = PointerEvent | FocusEvent;
+
+// functional definition of a PointerEvent (mouse, touch)
+export function isPointerEvent(event?: EventType): event is PointerEvent {
+	return !!event && ('clientX' in event || 'changedTouches' in event);
+}
+
+export function isFocusEvent(event?: EventType): event is FocusEvent {
+	return !!event && !isPointerEvent(event);
+}

package/src/xychart/typeguards/isValidNumber.ts

@@ -0,0 +1,3 @@
+export default function isValidNumber(_: unknown): _ is number {
+	return _ != null && typeof _ === 'number' && !Number.isNaN(_) && Number.isFinite(_);
+}

package/src/xychart/types/axis.ts

@@ -0,0 +1,3 @@
+import type { AxisScale as AxisAxisScale } from '@octanejs/visx/axis';
+
+export type AxisScale = AxisAxisScale;

package/src/xychart/types/data.ts

@@ -0,0 +1,57 @@
+import type { AxisScale } from '@octanejs/visx/axis';
+import type { ResizeObserverPolyfill } from '@octanejs/visx/responsive';
+import type { ScaleTypeToD3Scale, ScaleInput } from '@octanejs/visx/scale';
+import type DataRegistry from '../classes/DataRegistry';
+import type { XYChartTheme } from './theme';
+
+export type Margin = {
+	top: number;
+	right: number;
+	bottom: number;
+	left: number;
+};
+
+export type LegendShape = 'rect' | 'line' | 'dashed-line' | 'circle';
+
+export interface DataRegistryEntry<XScale extends AxisScale, YScale extends AxisScale, Datum> {
+	/** unique data key */
+	key: string;
+	/** array of data for the key. */
+	data: Datum[];
+	/** function that returns the x value of a datum. */
+	xAccessor: (d: Datum) => ScaleInput<XScale>;
+	/** function that returns the y value of a datum. */
+	yAccessor: (d: Datum) => ScaleInput<YScale>;
+	/** whether the entry supports mouse events. */
+	mouseEvents?: boolean;
+	/** Optionally update the xScale. */
+	xScale?: <Scale extends AxisScale>(xScale: Scale) => Scale;
+	/** Optionally update the yScale. */
+	yScale?: <Scale extends AxisScale>(yScale: Scale) => Scale;
+	/** Legend shape for the data key. */
+	legendShape?: LegendShape;
+}
+
+export interface DataContextType<
+	XScale extends AxisScale,
+	YScale extends AxisScale,
+	Datum extends object,
+> {
+	xScale: XScale;
+	yScale: YScale;
+	colorScale: ScaleTypeToD3Scale<string, string>['ordinal'];
+	width: number;
+	height: number;
+	innerWidth: number;
+	innerHeight: number;
+	margin: Margin;
+	dataRegistry: Omit<DataRegistry<XScale, YScale, Datum>, 'registry' | 'registryKeys'>;
+	registerData: (
+		data: DataRegistryEntry<XScale, YScale, Datum> | DataRegistryEntry<XScale, YScale, Datum>[],
+	) => void;
+	unregisterData: (keyOrKeys: string | string[]) => void;
+	setDimensions: (dims: { width: number; height: number; margin: Margin }) => void;
+	theme: XYChartTheme;
+	horizontal: boolean;
+	resizeObserverPolyfill?: ResizeObserverPolyfill;
+}

package/src/xychart/types/event.ts

@@ -0,0 +1,30 @@
+import type { AxisScale } from '@octanejs/visx/axis';
+import type { ScaleInput } from '@octanejs/visx/scale';
+import type { Emitter } from 'mitt';
+
+export type EventEmitterContextType = Emitter;
+
+/** Arguments for findNearestDatum* functions. */
+export type NearestDatumArgs<
+	XScale extends AxisScale,
+	YScale extends AxisScale,
+	Datum extends object,
+> = {
+	dataKey: string;
+	point: { x: number; y: number } | null;
+	xAccessor: (d: Datum) => ScaleInput<XScale>;
+	yAccessor: (d: Datum) => ScaleInput<YScale>;
+	data: Datum[];
+	width: number;
+	height: number;
+	xScale: XScale;
+	yScale: YScale;
+};
+
+/** Return type for nearestDatum* functions. */
+export type NearestDatumReturnType<Datum extends object> = {
+	datum: Datum;
+	index: number;
+	distanceX: number;
+	distanceY: number;
+} | null;

package/src/xychart/types/index.ts

@@ -0,0 +1,6 @@
+export type * from './axis';
+export type * from './data';
+export type * from './event';
+export type * from './series';
+export type * from './theme';
+export type * from './tooltip';

package/src/xychart/types/series.ts

@@ -0,0 +1,219 @@
+import type { PointerEvent, FocusEvent, SVGProps } from 'react';
+import type { AxisScale } from '@octanejs/visx/axis';
+import type { ScaleInput } from '@octanejs/visx/scale';
+import type { Series, SeriesPoint } from 'd3-shape';
+
+/** Call signature of PointerEvent callback. */
+export type EventHandlerParams<Datum> = {
+	/** Series key that datum belongs to. */
+	key: string;
+	/** Index of datum in series data array. */
+	index: number;
+	/** Datum. */
+	datum: Datum;
+	/** Optional distance of datum x value to event x value. Used to determine closest datum. */
+	distanceX?: number;
+	/** Optional distance of datum y value to event y value. Used to determine closest datum. */
+	distanceY?: number;
+	/** Coordinates of the event in svg space. */
+	svgPoint?: { x: number; y: number };
+	/** The PointerEvent or FocusEvent. */
+	event?: PointerEvent | FocusEvent;
+};
+
+export type SeriesProps<
+	XScale extends AxisScale,
+	YScale extends AxisScale,
+	Datum extends object,
+> = {
+	/** Required data key for the Series, should be unique across all series. */
+	dataKey: string;
+	/** Data for the Series. */
+	data: Datum[];
+	/** Given a Datum, returns the x-scale value. */
+	xAccessor: (d: Datum) => ScaleInput<XScale>;
+	/** Given a Datum, returns the y-scale value. */
+	yAccessor: (d: Datum) => ScaleInput<YScale>;
+	/**
+	 * Callback invoked for onPointerMove events for the nearest Datum to the PointerEvent.
+	 * By default XYChart will capture and emit PointerEvents, invoking this function for
+	 * any Series with a defined handler. Alternatively you may set <XYChart captureEvents={false} />
+	 * and Series will emit their own events.
+	 */
+	onPointerMove?: ({
+		datum,
+		distanceX,
+		distanceY,
+		event,
+		index,
+		key,
+		svgPoint,
+	}: EventHandlerParams<Datum>) => void;
+	/**
+	 * Callback invoked for onPointerOut events. By default XYChart will capture and emit
+	 * PointerEvents, invoking this function for any Series with a defined handler.
+	 * Alternatively you may set <XYChart captureEvents={false} /> and Series will emit
+	 * their own events.
+	 */
+	onPointerOut?: (
+		/** The PointerEvent. */
+		event: PointerEvent,
+	) => void;
+	/**
+	 * Callback invoked for onPointerUp events for the nearest Datum to the PointerEvent.
+	 * By default XYChart will capture and emit PointerEvents, invoking this function for
+	 * any Series with a defined handler. Alternatively you may set <XYChart captureEvents={false} />
+	 * and Series will emit their own events.
+	 */
+	onPointerUp?: ({
+		datum,
+		distanceX,
+		distanceY,
+		event,
+		index,
+		key,
+		svgPoint,
+	}: EventHandlerParams<Datum>) => void;
+
+	/**
+	 * Callback invoked for onPointerDown events for the nearest Datum to the PointerEvent.
+	 * By default XYChart will capture and emit PointerEvents, invoking this function for
+	 * any Series with a defined handler. Alternatively you may set <XYChart captureEvents={false} />
+	 * and Series will emit their own events.
+	 */
+	onPointerDown?: ({
+		datum,
+		distanceX,
+		distanceY,
+		event,
+		index,
+		key,
+		svgPoint,
+	}: EventHandlerParams<Datum>) => void;
+
+	/**
+	 * Callback invoked for onFocus events for the nearest Datum to the FocusEvent.
+	 * XYChart will NOT capture and emit FocusEvents, they are emitted from individual Series glyph shapes.
+	 */
+	onFocus?: ({
+		datum,
+		distanceX,
+		distanceY,
+		event,
+		index,
+		key,
+		svgPoint,
+	}: EventHandlerParams<Datum>) => void;
+	/**
+	 * Callback invoked for onBlur events for the nearest Datum to the FocusEvent.
+	 * XYChart will NOT capture and emit FocusEvents, they are emitted from individual Series glyph shapes.
+	 */
+	onBlur?: (
+		/** The FocusEvent. */
+		event: FocusEvent,
+	) => void;
+	/** Whether the Series emits and subscribes to PointerEvents and FocusEvents (including Tooltip triggering). */
+	enableEvents?: boolean;
+};
+
+/** Bar shape. */
+export type Bar = {
+	/** Unique key for Bar (not dataKey). */
+	key: string;
+	/** X coordinate of Bar. */
+	x: number;
+	/** Y coordinate of Bar. */
+	y: number;
+	/** Width of Bar. */
+	width: number;
+	/** Height of Bar. */
+	height: number;
+	/** Fill color of Bar */
+	fill?: string;
+};
+
+/** Props for base Bars components */
+export type BarsProps<XScale extends AxisScale, YScale extends AxisScale> = {
+	bars: Bar[];
+	xScale: XScale;
+	yScale: YScale;
+	horizontal?: boolean;
+	/** Optional radius to apply to bar corners. */
+	radius?: number;
+	/** Whether to apply radius to all corners. */
+	radiusAll?: boolean;
+	/** Whether to apply radius to top corners. */
+	radiusTop?: boolean;
+	/** Whether to apply radius to right corners. */
+	radiusRight?: boolean;
+	/** Whether to apply radius to bottom corners. */
+	radiusBottom?: boolean;
+	/** Whether to apply radius to left corners. */
+	radiusLeft?: boolean;
+} & Omit<
+	SVGProps<SVGRectElement | SVGPathElement>,
+	'x' | 'y' | 'width' | 'height' | 'ref' | 'children'
+>;
+
+// BarStack transforms its child series Datum into CombinedData<XScale, YScale>
+export type BarStackDatum<XScale extends AxisScale, YScale extends AxisScale> = SeriesPoint<
+	CombinedStackData<XScale, YScale>
+>;
+
+export type BarStackData<XScale extends AxisScale, YScale extends AxisScale> = Series<
+	CombinedStackData<XScale, YScale>,
+	string
+>[];
+
+export type CombinedStackData<XScale extends AxisScale, YScale extends AxisScale> = {
+	[dataKey: string]: ScaleInput<XScale> | ScaleInput<YScale>;
+} & { stack: ScaleInput<XScale> | ScaleInput<YScale>; positiveSum: number; negativeSum: number };
+
+/** Glyphs */
+export type GlyphsProps<
+	XScale extends AxisScale,
+	YScale extends AxisScale,
+	Datum extends object,
+> = {
+	xScale: XScale;
+	yScale: YScale;
+	horizontal?: boolean;
+	glyphs: GlyphProps<Datum>[];
+	/** Callback to invoke for onBlur. */
+	onBlur?: (event: FocusEvent) => void;
+	/** Callback to invoke for onFocus. */
+	onFocus?: (event: FocusEvent) => void;
+	/** Callback to invoke for onPointerMove. */
+	onPointerMove?: (event: PointerEvent) => void;
+	/** Callback to invoke for onPointerOut. */
+	onPointerOut?: (event: PointerEvent) => void;
+	/** Callback to invoke for onPointerUp. */
+	onPointerUp?: (event: PointerEvent) => void;
+};
+
+export type GlyphProps<Datum extends object> = {
+	/** Unique key for Glyph (not dataKey). */
+	key: string;
+	/** Datum for Glyph. */
+	datum: Datum;
+	/** Index of Datum in data array. */
+	index: number;
+	/** X coordinate of Glyph. */
+	x: number;
+	/** Y coordinate of Glyph. */
+	y: number;
+	/** Size of Glyph. */
+	size: number;
+	/** Color of Glyph. */
+	color: string;
+	/** Callback to invoke for onBlur. */
+	onBlur?: (event: FocusEvent) => void;
+	/** Callback to invoke for onFocus. */
+	onFocus?: (event: FocusEvent) => void;
+	/** Callback to invoke for onPointerMove. */
+	onPointerMove?: (event: PointerEvent) => void;
+	/** Callback to invoke for onPointerOut. */
+	onPointerOut?: (event: PointerEvent) => void;
+	/** Callback to invoke for onPointerUp. */
+	onPointerUp?: (event: PointerEvent) => void;
+};

package/src/xychart/types/theme.ts

@@ -0,0 +1,50 @@
+import type { CSSProperties, HTMLAttributes, SVGAttributes } from 'react';
+import type { TextProps } from '@octanejs/visx/text';
+
+export type HTMLTextStyles = HTMLAttributes<HTMLDivElement>['style'];
+
+export type LineStyles = Omit<SVGAttributes<SVGLineElement>, 'Key'>;
+
+export type GridStyles = CSSProperties;
+
+export type SVGTextProps = TextProps;
+
+interface AxisStyle {
+	/** Axis label styles. */
+	axisLabel: SVGTextProps;
+	/** Axis line styles. */
+	axisLine: LineStyles;
+	/** Tick label styles. */
+	tickLabel: SVGTextProps;
+	/** Tick line styles. */
+	tickLine: LineStyles;
+	/** Length of axis tick lines. */
+	tickLength: number;
+}
+
+/** A complete chart theme includes style definitions for all axis orientations. */
+export interface XYChartTheme {
+	/** Base background color. */
+	backgroundColor: string;
+	/** Ordinal colors to be used for default coloring by series `key`s. */
+	colors: string[];
+	/** Styles to applied to HMTL labels. */
+	htmlLabel: HTMLTextStyles;
+	/** Styles to applied to big SVG labels (axis label, annotation title, etc.). */
+	svgLabelBig: SVGTextProps;
+	/** Styles to applied to small SVG labels (tick label, annotation subtitle, etc.). */
+	svgLabelSmall: SVGTextProps;
+	/** Styles to be applied to chart grids. */
+	gridStyles: GridStyles;
+	/** Styles to be applied to axes (axis labels, ticks, tick labels). */
+	axisStyles: {
+		x: {
+			top: AxisStyle;
+			bottom: AxisStyle;
+		};
+		y: {
+			left: AxisStyle;
+			right: AxisStyle;
+		};
+	};
+}

package/src/xychart/types/tooltip.ts

@@ -0,0 +1,24 @@
+import type { UseTooltipParams } from '@octanejs/visx/tooltip';
+import type { EventHandlerParams } from './series';
+
+export type TooltipDatum<Datum extends object> = {
+	/** Series key that datum belongs to. */
+	key: string;
+	/** Index of datum in series data array. */
+	index: number;
+	/** Datum. */
+	datum: Datum;
+};
+
+export type TooltipData<Datum extends object = object> = {
+	/** Nearest Datum to event across all Series. */
+	nearestDatum?: TooltipDatum<Datum> & { distance: number };
+	/** Nearest Datum to event across for each Series. */
+	datumByKey: {
+		[key: string]: TooltipDatum<Datum>;
+	};
+};
+
+export type TooltipContextType<Datum extends object> = UseTooltipParams<TooltipData<Datum>> & {
+	showTooltip: (params: EventHandlerParams<Datum>) => void;
+};

package/src/xychart/utils/cleanColorString.ts

@@ -0,0 +1,4 @@
+/* react-spring cannot tween colors with url ids (patterns, gradients), these helpers detect and clean them. */
+const neutralCleanColor = 'rgba(0,0,0,0.1)';
+export const colorHasUrl = (color?: string) => Boolean(color?.includes('url('));
+export const cleanColor = (color?: string) => (colorHasUrl(color) ? neutralCleanColor : color);

package/src/xychart/utils/collectDataRegistryEntries.ts

@@ -0,0 +1,50 @@
+import { Children } from 'octane';
+import type { ReactNode } from 'react';
+import type { AxisScale } from '@octanejs/visx/axis';
+import type { DataRegistryEntry } from '../types';
+
+type ElementWithProps = { props?: Record<string, unknown> | null };
+
+function hasProps(value: unknown): value is ElementWithProps {
+	return value !== null && typeof value === 'object' && 'props' in value;
+}
+
+/**
+ * Discovers series descriptors before their effects run. Octane's return-form
+ * TSRX preserves JSX children as element descriptors, so fixed-size XYChart
+ * scales can be built during the server render and the first hydration pass.
+ */
+export default function collectDataRegistryEntries<
+	XScale extends AxisScale,
+	YScale extends AxisScale,
+	Datum extends object,
+>(children: ReactNode): DataRegistryEntry<XScale, YScale, Datum>[] {
+	const entries = new Map<string, DataRegistryEntry<XScale, YScale, Datum>>();
+
+	function visit(value: unknown): void {
+		for (const child of Children.toArray(value)) {
+			if (!hasProps(child) || child.props == null) continue;
+			const props = child.props;
+			const { data, dataKey, xAccessor, yAccessor } = props;
+
+			if (
+				typeof dataKey === 'string' &&
+				Array.isArray(data) &&
+				typeof xAccessor === 'function' &&
+				typeof yAccessor === 'function'
+			) {
+				entries.set(dataKey, {
+					key: dataKey,
+					data: data as Datum[],
+					xAccessor: xAccessor as DataRegistryEntry<XScale, YScale, Datum>['xAccessor'],
+					yAccessor: yAccessor as DataRegistryEntry<XScale, YScale, Datum>['yAccessor'],
+				});
+			}
+
+			if ('children' in props) visit(props.children);
+		}
+	}
+
+	visit(children);
+	return [...entries.values()];
+}