@octanejs/visx 0.1.0

package/src/kernel/path/createPath.ts

@@ -0,0 +1,132 @@
+const TAU = Math.PI * 2;
+
+export type PathBuilder = {
+	arc(
+		centerX: number,
+		centerY: number,
+		radius: number,
+		startAngle: number,
+		endAngle: number,
+		counterclockwise?: boolean,
+	): PathBuilder;
+	bezierCurveTo(
+		controlX1: number,
+		controlY1: number,
+		controlX2: number,
+		controlY2: number,
+		x: number,
+		y: number,
+	): PathBuilder;
+	closePath(): PathBuilder;
+	lineTo(x: number, y: number): PathBuilder;
+	moveTo(x: number, y: number): PathBuilder;
+	quadraticCurveTo(controlX: number, controlY: number, x: number, y: number): PathBuilder;
+	rect(x: number, y: number, width: number, height: number): PathBuilder;
+	toString(): string;
+};
+
+class PathBuilderImpl implements PathBuilder {
+	private readonly commands: string[] = [];
+
+	private readonly precision: number;
+
+	constructor(precision: number) {
+		this.precision = precision;
+	}
+
+	private number(value: number) {
+		return Number(value.toFixed(this.precision)).toString();
+	}
+
+	private point(x: number, y: number) {
+		return `${this.number(x)},${this.number(y)}`;
+	}
+
+	private append(command: string) {
+		this.commands.push(command);
+		return this;
+	}
+
+	moveTo(x: number, y: number) {
+		return this.append(`M${this.point(x, y)}`);
+	}
+
+	lineTo(x: number, y: number) {
+		return this.append(`L${this.point(x, y)}`);
+	}
+
+	closePath() {
+		return this.append('Z');
+	}
+
+	quadraticCurveTo(controlX: number, controlY: number, x: number, y: number) {
+		return this.append(`Q${this.point(controlX, controlY)},${this.point(x, y)}`);
+	}
+
+	bezierCurveTo(
+		controlX1: number,
+		controlY1: number,
+		controlX2: number,
+		controlY2: number,
+		x: number,
+		y: number,
+	) {
+		return this.append(
+			`C${this.point(controlX1, controlY1)},${this.point(controlX2, controlY2)},${this.point(
+				x,
+				y,
+			)}`,
+		);
+	}
+
+	rect(x: number, y: number, width: number, height: number) {
+		return this.append(
+			`M${this.point(x, y)}h${this.number(width)}v${this.number(height)}h${this.number(-width)}Z`,
+		);
+	}
+
+	arc(
+		centerX: number,
+		centerY: number,
+		radius: number,
+		startAngle: number,
+		endAngle: number,
+		counterclockwise = false,
+	) {
+		const delta = counterclockwise
+			? -((startAngle - endAngle + TAU) % TAU || TAU)
+			: (endAngle - startAngle + TAU) % TAU || TAU;
+		const sweep = counterclockwise ? 0 : 1;
+		const drawArc = (from: number, to: number) => {
+			const largeArc = Math.abs(to - from) > Math.PI ? 1 : 0;
+			const x = centerX + radius * Math.cos(to);
+			const y = centerY + radius * Math.sin(to);
+
+			this.append(
+				`A${this.number(radius)},${this.number(radius)},0,${largeArc},${sweep},${this.point(x, y)}`,
+			);
+		};
+		const startX = centerX + radius * Math.cos(startAngle);
+		const startY = centerY + radius * Math.sin(startAngle);
+
+		if (this.commands.length === 0) this.moveTo(startX, startY);
+		else this.lineTo(startX, startY);
+
+		if (Math.abs(delta) >= TAU) {
+			drawArc(startAngle, startAngle + delta / 2);
+			drawArc(startAngle + delta / 2, startAngle + delta);
+		} else {
+			drawArc(startAngle, startAngle + delta);
+		}
+
+		return this;
+	}
+
+	toString() {
+		return this.commands.join('');
+	}
+}
+
+export default function createPath(precision = 3): PathBuilder {
+	return new PathBuilderImpl(precision);
+}

package/src/kernel/path/toPath2D.ts

@@ -0,0 +1,41 @@
+const CACHE_LIMIT = 1024;
+const pathCache = new Map<string, Path2D>();
+
+class Path2DShim {
+	private readonly d: string;
+
+	constructor(d = '') {
+		this.d = d;
+	}
+
+	toString() {
+		return this.d;
+	}
+}
+
+function createPath2D(d: string) {
+	const Path2DConstructor =
+		typeof Path2D === 'undefined' ? (Path2DShim as unknown as typeof Path2D) : Path2D;
+
+	return new Path2DConstructor(d);
+}
+
+export default function toPath2D(d: string): Path2D {
+	const cachedPath = pathCache.get(d);
+
+	if (cachedPath) {
+		pathCache.delete(d);
+		pathCache.set(d, cachedPath);
+		return cachedPath;
+	}
+
+	const path = createPath2D(d);
+	pathCache.set(d, path);
+
+	if (pathCache.size > CACHE_LIMIT) {
+		const firstKey = pathCache.keys().next().value;
+		if (firstKey !== undefined) pathCache.delete(firstKey);
+	}
+
+	return path;
+}

package/src/kernel/refs/useLatestRef.tsrx

@@ -0,0 +1,7 @@
+import { useRef } from 'octane';
+
+export default function useLatestRef<T>(value: T) {
+	const valueRef = useRef(value);
+	valueRef.current = value;
+	return valueRef;
+}

package/src/kernel/refs/useLatestRef.tsrx.d.ts

@@ -0,0 +1,4 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+export default function useLatestRef<T>(value: T): {
+    current: T;
+};

package/src/kernel/refs/useStableCallback.tsrx

@@ -0,0 +1,13 @@
+import { useRef } from 'octane';
+import useLatestRef from './useLatestRef.tsrx';
+
+export default function useStableCallback<Args extends readonly unknown[], Result>(callback: (...args: Args) => Result) {
+	const callbackRef = useLatestRef(callback);
+	const stableCallbackRef = useRef<((...args: Args) => Result) | null>(null);
+
+	if (stableCallbackRef.current === null) {
+		stableCallbackRef.current = (...args: Args) => callbackRef.current(...args);
+	}
+
+	return stableCallbackRef.current;
+}

package/src/kernel/refs/useStableCallback.tsrx.d.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+export default function useStableCallback<Args extends readonly unknown[], Result>(callback: (...args: Args) => Result): (...args: Args) => Result;

package/src/kernel/warnings.ts

@@ -0,0 +1,76 @@
+export type WarnCode = 'EMPTY_DATA' | 'NAN_IN_DATA';
+export type WarnDetails = Readonly<Record<string, unknown>>;
+
+export type KernelWarning<Code extends string = string> = {
+	code: Code;
+	details?: WarnDetails;
+	message: string;
+	source: string;
+};
+
+export type WarnHandler = (warning: KernelWarning) => void;
+
+const warnedMessages = new Set<string>();
+
+function formatWarning({ code, message, source }: KernelWarning) {
+	return `${source} ${code}: ${message}`;
+}
+
+function defaultWarnHandler(warning: KernelWarning) {
+	if (process.env.NODE_ENV !== 'production') {
+		if (warning.details) {
+			console.warn(formatWarning(warning), warning.details);
+		} else {
+			console.warn(formatWarning(warning));
+		}
+	}
+}
+
+let warnHandler: WarnHandler = defaultWarnHandler;
+
+export function setWarnHandler(handler?: WarnHandler | null) {
+	const previousWarnHandler = warnHandler;
+
+	warnHandler = handler ?? defaultWarnHandler;
+
+	return () => {
+		warnHandler = previousWarnHandler;
+	};
+}
+
+export function resetWarnCache() {
+	warnedMessages.clear();
+}
+
+function getDetailsKey(details?: WarnDetails) {
+	if (!details) {
+		return '';
+	}
+
+	try {
+		return JSON.stringify(details);
+	} catch {
+		return '[unserializable]';
+	}
+}
+
+export function devWarn<Code extends string>(
+	code: Code,
+	message: string,
+	source?: string,
+	details?: WarnDetails,
+) {
+	if (process.env.NODE_ENV === 'production') {
+		return;
+	}
+
+	const warningSource = source ?? '@octanejs/visx/kernel';
+	const key = `${warningSource}:${code}:${message}:${getDetailsKey(details)}`;
+
+	if (warnedMessages.has(key)) {
+		return;
+	}
+
+	warnedMessages.add(key);
+	warnHandler({ code, details, message, source: warningSource });
+}

package/src/legend/index.ts

@@ -0,0 +1,27 @@
+// @octanejs/visx/legend
+export { default as Legend } from './legends/Legend/index.tsrx';
+export { default as LegendQuantile } from './legends/Quantile.tsrx';
+export { default as LegendLinear } from './legends/Linear.tsrx';
+export { default as LegendOrdinal } from './legends/Ordinal.tsrx';
+export { default as LegendThreshold } from './legends/Threshold.tsrx';
+export { default as LegendSize } from './legends/Size.tsrx';
+export { default as LegendItem } from './legends/Legend/LegendItem.tsrx';
+export { default as LegendLabel } from './legends/Legend/LegendLabel.tsrx';
+export { default as LegendShape } from './legends/Legend/LegendShape.tsrx';
+export { default as CircleShape } from './shapes/Circle.tsrx';
+export { default as LineShape } from './shapes/Line.tsrx';
+export { default as RectShape } from './shapes/Rect.tsrx';
+
+export type * from './types';
+export type { LegendProps } from './legends/Legend/index.tsrx';
+export type { LegendItemProps } from './legends/Legend/LegendItem.tsrx';
+export type { LegendLabelProps, LegendLabelOwnProps } from './legends/Legend/LegendLabel.tsrx';
+export type { LegendShapeProps } from './legends/Legend/LegendShape.tsrx';
+export type { LegendLinearProps } from './legends/Linear.tsrx';
+export type { LegendOrdinalProps } from './legends/Ordinal.tsrx';
+export type { LegendQuantileProps } from './legends/Quantile.tsrx';
+export type { LegendSizeProps } from './legends/Size.tsrx';
+export type { LegendThresholdProps } from './legends/Threshold.tsrx';
+export type { ShapeCircleProps } from './shapes/Circle.tsrx';
+export type { ShapeShapeLineProps } from './shapes/Line.tsrx';
+export type { ShapeRectProps } from './shapes/Rect.tsrx';

package/src/legend/legends/Legend/LegendItem.tsrx

@@ -0,0 +1,35 @@
+import type { ReactNode, HTMLProps } from 'react';
+import type { FlexDirection } from '../../types';
+
+export type LegendItemProps = {
+	/** Flex direction for the legend item layout. Determines if the shape and label are arranged horizontally or vertically. */
+	flexDirection?: FlexDirection;
+	/** CSS align-items property for vertical alignment of the legend item contents. */
+	alignItems?: string;
+	/** Margin around the legend item. */
+	margin?: string | number;
+	/** Child elements to render inside the legend item (typically LegendShape and LegendLabel). */
+	children?: ReactNode;
+	/** CSS display property for the legend item. */
+	display?: string;
+};
+
+export default function LegendItem({
+	flexDirection = 'row',
+	alignItems = 'center',
+	margin = '0',
+	display = 'flex',
+	children,
+	...restProps
+}: LegendItemProps & Omit<HTMLProps<HTMLDivElement>, keyof LegendItemProps>) {
+	return <div
+		className="visx-legend-item"
+		style={{
+			display,
+			alignItems,
+			flexDirection,
+			margin,
+		}}
+		{...restProps}
+	>{children}</div>;
+}

package/src/legend/legends/Legend/LegendItem.tsrx.d.ts

@@ -0,0 +1,16 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { ReactNode, HTMLProps } from 'react';
+import type { FlexDirection } from '../../types';
+export type LegendItemProps = {
+    /** Flex direction for the legend item layout. Determines if the shape and label are arranged horizontally or vertically. */
+    flexDirection?: FlexDirection;
+    /** CSS align-items property for vertical alignment of the legend item contents. */
+    alignItems?: string;
+    /** Margin around the legend item. */
+    margin?: string | number;
+    /** Child elements to render inside the legend item (typically LegendShape and LegendLabel). */
+    children?: ReactNode;
+    /** CSS display property for the legend item. */
+    display?: string;
+};
+export default function LegendItem({ flexDirection, alignItems, margin, display, children, ...restProps }: LegendItemProps & Omit<HTMLProps<HTMLDivElement>, keyof LegendItemProps>): import("react").JSX.Element;

package/src/legend/legends/Legend/LegendLabel.tsrx

@@ -0,0 +1,39 @@
+import type { ReactNode, HTMLProps } from 'react';
+
+export type LegendLabelOwnProps = {
+	/** Horizontal alignment of the label text. Maps to CSS justify-content property. */
+	align?: string;
+	/** The label content to display. Can be a string or any React node. */
+	label?: ReactNode;
+	/** CSS flex property controlling how the label grows/shrinks in the legend item. */
+	flex?: string | number;
+	/** Margin around the label. */
+	margin?: string | number;
+	/** Child elements to render. If provided, overrides the label prop. */
+	children?: ReactNode;
+};
+
+export type LegendLabelProps =
+	LegendLabelOwnProps & Omit<HTMLProps<HTMLDivElement>, keyof LegendLabelOwnProps>;
+
+export default function LegendLabel({
+	flex = '1',
+	label,
+	margin = '5px 0',
+	align = 'left',
+	children,
+	...restProps
+}: LegendLabelProps) {
+	return <div
+		className="visx-legend-label"
+		style={{
+			justifyContent: align,
+			display: 'flex',
+			flex,
+			margin,
+		}}
+		{...restProps}
+	>
+		{children || label}
+	</div>;
+}

package/src/legend/legends/Legend/LegendLabel.tsrx.d.ts

@@ -0,0 +1,16 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { ReactNode, HTMLProps } from 'react';
+export type LegendLabelOwnProps = {
+    /** Horizontal alignment of the label text. Maps to CSS justify-content property. */
+    align?: string;
+    /** The label content to display. Can be a string or any React node. */
+    label?: ReactNode;
+    /** CSS flex property controlling how the label grows/shrinks in the legend item. */
+    flex?: string | number;
+    /** Margin around the label. */
+    margin?: string | number;
+    /** Child elements to render. If provided, overrides the label prop. */
+    children?: ReactNode;
+};
+export type LegendLabelProps = LegendLabelOwnProps & Omit<HTMLProps<HTMLDivElement>, keyof LegendLabelOwnProps>;
+export default function LegendLabel({ flex, label, margin, align, children, ...restProps }: LegendLabelProps): import("react").JSX.Element;

package/src/legend/legends/Legend/LegendShape.tsrx

@@ -0,0 +1,64 @@
+import ShapeRect from '../../shapes/Rect.tsrx';
+import renderShape from '../../util/renderShape';
+import type {
+	FillAccessor,
+	FormattedLabel,
+	LegendShape as LegendShapeType,
+	SizeAccessor,
+	ShapeStyleAccessor,
+} from '../../types';
+
+export type LegendShapeProps<Data, Output> = {
+	/** The formatted label object containing datum, index, text, and optional value */
+	label: FormattedLabel<Data, Output>;
+	/** The data item for this legend entry */
+	item: Data;
+	/** The index of this item in the legend */
+	itemIndex: number;
+	/** Margin around the shape */
+	margin?: string | number;
+	/** The shape component or function to render. Defaults to ShapeRect if not provided. */
+	shape?: LegendShapeType<Data, Output>;
+	/** Accessor function for the fill color of the shape */
+	fill?: FillAccessor<Data, Output>;
+	/** Accessor function for the size of the shape */
+	size?: SizeAccessor<Data, Output>;
+	/** Accessor function for additional shape styling */
+	shapeStyle?: ShapeStyleAccessor<Data, Output>;
+	/** Width of the shape container */
+	width?: string | number;
+	/** Height of the shape container */
+	height?: string | number;
+};
+
+export default function LegendShape<Data, Output>({
+	shape = ShapeRect,
+	width,
+	height,
+	margin,
+	label,
+	item,
+	itemIndex,
+	fill,
+	size,
+	shapeStyle,
+}: LegendShapeProps<Data, Output>) {
+	return <div
+		className="visx-legend-shape"
+		style={{
+			display: 'flex',
+			width: size ? size({ ...label }) : width,
+			height: size ? size({ ...label }) : height,
+			margin,
+		}}
+	>{renderShape<Data, Output>({
+		shape,
+		item,
+		itemIndex,
+		label,
+		width,
+		height,
+		fill,
+		shapeStyle,
+	})}</div>;
+}

package/src/legend/legends/Legend/LegendShape.tsrx.d.ts

@@ -0,0 +1,25 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { FillAccessor, FormattedLabel, LegendShape as LegendShapeType, SizeAccessor, ShapeStyleAccessor } from '../../types';
+export type LegendShapeProps<Data, Output> = {
+    /** The formatted label object containing datum, index, text, and optional value */
+    label: FormattedLabel<Data, Output>;
+    /** The data item for this legend entry */
+    item: Data;
+    /** The index of this item in the legend */
+    itemIndex: number;
+    /** Margin around the shape */
+    margin?: string | number;
+    /** The shape component or function to render. Defaults to ShapeRect if not provided. */
+    shape?: LegendShapeType<Data, Output>;
+    /** Accessor function for the fill color of the shape */
+    fill?: FillAccessor<Data, Output>;
+    /** Accessor function for the size of the shape */
+    size?: SizeAccessor<Data, Output>;
+    /** Accessor function for additional shape styling */
+    shapeStyle?: ShapeStyleAccessor<Data, Output>;
+    /** Width of the shape container */
+    width?: string | number;
+    /** Height of the shape container */
+    height?: string | number;
+};
+export default function LegendShape<Data, Output>({ shape, width, height, margin, label, item, itemIndex, fill, size, shapeStyle, }: LegendShapeProps<Data, Output>): import("react").JSX.Element;

package/src/legend/legends/Legend/index.tsrx

@@ -0,0 +1,140 @@
+import type { ReactNode, CSSProperties } from 'react';
+import { createElement } from 'octane';
+import cx from 'classnames';
+import type { AnyD3Scale, ScaleInput } from '@octanejs/visx/scale';
+import LegendItem from './LegendItem.tsrx';
+import type { LegendLabelProps } from './LegendLabel.tsrx';
+import LegendLabel from './LegendLabel.tsrx';
+import LegendShape from './LegendShape.tsrx';
+import valueOrIdentity, { valueOrIdentityString } from '../../util/valueOrIdentity';
+import labelTransformFactory from '../../util/labelTransformFactory';
+import type {
+	FlexDirection,
+	FormattedLabel,
+	LabelFormatter,
+	LabelFormatterFactory,
+	LegendShape as LegendShapeType,
+} from '../../types';
+
+export type LegendProps<Scale extends AnyD3Scale> = {
+	/** Optional render function override. */
+	children?: (labels: FormattedLabel<ScaleInput<Scale>, ReturnType<Scale>>[]) => ReactNode;
+	/** Classname to be applied to legend container. */
+	className?: string;
+	/** Styles to be applied to the legend container. */
+	style?: CSSProperties;
+	/** Legend domain. */
+	domain?: ScaleInput<Scale>[];
+	/** Width of the legend shape. */
+	shapeWidth?: string | number;
+	/** Height of the legend shape. */
+	shapeHeight?: string | number;
+	/** Margin of the legend shape. */
+	shapeMargin?: string | number;
+	/** Flex-box alignment of legend item labels. */
+	labelAlign?: string;
+	/** `@octanejs/visx/scale` or `d3-scale` object used to generate the legend items. */
+	scale: Scale;
+	/** Flex-box flex of legend item labels. */
+	labelFlex?: string | number;
+	/** Margin of legend item labels. */
+	labelMargin?: string | number;
+	/** Margin of legend items. */
+	itemMargin?: string | number;
+	/** Flex direction of the legend itself. */
+	direction?: FlexDirection;
+	/** Flex direction of legend items. */
+	itemDirection?: FlexDirection;
+	/** Legend item fill accessor function. */
+	fill?: (label: FormattedLabel<ScaleInput<Scale>, ReturnType<Scale>>) => string | undefined;
+	/** Legend item size accessor function. */
+	size?: (label: FormattedLabel<ScaleInput<Scale>, ReturnType<Scale>>) => | string
+	| number
+	| undefined;
+	/** Legend shape string preset or Element or Component. */
+	shape?: LegendShapeType<ScaleInput<Scale>, ReturnType<Scale>>;
+	/** Styles applied to legend shapes. */
+	shapeStyle?: (label: FormattedLabel<ScaleInput<Scale>, ReturnType<Scale>>) => CSSProperties;
+	/** Given a legend item and its index, returns an item label. */
+	labelFormat?: LabelFormatter<ScaleInput<Scale>>;
+	/** Given the legend scale and labelFormatter, returns a label with datum, index, value, and label. */
+	labelTransform?: LabelFormatterFactory<Scale>;
+	/** Additional props to be set on LegendLabel. */
+	legendLabelProps?: Partial<LegendLabelProps>;
+};
+
+const defaultStyle = {
+	display: 'flex',
+};
+
+export default function Legend<Scale extends AnyD3Scale>({
+	className,
+	style = defaultStyle,
+	scale,
+	shape,
+	domain: inputDomain,
+	fill = valueOrIdentityString,
+	size = valueOrIdentityString,
+	labelFormat = valueOrIdentity,
+	labelTransform = labelTransformFactory,
+	shapeWidth = 15,
+	shapeHeight = 15,
+	shapeMargin = '2px 4px 2px 0',
+	shapeStyle,
+	labelAlign = 'left',
+	labelFlex = '1',
+	labelMargin = '0 4px',
+	itemMargin = '0',
+	direction = 'column',
+	itemDirection = 'row',
+	legendLabelProps,
+	children,
+	...legendItemProps
+}: LegendProps<Scale>) {
+	// `Scale extends ScaleType` constraint is tricky
+	//  could consider removing `scale` altogether in the future and making `domain: Datum[]` required
+	const domain = inputDomain || ('domain' in scale ? scale.domain() : []);
+	const labelFormatter = labelTransform({ scale, labelFormat });
+	const labels = domain.map(labelFormatter);
+	if (children) return <>
+		{children(labels)}
+	</>;
+	const legendItems = labels.map(
+		(label, i) => createElement(
+			LegendItem,
+			{
+				key: `legend-${label.text}-${i}`,
+				margin: itemMargin,
+				flexDirection: itemDirection,
+				...legendItemProps,
+			},
+			createElement(LegendShape, {
+				shape,
+				height: shapeHeight,
+				width: shapeWidth,
+				margin: shapeMargin,
+				item: domain[i],
+				itemIndex: i,
+				label,
+				fill,
+				size,
+				shapeStyle,
+			}),
+			createElement(LegendLabel, {
+				label: label.text,
+				flex: labelFlex,
+				margin: labelMargin,
+				align: labelAlign,
+				...legendLabelProps,
+			}),
+		),
+	);
+
+	return <div
+		className={cx('visx-legend', className)}
+		style={{
+			...style,
+			flexDirection: direction,
+		}}
+	>{legendItems}</div>;
+}