@torpor/ui 0.4.0 → 1.0.0

package/dist/Charts/ChartXAxis.torp

@@ -0,0 +1,83 @@
+import { type ChartContext, ChartContextName } from "./ChartTypes";
+
+interface ChartXAxisProps {
+	/** Whether to draw the axis line itself (default true) */
+	showAxis?: boolean;
+	/** An axis title, overriding the Chart's x label */
+	label?: string;
+}
+
+/**
+ * The x axis for a chart. For vertical marks (columns, lines) it runs along
+ * the bottom with each series' label centered under its slot; for
+ * horizontal marks (bars) it becomes the value scale, with a tick for each
+ * step along the bottom.
+ */
+export default function ChartXAxis($props?: ChartXAxisProps) {
+	const context = $context[ChartContextName] as ChartContext;
+	if (!context) {
+		throw new Error("ChartXAxis must be contained within a Chart");
+	}
+	const { layout, xLabel, horizontal } = context;
+
+	function showAxis(): boolean {
+		return $props?.showAxis !== false;
+	}
+
+	function title(): string {
+		if ($props?.label !== undefined) return $props.label;
+		return xLabel();
+	}
+
+	function plotWidth(): number {
+		return layout.calculatedWidth - layout.chartLeft;
+	}
+
+	function unitWidth(): number {
+		return plotWidth() / Math.max(1, layout.maxValue);
+	}
+
+	function tickX(i: number): number {
+		return layout.chartLeft + i * layout.stepValue * unitWidth();
+	}
+
+	function tickY(): number {
+		return layout.calculatedHeight - layout.textHeight / 3;
+	}
+
+	@render {
+		<svg>
+			@if (showAxis()) {
+				<line x1={layout.chartLeft} y1={layout.chartBottom} x2={layout.calculatedWidth} y2={layout.chartBottom} stroke="currentcolor" />
+			}
+			@if (!horizontal()) {
+				@if (title()) {
+					<text
+						text-anchor="middle"
+						dominant-baseline="text-after-edge"
+						x={layout.calculatedWidth - (layout.calculatedWidth - layout.chartLeft) / 2}
+						y={layout.calculatedHeight}
+					>
+						{title()}
+					</text>
+				}
+				@for (let [i, label] of layout.labels.entries()) {
+					<text
+						text-anchor="middle"
+						dominant-baseline="text-after-edge"
+						x={layout.chartLeft + layout.itemWidth * i + layout.itemWidth / 2}
+						y={tickY()}
+					>
+						{label}
+					</text>
+				}
+			} else {
+				@for (let [i, label] of layout.stepLabels.entries()) {
+					<text text-anchor="middle" dominant-baseline="text-after-edge" x={tickX(i)} y={tickY()}>
+						{label}
+					</text>
+				}
+			}
+		</svg>
+	}
+}

package/dist/Charts/ChartYAxis.torp

@@ -0,0 +1,105 @@
+import { type ChartContext, ChartContextName } from "./ChartTypes";
+
+interface ChartYAxisProps {
+	/** Whether to draw the axis line itself (default true) */
+	showAxis?: boolean;
+	/** Which side of the plot the value scale runs on (default "left") */
+	side?: "left" | "right";
+	/** An axis title, overriding the Chart's y label */
+	label?: string;
+}
+
+/**
+ * The y axis for a chart. For vertical marks (columns, lines) it is the
+ * value scale -- a line down the `side` edge with a tick for each step
+ * between 0 and the maximum value. For horizontal marks (bars) it carries
+ * the category labels, one per band down the left.
+ *
+ * Drawing it on either side does not change the plot geometry; overlaying
+ * an axis is purely presentational.
+ */
+export default function ChartYAxis($props?: ChartYAxisProps) {
+	const context = $context[ChartContextName] as ChartContext;
+	if (!context) {
+		throw new Error("ChartYAxis must be contained within a Chart");
+	}
+	const { layout, yLabel, horizontal } = context;
+
+	function showAxis(): boolean {
+		return $props?.showAxis !== false;
+	}
+
+	function side(): "left" | "right" {
+		return $props?.side ?? "left";
+	}
+
+	function title(): string {
+		if ($props?.label !== undefined) return $props.label;
+		return yLabel();
+	}
+
+	function bandHeight(): number {
+		const count = Math.max(1, layout.labels.length);
+		return (layout.chartBottom - topPad()) / count;
+	}
+
+	function topPad(): number {
+		return layout.textHeight / 3;
+	}
+
+	function bandCenter(i: number): number {
+		return topPad() + i * bandHeight() + bandHeight() / 2;
+	}
+
+	function axisX(): number {
+		return side() === "left" ? layout.chartLeft : layout.calculatedWidth;
+	}
+
+	function tickX(): number {
+		if (side() === "left") {
+			return layout.chartLeft - layout.textHeight / 4;
+		}
+		return layout.calculatedWidth + layout.textHeight / 4;
+	}
+
+	function anchor(): string {
+		return side() === "left" ? "end" : "start";
+	}
+
+	@render {
+		<svg>
+			@if (showAxis()) {
+				<line x1={axisX()} y1={layout.chartBottom} x2={axisX()} y2={0} stroke="currentcolor" />
+			}
+			@if (horizontal()) {
+				@for (let [i, label] of layout.labels.entries()) {
+					<text
+						text-anchor="end"
+						dominant-baseline="middle"
+						x={layout.chartLeft - layout.textHeight / 4}
+						y={bandCenter(i)}
+					>
+						{label}
+					</text>
+				}
+			} else {
+				@if (side() === "left" && title()) {
+					<text
+						text-anchor="middle"
+						dominant-baseline="hanging"
+						x={0}
+						y={layout.chartBottom / 2}
+						transform={`rotate(-90, 0, ${layout.chartBottom / 2})`}
+					>
+						{title()}
+					</text>
+				}
+				@for (let [i, label] of layout.stepLabels.entries()) {
+					<text text-anchor={anchor()} dominant-baseline="middle" x={tickX()} y={layout.chartBottom - i * layout.stepValue * layout.valueHeight}>
+						{label}
+					</text>
+				}
+			}
+		</svg>
+	}
+}

package/dist/Charts/ColumnChart.torp

@@ -0,0 +1,70 @@
+import type { ClassValue, StyleValue } from "@torpor/view";
+import Chart from "./Chart.torp";
+import ChartXAxis from "./ChartXAxis.torp";
+import ChartColumns from "./ChartColumns.torp";
+import ChartGrid from "./ChartGrid.torp";
+import ChartYAxis from "./ChartYAxis.torp";
+import type DataSeries from "./DataSeries";
+
+interface ColumnChartProps {
+	/** 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;
+	series: DataSeries[];
+	height?: number;
+	width?: number;
+	xLabel?: string;
+	yLabel?: string;
+	maxValue?: number;
+	stepCount?: number;
+	stepValue?: number;
+	showHLines?: boolean;
+	showVLines?: boolean;
+}
+
+/**
+ * A column chart: each value in each series is drawn as a vertical column,
+ * grouped under the series' label along the bottom axis.
+ *
+ * This is a preset over the layered chart components:
+ *
+ * ```
+ * <Chart>
+ * 	<ChartValueAxis />
+ * 	<ChartGrid />
+ * 	<ChartXAxis />
+ * 	<ChartColumns />
+ * </Chart>
+ * ```
+ *
+ * Compose those directly to customize -- e.g. the value axis on the right,
+ * or a line overlaid with ChartLines.
+ */
+export default function ColumnChart($props: ColumnChartProps) {
+	@render {
+		<Chart
+			{$props?.id}
+			class={["torp-column-chart", $props?.class]}
+			{$props?.style}
+			{$props?.ariaLabel}
+			{$props?.series}
+			{$props?.height}
+			{$props?.width}
+			{$props?.xLabel}
+			{$props?.yLabel}
+			{$props?.maxValue}
+			{$props?.stepCount}
+			{$props?.stepValue}
+		>
+			<ChartYAxis />
+			<ChartGrid hLines={$props.showHLines === true} vLines={$props.showVLines === true} />
+			<ChartXAxis />
+			<ChartColumns />
+		</Chart>
+	}
+}

package/dist/Charts/GridLines.torp

@@ -4,11 +4,11 @@ interface GridLinesProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
-	showHLines?: boolean,
-	showVLines?: boolean,
+	style?: StyleValue;
+	showHLines?: boolean;
+	showVLines?: boolean;
 	width: number;
 	labels: string[];
 	xStepValue: number;

package/dist/Charts/LineChart.torp

@@ -1,196 +1,73 @@
 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 ChartXAxis from "./ChartXAxis.torp";
+import ChartGrid from "./ChartGrid.torp";
+import ChartLines from "./ChartLines.torp";
+import ChartYAxis from "./ChartYAxis.torp";
 import type DataSeries from "./DataSeries";
 
 interface LineChartProps {
 	/** 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,
-	showPoints?: boolean,
-	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;
+	showPoints?: boolean;
+	showHLines?: boolean;
+	showVLines?: boolean;
 }
 
+/**
+ * A line chart: each series drawn as a connected line across the category
+ * slots.
+ *
+ * This is a preset over the layered chart components:
+ *
+ * ```
+ * <Chart>
+ * 	<ChartValueAxis />
+ * 	<ChartGrid />
+ * 	<ChartXAxis />
+ * 	<ChartLines seriesIndex={0} />
+ * </Chart>
+ * ```
+ *
+ * Compose those directly for overlaid layers (columns plus a line, multiple
+ * separately-indexed lines etc).
+ */
 export default function LineChart($props: LineChartProps) {
-	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);
-		},
-		get pointSeries() {
-			return buildPointSeries(
-				$props.series,
-				$state.chartLeft,
-				$state.chartBottom,
-				$state.itemWidth,
-				$state.valueHeight
-			);
-		}
-	});
-
-	$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);
-	});
-
-	function buildPointSeries(
-		theSeries: DataSeries[],
-		theChartLeft: number,
-		theChartBottom: number,
-		theItemWidth: number,
-		theValueHeight: number
-	): { x: number; y: number }[][] {
-		return theSeries.map((series) => {
-			return series.data.map((value, i) => {
-				const x = +(theChartLeft + i * theItemWidth + theItemWidth / 2).toFixed(2);
-				const y = +(theChartBottom - value * theValueHeight).toFixed(2);
-				return { x, y };
-			});
-		});
-	}
-
 	@render {
-		<div
+		<Chart
 			{$props?.id}
 			class={["torp-line-chart", $props?.class]}
 			{$props?.style}
-			&ref={container}
+			{$props?.ariaLabel}
+			{$props?.series}
+			{$props?.height}
+			{$props?.width}
+			{$props?.xLabel}
+			{$props?.yLabel}
+			{$props?.maxValue}
+			{$props?.stepCount}
+			{$props?.stepValue}
 		>
-			<svg version="1.1" width={$state.calculatedWidth} height={$state.calculatedHeight}>
-				<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 ?? ""}
-							{$state.labels}
-							stepLabels={[]}
-							stepValue={0}
-							{$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="line"
-						/>
-						@for (let [i, series] of $props.series.entries()) {
-							<polyline
-								points={$state.pointSeries[i].map((p) => `${p.x},${p.y}`).join(" ")}
-								stroke={series.color || chartColors[i % chartColors.length]}
-								stroke-width="2"
-								fill="none"
-							/>
-							@if ($props.showPoints) {
-								@for (let [j, point] of $state.pointSeries[i].entries()) {
-									<circle
-										cx={point.x}
-										cy={point.y}
-										r="4"
-										stroke={series.color || chartColors[i % chartColors.length]}
-										stroke-width="2"
-										fill="white"
-									>
-										<title>{`${[series.name, $state.labels[j], series.data[j]].filter(Boolean).join("\n")}`}</title>
-									</circle>
-								}
-							}
-						}
-					}
-				</g>
-			</svg>
-		</div>
+			<ChartYAxis />
+			<ChartGrid hLines={$props.showHLines === true} vLines={$props.showVLines === true} />
+			<ChartXAxis />
+			@for (let i of $props.series.map((_, i) => i)) {
+				<ChartLines seriesIndex={i} showPoints={$props.showPoints} />
+			}
+		</Chart>
 	}
 }

package/dist/Charts/PieChart.torp

@@ -18,13 +18,15 @@ interface PieChartProps {
 	/** An ID for the root element */
 	id?: string;
 	/** Classes for the root element */
-	class?: ClassValue,
+	class?: ClassValue;
 	/** Styles for the root element */
-	style?: StyleValue,
-	data: PieData[],
-	size?: number,
-	radius?: number,
-	cutout?: number,
+	style?: StyleValue;
+	/** An ARIA label describing the chart for screen readers */
+	ariaLabel?: string;
+	data: PieData[];
+	size?: number;
+	radius?: number;
+	cutout?: number;
 }
 
 export default function PieChart($props: PieChartProps) {
@@ -42,14 +44,14 @@ export default function PieChart($props: PieChartProps) {
 		},
 		get segments() {
 			return buildSegments($props.size!, $props.data, $props.radius!, $props.cutout!);
-		}
+		},
 	});
 
 	function buildSegments(
 		theSize: number,
 		theData: PieData[],
 		theRadiusSize: number,
-		theCutoutSize: number
+		theCutoutSize: number,
 	): SegmentData[] {
 		const segments = [];
 		const x = theSize / 2;
@@ -67,7 +69,7 @@ export default function PieChart($props: PieChartProps) {
 				name: theData[i].name,
 				value: theData[i].value,
 				color: theData[i].color,
-				path: buildPath(x, y, theRadiusSize, theCutoutSize, startAngle, endAngle, largeArc)
+				path: buildPath(x, y, theRadiusSize, theCutoutSize, startAngle, endAngle, largeArc),
 			});
 			startAngle = endAngle;
 		}
@@ -81,7 +83,7 @@ export default function PieChart($props: PieChartProps) {
 		theCutoutSize: number,
 		startAngle: number,
 		endAngle: number,
-		largeArc: number
+		largeArc: number,
 	): string {
 		// HACK: Drawing an arc of 360 degrees doesn't work
 		if (startAngle - endAngle === 360) {
@@ -122,16 +124,8 @@ A${theCutoutSize},${theCutoutSize} 0 ${largeArc} 0 ${cutoutstartx},${cutoutstart
 	}
 
 	@render {
-		<div
-			{$props?.id}
-			class={["torp-pie-chart", $props?.class]}
-			{$props?.style}
-		>
-			<svg
-				version="1.1"
-				width={$props.size}
-				height={$props.size}
-			>
+		<div {$props?.id} class={["torp-pie-chart", $props?.class]} {$props?.style}>
+			<svg role={$props?.ariaLabel ? "img" : undefined} aria-label={$props?.ariaLabel} version="1.1" width={$props.size} height={$props.size}>
 				<g>
 					@for (let [i, segment] of $state.segments.entries()) {
 						<path d={segment.path} fill={segment.color || chartColors[i % chartColors.length]}>