@torpor/ui 0.4.0 → 1.0.0

package/dist/Charts/BarChart.torp

@@ -1,159 +1,70 @@
 import type { ClassValue, StyleValue } from "@torpor/view";
-import XAxis from "./XAxis.torp";
-import YAxis from "./YAxis.torp";
-import GridLines from "./GridLines.torp";
-import {
-	calculateMaxValue,
-	calculateStepValue,
-	calculateStepLabels,
-	calculateItemWidth,
-	calculateValueHeight,
-	calculateChartBottom,
-	calculateChartLeft
-} from "../utils/chartUtils";
-import { chartColors } from "../utils/chartColors";
-
+import Chart from "./Chart.torp";
+import ChartBars from "./ChartBars.torp";
+import ChartXAxis from "./ChartXAxis.torp";
+import ChartGrid from "./ChartGrid.torp";
+import ChartYAxis from "./ChartYAxis.torp";
 import type DataSeries from "./DataSeries";
 
 interface BarChartProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
-	series: DataSeries[],
-	height?: number,
-	width?: number,
-	xLabel?: string,
-	yLabel?: string,
-	maxValue?: number,
-	stepCount?: number,
-	stepValue?: number,
-	hideXAxis?: boolean,
-	hideYAxis?: boolean,
-	showHLines?: boolean,
-	showVLines?: boolean,
+	style?: StyleValue;
+	/** An ARIA label describing the chart for screen readers */
+	ariaLabel?: string;
+	series: DataSeries[];
+	height?: number;
+	width?: number;
+	xLabel?: string;
+	yLabel?: string;
+	maxValue?: number;
+	stepCount?: number;
+	stepValue?: number;
+	showHLines?: boolean;
+	showVLines?: boolean;
 }
 
+/**
+ * A bar chart: one thick horizontal bar per series, drawn from the left
+ * edge towards its first value, with category labels down the side and the
+ * value scale along the bottom.
+ *
+ * This is a preset over the layered chart components:
+ *
+ * ```
+ * <Chart>
+ * 	<ChartYAxis />
+ * 	<ChartGrid />
+ * 	<ChartXAxis />
+ * 	<ChartBars />
+ * </Chart>
+ * ```
+ *
+ * For a vertical column per value, use ColumnChart instead.
+ */
 export default function BarChart($props: BarChartProps) {
-	const defaultHeight = 200;
-	const defaultWidth = 400;
-
-	let container: HTMLElement;
-	let measurer: SVGTextElement;
-
-	let $state = $watch({
-		textWidth: 0,
-		textHeight: 0,
-		get labels() {
-			return $props.series.map((s) => s.name);
-		},
-		get calculatedHeight() { 
-			return $props.height || defaultHeight;
-		},
-		get calculatedWidth() { 
-			return $props.width || container?.clientWidth || defaultWidth;
-		},
-		get maxValue () {
-			return $props.maxValue || calculateMaxValue($props.series);
-		},
-		get calculatedStepValue() {
-			return $props.stepValue || calculateStepValue($state.maxValue, $props.stepCount);
-		},
-		get stepLabels() {
-			return calculateStepLabels($props.stepCount || 2, $state.calculatedStepValue);
-		},
-		get itemWidth() {
-			return calculateItemWidth($state.calculatedWidth, $state.chartLeft, $state.labels);
-		},
-		get valueHeight() {
-			return calculateValueHeight($state.chartBottom, $state.textHeight, $state.calculatedStepValue, $props.stepCount || 2);
-		},
-		get chartBottom() {
-			return calculateChartBottom($props.xLabel ?? "", $state.calculatedHeight, $state.textHeight);
-		},
-		get chartLeft() {
-			return calculateChartLeft($state.stepLabels, $props.yLabel ?? "", $state.textHeight, $state.textWidth);
-		}
-	});
-
-	$mount(() => {
-		// HACK: Wait until the measurer is really available
-		setTimeout(() => {
-			const bbox = measurer.getBBox();
-			$state.textWidth = bbox.width;
-			$state.textHeight = bbox.height * 1.5;
-			measurer.remove();
-		}, 1);
-	});
-
 	@render {
-		<div
-			{$props?.id}
-			class={["torp-bar-chart", $props?.class]}
-			{$props?.style}
-			&ref={container}
+		<Chart
+			id={$props.id}
+			class={["torp-bar-chart", $props.class]}
+			style={$props.style}
+			ariaLabel={$props.ariaLabel}
+			series={$props.series}
+			height={$props.height}
+			width={$props.width}
+			xLabel={$props.xLabel}
+			yLabel={$props.yLabel}
+			maxValue={$props.maxValue}
+			stepCount={$props.stepCount}
+			stepValue={$props.stepValue}
 		>
-			<svg version="1.1" width={$state.calculatedWidth} height={$state.calculatedHeight} xmlns="http://www.w3.org/2000/svg">
-				<g>
-				 	<text &ref={measurer} x="-999" y="-999">8</text>
-	
-					@if ($state.textWidth && $state.textHeight) {
-						<XAxis
-							showAxis={!$props.hideXAxis}
-							height={$state.calculatedHeight}
-							width={$state.calculatedWidth}
-							{$state.itemWidth}
-							{$state.textHeight}
-							xLabel={$props.xLabel ?? ""}
-							stepLabels={[]}
-							stepValue={0}
-							{$state.labels}
-							{$state.chartLeft}
-							{$state.chartBottom}
-						/>
-						<YAxis
-							showAxis={!$props.hideYAxis}
-							{$state.valueHeight}
-							{$state.textHeight}
-							yLabel={$props.yLabel ?? ""}
-							{$state.stepLabels}
-							stepValue={$state.calculatedStepValue}
-							{$state.chartLeft}
-							{$state.chartBottom}
-						/>
-						<GridLines
-							{$props.showHLines}
-							{$props.showVLines}
-							width={$state.calculatedWidth}
-							{$state.labels}
-							xStepValue={0}
-							xStepLabels={[]}
-							yStepValue={$state.calculatedStepValue}
-							yStepLabels={$state.stepLabels}
-							{$state.itemWidth}
-							{$state.valueHeight}
-							{$state.chartLeft}
-							{$state.chartBottom}
-							type="bar"
-						/>
-						@for (let [i, series] of $props.series.entries()) {
-							<rect
-								x={$state.chartLeft +
-									i * $state.itemWidth +
-									$state.itemWidth / 4}
-								y={$state.chartBottom - Math.max(1, series.data[0] * $state.valueHeight)}
-								width={Math.max(1, $state.itemWidth / 2)}
-								height={Math.max(1, series.data[0] * $state.valueHeight)}
-								fill={series.color || chartColors[i % chartColors.length]}
-							>
-								<title>{`${[series.name, series.data[0]].filter(Boolean).join("\n")}`}</title>
-							</rect>
-						}
-					}
-				</g>
-			</svg>
-		</div>
+			<ChartYAxis />
+			<ChartGrid hLines={$props.showHLines === true} vLines={$props.showVLines === true} />
+			<ChartXAxis />
+			<ChartBars />
+		</Chart>
 	}
 }

package/dist/Charts/Chart.torp

@@ -0,0 +1,120 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import { chartColors } from "../utils/chartColors";
+import { createChartLayout, measureChartText, type ChartLayout } from "../utils/chartLayout";
+import type DataSeries from "./DataSeries";
+import { type ChartContext, ChartContextName } from "./ChartTypes";
+
+interface ChartProps {
+	/** An ID for the root element */
+	id?: string;
+	/** Classes for the root element */
+	class?: ClassValue;
+	/** Styles for the root element */
+	style?: StyleValue;
+	/** An ARIA label describing the chart for screen readers */
+	ariaLabel?: string;
+	/** The series that layers draw from (layers reference them by index) */
+	series: DataSeries[];
+	/** Fixed height in pixels (default 200) */
+	height?: number;
+	/** Fixed width in pixels (default: fills the container, minimum 400) */
+	width?: number;
+	/** Label under the x axis */
+	xLabel?: string;
+	/** Label beside the y axis */
+	yLabel?: string;
+	/** The value at the top of the value axis, instead of the series' maximum */
+	maxValue?: number;
+	/** The number of steps between 0 and the maximum value (default 2) */
+	stepCount?: number;
+	/** The size of each step, instead of being calculated */
+	stepValue?: number;
+}
+
+/**
+ * A container for layered chart components. It measures its text, works out
+ * the plot geometry and provides it to whatever axes, grid lines and marks
+ * are slotted inside:
+ *
+ * ```
+ * <Chart ariaLabel="Revenue" series={revenue}>
+ * 	<ChartYAxis side="right" />
+ * 	<ChartGrid />
+ * 	<ChartXAxis />
+ * 	<ChartColumns />
+ * 	<ChartLines seriesIndex={1} showPoints />
+ * </Chart>
+ * ```
+ *
+ * Layers can be mixed freely -- columns with a line overlaid, an axis on
+ * either side, only a y axis with no x axis -- so a preset like LineChart is
+ * just one such combination.
+ *
+ * See also the ready-made presets: BarChart, ColumnChart, LineChart,
+ * ScatterChart.
+ */
+export default function Chart($props: ChartProps | undefined) {
+	let container: HTMLElement;
+	let measurer: SVGTextElement;
+
+	const $layout = createChartLayout({
+		series: () => $props?.series ?? [],
+		height: () => $props?.height,
+		width: () => $props?.width,
+		xLabel: () => $props?.xLabel,
+		yLabel: () => $props?.yLabel,
+		maxValue: () => $props?.maxValue,
+		stepCount: () => $props?.stepCount,
+		stepValue: () => $props?.stepValue,
+		getContainer: () => container,
+	});
+
+	$onmount(() => {
+		// HACK: Wait until the measurer is really available
+		setTimeout(() => measureChartText($layout, measurer), 1);
+	});
+
+	function colorAt(i: number): string {
+		const series = $props?.series[i];
+		return series?.color || chartColors[i % chartColors.length];
+	}
+
+	let $chartState = $watch({
+		horizontal: false,
+	});
+
+	const context: ChartContext = {
+		layout: $layout as unknown as ChartLayout,
+		series: () => $props?.series ?? [],
+		xLabel: () => $props?.xLabel ?? "",
+		yLabel: () => $props?.yLabel ?? "",
+		horizontal: () => $chartState.horizontal,
+		registerMark: (orientation) => {
+			if (orientation === "horizontal") {
+				$chartState.horizontal = true;
+			}
+		},
+		colorAt,
+	};
+	$context[ChartContextName] = context;
+
+	@render {
+		<div {$props?.id} class={["torp-chart", $props?.class]} {$props?.style} &ref={container}>
+			<svg
+				role={$props?.ariaLabel ? "img" : undefined}
+				aria-label={$props?.ariaLabel}
+				version="1.1"
+				width={$layout.calculatedWidth}
+				height={$layout.calculatedHeight}
+			>
+				<g>
+					<text &ref={measurer} x="-999" y="-999">8</text>
+
+					@if ($layout.textWidth && $layout.textHeight) {
+						<slot />
+					}
+				</g>
+			</svg>
+		</div>
+	}
+}

package/dist/Charts/ChartBars.torp

@@ -0,0 +1,78 @@
+import { type ChartContext, ChartContextName } from "./ChartTypes";
+
+interface ChartBarsProps {
+	/**
+	 * The index of the series to draw, when the Chart has other layers
+	 * reading different series. Defaults to all series.
+	 */
+	seriesIndex?: number;
+}
+
+/**
+ * Horizontal bar marks for a Chart: one thick horizontal bar per series,
+ * drawn from the left edge of the plot towards its value.
+ *
+ * For a column per value grouped under each label, use ChartColumns --
+ * those run vertically.
+ */
+export default function ChartBars($props?: ChartBarsProps) {
+	const context = $context[ChartContextName] as ChartContext;
+	if (!context) {
+		throw new Error("This layer must be contained within a Chart");
+	}
+	const { layout, series, colorAt } = context;
+	context.registerMark("horizontal");
+
+	function indexes(): number[] {
+		if ($props?.seriesIndex !== undefined) {
+			return [$props.seriesIndex];
+		}
+		return series().map((_, i) => i);
+	}
+
+	// The vertical band each series occupies within the plot
+	function bandHeight(): number {
+		const count = Math.max(1, layout.labels.length);
+		return (layout.chartBottom - topPad()) / count;
+	}
+
+	// A little space above for breathing room, matching ChartXAxis's labels
+	function topPad(): number {
+		return layout.textHeight / 3;
+	}
+
+	function barHeight(count: number): number {
+		return Math.max(1, (bandHeight() / count) * 0.7);
+	}
+
+	function valueWidth(value: number): number {
+		const plotWidth = layout.calculatedWidth - layout.chartLeft;
+		const max = Math.max(1, layout.maxValue);
+		return Math.max(1, (value / max) * plotWidth);
+	}
+
+	function barY(i: number): number {
+		const count = series().length || 1;
+		return (
+			topPad() +
+			i * bandHeight() +
+			(bandHeight() - barHeight(count)) / 2
+		);
+	}
+
+	@render {
+		<svg>
+			@for (let i of indexes()) {
+				<rect
+					x={layout.chartLeft}
+					y={barY(i)}
+					width={valueWidth(series()[i].data[0])}
+					height={barHeight(Math.max(1, series().length))}
+					fill={colorAt(i)}
+				>
+					<title>{`${[layout.labels[i], series()[i].data[0]].filter(Boolean).join("\n")}`}</title>
+				</rect>
+			}
+		</svg>
+	}
+}

package/dist/Charts/ChartColumns.torp

@@ -0,0 +1,66 @@
+import { type ChartContext, ChartContextName } from "./ChartTypes";
+
+interface ChartColumnsProps {
+	/**
+	 * The index of the series to draw, when the Chart has other layers
+	 * reading different series. Defaults to all series.
+	 */
+	seriesIndex?: number;
+}
+
+/**
+ * Vertical column marks for a Chart: every value in the chosen series is
+ * drawn as a vertical column, grouped under its label.
+ *
+ * For one thick bar per series, use ChartBars -- those run horizontally.
+ */
+export default function ChartColumns($props?: ChartColumnsProps) {
+	const context = $context[ChartContextName] as ChartContext;
+	if (!context) {
+		throw new Error("This layer must be contained within a Chart");
+	}
+	const { layout, series, colorAt } = context;
+	context.registerMark("vertical");
+
+	function indexes(): number[] {
+		if ($props?.seriesIndex !== undefined) {
+			return [$props.seriesIndex];
+		}
+		return series().map((_, i) => i);
+	}
+
+	function columnWidth(count: number): number {
+		return Math.max(1, (layout.itemWidth / count) * 0.7);
+	}
+
+	function columnGap(count: number): number {
+		return (layout.itemWidth - columnWidth(count) * count) / (count + 1);
+	}
+
+	function columnX(i: number, j: number): number {
+		return (
+			layout.chartLeft +
+			i * layout.itemWidth +
+			columnGap(series()[i].data.length) +
+			j * columnWidth(series()[i].data.length)
+		);
+	}
+
+	@render {
+		<svg>
+			@for (let i of indexes()) {
+				@for (let [j, value] of series()[i].data.entries()) {
+					<rect
+						x={columnX(i, j)}
+						y={layout.chartBottom - Math.max(1, value * layout.valueHeight)}
+						width={columnWidth(series()[i].data.length)}
+						height={Math.max(1, value * layout.valueHeight)}
+						fill={colorAt(i)}
+					>
+						<title>{`${[layout.labels[i], value].filter(Boolean).join("\n")}`}</title>
+					</rect>
+				}
+			}
+		</svg>
+	}
+}

package/dist/Charts/ChartGrid.torp

@@ -0,0 +1,54 @@
+import { type ChartContext, ChartContextName } from "./ChartTypes";
+
+interface ChartGridProps {
+	/** Horizontal lines across the plot at each value step (default true) */
+	hLines?: boolean;
+	/** Vertical lines at each category slot (default false) */
+	vLines?: boolean;
+}
+
+/**
+ * Grid lines for a Chart: horizontal lines at each value step and/or
+ * vertical lines through each category slot.
+ */
+export default function ChartGrid($props?: ChartGridProps) {
+	const context = $context[ChartContextName] as ChartContext;
+	if (!context) {
+		throw new Error("This layer must be contained within a Chart");
+	}
+	const { layout } = context;
+
+	function hLines(): boolean {
+		return $props?.hLines !== false;
+	}
+	function vLines(): boolean {
+		return $props?.vLines === true;
+	}
+
+	@render {
+		<svg>
+			@if (hLines()) {
+				@for (let [i] of layout.stepLabels.entries()) {
+					<line
+						x1={layout.chartLeft}
+						y1={layout.chartBottom - i * layout.stepValue * layout.valueHeight}
+						x2={layout.calculatedWidth}
+						y2={layout.chartBottom - i * layout.stepValue * layout.valueHeight}
+						stroke="currentcolor"
+					/>
+				}
+			}
+			@if (vLines()) {
+				@for (let [i] of layout.labels.entries()) {
+					<line
+						x1={layout.chartLeft + i * layout.itemWidth + layout.itemWidth / 2}
+						y1={layout.chartBottom}
+						x2={layout.chartLeft + i * layout.itemWidth + layout.itemWidth / 2}
+						y2={0}
+						stroke="currentcolor"
+					/>
+				}
+			}
+		</svg>
+	}
+}

package/dist/Charts/ChartLines.torp

@@ -0,0 +1,60 @@
+import { type ChartContext, ChartContextName } from "./ChartTypes";
+import type DataSeries from "./DataSeries";
+
+interface ChartLinesProps {
+	/** The index of the series to draw (default 0) */
+	seriesIndex?: number;
+	/** The color to draw with, instead of the series' own */
+	color?: string;
+	/** Draws a point at each value (default false) */
+	showPoints?: boolean;
+}
+
+/**
+ * Line marks for a Chart: draws the chosen series as a connected line
+ * across the category slots.
+ *
+ * Add alongside ChartColumns or ChartBars for overlaid layers -- or use two
+ * ChartLines with different `seriesIndex` to compare series.
+ */
+export default function ChartLines($props?: ChartLinesProps) {
+	const context = $context[ChartContextName] as ChartContext;
+	if (!context) {
+		throw new Error("This layer must be contained within a Chart");
+	}
+	const { layout, series, colorAt } = context;
+	context.registerMark("vertical");
+
+	function index(): number {
+		return $props?.seriesIndex ?? 0;
+	}
+
+	function current(): DataSeries | undefined {
+		return series()[index()];
+	}
+
+	function points(): { x: number; y: number }[] {
+		const data = current()?.data ?? [];
+		return data.map((value, j) => ({
+			x: +(layout.chartLeft + j * layout.itemWidth + layout.itemWidth / 2).toFixed(2),
+			y: +(layout.chartBottom - value * layout.valueHeight).toFixed(2),
+		}));
+	}
+
+	function stroke(): string {
+		return $props?.color || colorAt(index());
+	}
+
+	@render {
+		<svg>
+			<polyline points={points().map((p) => `${p.x},${p.y}`).join(" ")} stroke={stroke()} stroke-width="2" fill="none" />
+			@if ($props?.showPoints) {
+				@for (let [j, point] of points().entries()) {
+					<circle cx={point.x} cy={point.y} r="4" stroke={stroke()} stroke-width="2" fill="white">
+						<title>{`${[current()?.name, layout.labels[j], current()?.data[j]].filter(Boolean).join("\n")}`}</title>
+					</circle>
+				}
+			}
+		</svg>
+	}
+}

package/dist/Charts/ChartTypes.ts

@@ -0,0 +1,25 @@
+import type DataSeries from "./DataSeries";
+import { type ChartLayout } from "../utils/chartLayout";
+
+export const ChartContextName: unique symbol = Symbol.for("torp.Chart");
+
+/**
+ * The shared context for layered chart components (ChartXAxis, ChartYAxis,
+ * ChartGrid, ChartColumns etc), published by the Chart container.
+ */
+export interface ChartContext {
+	/** The plot geometry: margins, scales and derived positions */
+	layout: ChartLayout;
+	/** The series that layers draw from */
+	series: () => DataSeries[];
+	/** The label under the x axis, if any */
+	xLabel: () => string;
+	/** The label beside the y axis, if any */
+	yLabel: () => string;
+	/** Whether the chart draws horizontal marks (bars), set by the mark layers */
+	horizontal: () => boolean;
+	/** Called by mark layers to announce their orientation */
+	registerMark: (orientation: "horizontal" | "vertical") => void;
+	/** The color to draw series i with, from its own color or the palette */
+	colorAt: (i: number) => string;
+}