@torpor/ui 0.3.7 → 1.0.0

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;
+}

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>
+	}
+}