@voila.dev/chart 4.0.107 → 4.0.109

package/src/canvas/paint-scene.ts

@@ -14,6 +14,48 @@ const CANVAS_ALIGN = {
 	end: "right",
 } as const satisfies Record<string, CanvasTextAlign>;
 
+const HATCH_STEP = 6;
+const hatchCache = new WeakMap<
+	CanvasRenderingContext2D,
+	Map<string, CanvasPattern | string>
+>();
+
+/** Diagonal lines every few pixels in the colour, as the SVG pattern draws them. */
+function hatchPattern(
+	context: CanvasRenderingContext2D,
+	color: string,
+): CanvasPattern | string {
+	const cache =
+		hatchCache.get(context) ?? new Map<string, CanvasPattern | string>();
+	hatchCache.set(context, cache);
+	const cached = cache.get(color);
+	if (cached !== undefined) {
+		return cached;
+	}
+	const tile = document.createElement("canvas");
+	tile.width = HATCH_STEP;
+	tile.height = HATCH_STEP;
+	const pen = tile.getContext("2d");
+	if (pen === null) {
+		return color;
+	}
+	pen.strokeStyle = color;
+	pen.lineWidth = 1.5;
+	pen.beginPath();
+	// One diagonal across the tile, plus the two corner stubs that join it to
+	// the neighbouring tiles' lines.
+	pen.moveTo(0, HATCH_STEP);
+	pen.lineTo(HATCH_STEP, 0);
+	pen.moveTo(-1, 1);
+	pen.lineTo(1, -1);
+	pen.moveTo(HATCH_STEP - 1, HATCH_STEP + 1);
+	pen.lineTo(HATCH_STEP + 1, HATCH_STEP - 1);
+	pen.stroke();
+	const pattern = context.createPattern(tile, "repeat") ?? color;
+	cache.set(color, pattern);
+	return pattern;
+}
+
 function dashes(dasharray: string | undefined): number[] {
 	if (!dasharray) {
 		return [];
@@ -39,7 +81,9 @@ function fillAndStroke(
 	const opacity = paint.opacity ?? 1;
 	if (paint.fill && paint.fill !== "none") {
 		context.globalAlpha = opacity * (paint.fillOpacity ?? 1);
-		context.fillStyle = resolve(paint.fill);
+		context.fillStyle = paint.hatch
+			? hatchPattern(context, resolve(paint.fill))
+			: resolve(paint.fill);
 		draw("fill");
 	}
 	if (paint.stroke && paint.stroke !== "none") {

package/src/core/marks/area.ts

@@ -11,6 +11,7 @@ import {
 	markId,
 	paint,
 	seriesResolver,
+	tips,
 } from "#/core/marks/shared.ts";
 import { stackSegments } from "#/core/marks/stack.ts";
 import { areaPath, type ChartXY, linePath } from "#/core/paths.ts";
@@ -149,7 +150,7 @@ function areaMark<TDatum>(
 					const run = runs[runs.length - 1];
 					run.top.push(top);
 					run.bottom.push(place(along, edge.low));
-					if (options.tip === false) {
+					if (!tips(options.tip, data[index], index)) {
 						continue;
 					}
 					const value = explicit ? edge.high : (values[index] ?? 0);

package/src/core/marks/bar.ts

@@ -10,6 +10,7 @@ import {
 	markId,
 	paint,
 	seriesResolver,
+	tips,
 } from "#/core/marks/shared.ts";
 import { stackSegments } from "#/core/marks/stack.ts";
 import { categoryKey } from "#/core/scales/discrete.ts";
@@ -40,6 +41,11 @@ export interface BarOptions<TDatum> extends ChartMarkOptions<TDatum> {
 	readonly radius?: number;
 	/** Pixels kept clear on each side of the bar inside its band. */
 	readonly inset?: number;
+	/**
+	 * Bars to draw hatched and outlined: projections, stages still in flight,
+	 * anything pencilled in rather than recorded.
+	 */
+	readonly projected?: (datum: TDatum, index: number) => boolean;
 }
 
 const DEFAULT_RADIUS = 4;
@@ -192,15 +198,26 @@ function barMark<TDatum>(
 					role: "mark",
 					...rect,
 					corners: corners(vertical, bar, radius, explicit),
-					paint: paint({
-						fill: series.color,
-						fillOpacity: options.fillOpacity,
-						stroke: options.stroke,
-						strokeDasharray: options.strokeDasharray,
-						opacity: options.opacity,
-					}),
+					paint: paint(
+						options.projected?.(data[bar.index], bar.index)
+							? {
+									fill: series.color,
+									hatch: true,
+									stroke: series.color,
+									strokeWidth: 1,
+									strokeDasharray: "3 2",
+									opacity: options.opacity,
+								}
+							: {
+									fill: series.color,
+									fillOpacity: options.fillOpacity,
+									stroke: options.stroke,
+									strokeDasharray: options.strokeDasharray,
+									opacity: options.opacity,
+								},
+					),
 				});
-				if (options.tip === false) {
+				if (!tips(options.tip, data[bar.index], bar.index)) {
 					continue;
 				}
 				const along = alongStart + alongSize / 2;

package/src/core/marks/cell.ts

@@ -6,6 +6,7 @@ import {
 	markId,
 	paint,
 	seriesResolver,
+	tips,
 	valueOn,
 } from "#/core/marks/shared.ts";
 import type {
@@ -96,7 +97,7 @@ export function cell<TDatum>(
 					corners: [radius, radius, radius, radius],
 					paint: paint({ fill: series.color, opacity: options.opacity }),
 				});
-				if (options.tip !== false) {
+				if (tips(options.tip, datum, index)) {
 					points.push({
 						key: `${id}:${index}`,
 						markId: id,

package/src/core/marks/dot.ts

@@ -10,6 +10,7 @@ import {
 	markId,
 	paint,
 	seriesResolver,
+	tips,
 	valueOn,
 } from "#/core/marks/shared.ts";
 import type {
@@ -129,7 +130,7 @@ export function dot<TDatum>(
 						opacity: options.opacity,
 					}),
 				});
-				if (options.tip !== false) {
+				if (tips(options.tip, datum, index)) {
 					points.push({
 						key: `${id}:${index}`,
 						markId: id,

package/src/core/marks/funnel.ts

@@ -11,6 +11,7 @@ import {
 	markId,
 	paint,
 	seriesResolver,
+	tips,
 } from "#/core/marks/shared.ts";
 import { categoryKey } from "#/core/scales/discrete.ts";
 import type {
@@ -133,7 +134,7 @@ export function funnel<TDatum>(
 						},
 					);
 				}
-				if (options.tip === false) {
+				if (!tips(options.tip, data[slice.index], slice.index)) {
 					continue;
 				}
 				const previous = slice.index > 0 ? values[slice.index - 1] : undefined;

package/src/core/marks/line.ts

@@ -6,6 +6,7 @@ import {
 	markId,
 	paint,
 	seriesResolver,
+	tips,
 	valueOn,
 } from "#/core/marks/shared.ts";
 import { type ChartXY, linePath } from "#/core/paths.ts";
@@ -111,7 +112,7 @@ function lineMark<TDatum>(
 						? { x: along, y: across }
 						: { x: across, y: along };
 					runs[runs.length - 1].push(xy);
-					if (options.tip !== false) {
+					if (tips(options.tip, data[index], index)) {
 						points.push({
 							key: `${id}:${index}`,
 							markId: id,

package/src/core/marks/polar.ts

@@ -10,6 +10,7 @@ import {
 	markId,
 	paint,
 	seriesResolver,
+	tips,
 } from "#/core/marks/shared.ts";
 import {
 	arcPath,
@@ -187,7 +188,7 @@ export function arc<TDatum>(
 						opacity: options.opacity,
 					}),
 				});
-				if (options.tip === false) {
+				if (!tips(options.tip, data[index], index)) {
 					continue;
 				}
 				const middle = (angle.startAngle + angle.endAngle) / 2;
@@ -307,7 +308,7 @@ export function radialBar<TDatum>(
 					d: arcPath(shape),
 					paint: paint({ fill: series.color, opacity: options.opacity }),
 				});
-				if (options.tip === false) {
+				if (!tips(options.tip, data[index], index)) {
 					continue;
 				}
 				const anchor = polarToCartesian(
@@ -512,7 +513,7 @@ export function radar<TDatum>(
 				};
 				polygon.vertices[spoke] = vertex;
 				polygons.set(series.key, polygon);
-				if (options.tip !== false) {
+				if (tips(options.tip, data[index], index)) {
 					points.push({
 						key: `${id}:${index}`,
 						markId: id,

package/src/core/marks/rect.ts

@@ -10,6 +10,7 @@ import {
 	markId,
 	paint,
 	seriesResolver,
+	tips,
 	valueOn,
 } from "#/core/marks/shared.ts";
 import { stackSegments } from "#/core/marks/stack.ts";
@@ -131,7 +132,7 @@ export function rectY<TDatum>(
 						opacity: options.opacity,
 					}),
 				});
-				if (options.tip !== false) {
+				if (tips(options.tip, data[index], index)) {
 					points.push({
 						key: `${id}:${index}`,
 						markId: id,

package/src/core/marks/rule.ts

@@ -1,8 +1,10 @@
 import { isPlaceable, readChannel } from "#/core/channel.ts";
 import { markId, paint, valueOn } from "#/core/marks/shared.ts";
+import { categoryKey } from "#/core/scales/discrete.ts";
 import type {
 	ChartAccessor,
 	ChartMark,
+	ChartPositionScale,
 	ChartValue,
 	SceneNode,
 } from "#/core/types.ts";
@@ -17,10 +19,30 @@ export interface RuleOptions<TDatum> {
 	readonly opacity?: number;
 	/** Text written at the end of the rule: "Objectif", "Moyenne". */
 	readonly label?: string;
+	/**
+	 * On a band or point axis, `before` draws the rule between the value's
+	 * column and the one before it: where a period starts, not its middle.
+	 */
+	readonly position?: "center" | "before";
 }
 
 const LABEL_GAP = 4;
 
+/** Halfway between a category's slot and the previous one's, or its own start for the first. */
+function before(scale: ChartPositionScale, value: ChartValue): number {
+	if (scale.kind !== "band" && scale.kind !== "point") {
+		return scale.center(value);
+	}
+	const index = scale.domain.findIndex(
+		(candidate) => categoryKey(candidate) === categoryKey(value),
+	);
+	const previous = scale.domain[index - 1];
+	if (index <= 0 || previous === undefined) {
+		return scale.map(value);
+	}
+	return (scale.map(previous) + scale.bandwidth + scale.map(value)) / 2;
+}
+
 function ruleMark<TDatum>(
 	kind: "ruleY" | "ruleX",
 	data: ReadonlyArray<TDatum>,
@@ -50,7 +72,10 @@ function ruleMark<TDatum>(
 				if (value === undefined) {
 					continue;
 				}
-				const at = scale.center(value);
+				const at =
+					options.position === "before"
+						? before(scale, value)
+						: scale.center(value);
 				nodes.push({
 					kind: "line",
 					key: `${id}:${index}`,

package/src/core/marks/shared.ts

@@ -22,8 +22,12 @@ export interface ChartMarkOptions<TDatum> {
 	readonly label?: string;
 	/** A field or function whose distinct values split the mark into coloured series. */
 	readonly color?: ChartAccessor<TDatum, ChartValue>;
-	/** `false` keeps the mark out of focus, tooltips and the data table. */
-	readonly tip?: boolean;
+	/**
+	 * `false` keeps the mark out of focus, tooltips and the data table; a
+	 * function decides per datum (the point where a recorded line hands over
+	 * to its dashed projection belongs to one of the two, not both).
+	 */
+	readonly tip?: boolean | ((datum: TDatum, index: number) => boolean);
 	readonly opacity?: number;
 }
 
@@ -132,3 +136,12 @@ export function valueOn(
 	}
 	return numericValue(raw);
 }
+
+/** Whether a datum takes part in focus, tooltips and the data table. */
+export function tips<TDatum>(
+	tip: ChartMarkOptions<TDatum>["tip"],
+	datum: TDatum,
+	index: number,
+): boolean {
+	return typeof tip === "function" ? tip(datum, index) : tip !== false;
+}

package/src/core/marks/stats/dodge.ts

@@ -5,6 +5,7 @@ import {
 	markId,
 	paint,
 	seriesResolver,
+	tips,
 	valueOn,
 } from "#/core/marks/shared.ts";
 import type {
@@ -109,7 +110,7 @@ export function dodgeY<TDatum>(
 					r,
 					paint: paint({ fill: series.color, opacity: options.opacity }),
 				});
-				if (options.tip !== false) {
+				if (tips(options.tip, data[entry.index], entry.index)) {
 					points.push({
 						key: `${id}:${entry.index}`,
 						markId: id,

package/src/core/marks/stats/histogram.ts

@@ -95,7 +95,8 @@ export function histogram<TDatum>(
 	return rectY(bins, {
 		id: options.id,
 		label: options.label,
-		tip: options.tip,
+		// Bins are not the caller's data: only a plain on/off carries over.
+		tip: typeof options.tip === "function" ? undefined : options.tip,
 		opacity: options.opacity,
 		fill: options.fill,
 		x1: (bin) => bin.x1,

package/src/core/marks/stats/waffle.ts

@@ -10,6 +10,7 @@ import {
 	markId,
 	paint,
 	seriesResolver,
+	tips,
 } from "#/core/marks/shared.ts";
 import { categoryKey } from "#/core/scales/discrete.ts";
 import type {
@@ -117,7 +118,7 @@ export function waffleY<TDatum>(
 						paint: paint({ fill: series.color, opacity: options.opacity }),
 					});
 				}
-				if (options.tip !== false) {
+				if (tips(options.tip, data[index], index)) {
 					points.push({
 						key: `${id}:${index}`,
 						markId: id,

package/src/core/scales/resolve.ts

@@ -111,7 +111,17 @@ export function planScale(
 		};
 	}
 	if (options?.domain !== undefined) {
-		return { kind, domain: options.domain.map(toNumber), label };
+		const [low, high] = options.domain.map(toNumber);
+		// An explicit domain still widens to round ticks when asked to: the
+		// data's own maximum as the top of the axis would end it mid-air.
+		return {
+			kind,
+			domain:
+				options.nice === true && kind === "linear"
+					? niceDomain(low, high)
+					: [low, high],
+			label,
+		};
 	}
 	const zero =
 		options?.zero ?? channels.some((channel) => channel.includeZero === true);

package/src/core/types.ts

@@ -90,6 +90,8 @@ export interface ChartPaint {
 	readonly opacity?: number;
 	readonly fillOpacity?: number;
 	readonly strokeOpacity?: number;
+	/** Fill with diagonal hatching in the fill colour: a value pencilled in, not yet true. */
+	readonly hatch?: boolean;
 }
 
 export interface ChartTextPaint extends ChartPaint {

package/src/react/chart-placeholders.tsx

@@ -0,0 +1,93 @@
+import type * as React from "react";
+
+/**
+ * Stand-ins for a chart: no data yet, or none at all. Sized like the chart
+ * they replace (pass the same height), so the page does not jump when the
+ * data lands. Styled with the kit's tokens when the page has them.
+ */
+
+const BOX: React.CSSProperties = {
+	width: "100%",
+	aspectRatio: "16 / 9",
+	borderRadius: 8,
+};
+
+interface EmptyProps extends React.ComponentProps<"div"> {}
+
+/** In place of a chart with nothing to show. Pass the localized message as children. */
+export function ChartEmpty({ style, ...props }: EmptyProps) {
+	return (
+		<div
+			data-slot="chart-empty"
+			style={{
+				...BOX,
+				display: "flex",
+				flexDirection: "column",
+				alignItems: "center",
+				justifyContent: "center",
+				gap: 4,
+				border:
+					"1px dashed var(--border, color-mix(in oklab, currentColor 25%, transparent))",
+				color: "var(--muted-foreground, inherit)",
+				fontSize: 14,
+				textAlign: "center",
+				textWrap: "balance",
+				...style,
+			}}
+			{...props}
+		/>
+	);
+}
+
+/** Fixed, not random, so the server and the browser render the same bars. */
+const BAR_HEIGHTS = [40, 70, 55, 90, 65, 80, 50] as const;
+
+const SKELETON_CSS = `
+@keyframes voila-chart-pulse{50%{opacity:.5}}
+@media (prefers-reduced-motion:no-preference){[data-slot="chart-skeleton-bar"]{animation:voila-chart-pulse 2s cubic-bezier(.4,0,.6,1) infinite}}
+`;
+
+interface SkeletonProps extends React.ComponentProps<"div"> {
+	/** What a screen reader hears while the chart loads. */
+	readonly label?: string;
+}
+
+/** A loading placeholder shaped like a bar chart, announced as a status. */
+export function ChartSkeleton({
+	label = "Chargement",
+	style,
+	...props
+}: SkeletonProps) {
+	return (
+		<div
+			data-slot="chart-skeleton"
+			role="status"
+			aria-label={label}
+			style={{
+				...BOX,
+				display: "flex",
+				alignItems: "flex-end",
+				gap: 8,
+				...style,
+			}}
+			{...props}
+		>
+			<style href="voila-chart-skeleton" precedence="default">
+				{SKELETON_CSS}
+			</style>
+			{BAR_HEIGHTS.map((height) => (
+				<div
+					key={height}
+					data-slot="chart-skeleton-bar"
+					style={{
+						width: "100%",
+						height: `${height}%`,
+						borderRadius: 6,
+						background:
+							"var(--muted, color-mix(in oklab, currentColor 10%, transparent))",
+					}}
+				/>
+			))}
+		</div>
+	);
+}

package/src/react/index.ts

@@ -1,5 +1,6 @@
 export type { ChartBrush, ChartBrushRange } from "#/react/brush-contract.ts";
 export { Chart } from "#/react/chart.tsx";
+export { ChartEmpty, ChartSkeleton } from "#/react/chart-placeholders.tsx";
 export {
 	ChartTooltipContent,
 	type ChartTooltipRenderProps,

package/src/react/svg-scene.tsx

@@ -17,9 +17,40 @@ const BASELINE: Record<
 	alphabetic: "alphabetic",
 };
 
-function paintProps(paint: ChartPaint): React.SVGAttributes<SVGElement> {
+const HATCH_STEP = 6;
+
+/** A stable id per colour (djb2), the same on the server and in the browser. */
+function hatchId(prefix: string, color: string): string {
+	let hash = 5381;
+	for (const character of color) {
+		hash = ((hash << 5) + hash + character.charCodeAt(0)) | 0;
+	}
+	return `${prefix}-hatch-${(hash >>> 0).toString(36)}`;
+}
+
+function hatchColors(
+	nodes: ReadonlyArray<SceneNode>,
+	into = new Set<string>(),
+): Set<string> {
+	for (const node of nodes) {
+		if (node.kind === "group") {
+			hatchColors(node.children, into);
+		} else if (node.paint.hatch && node.paint.fill) {
+			into.add(node.paint.fill);
+		}
+	}
+	return into;
+}
+
+function paintProps(
+	paint: ChartPaint,
+	prefix: string,
+): React.SVGAttributes<SVGElement> {
 	return {
-		fill: paint.fill ?? "none",
+		fill:
+			paint.hatch && paint.fill
+				? `url(#${hatchId(prefix, paint.fill)})`
+				: (paint.fill ?? "none"),
 		stroke: paint.stroke,
 		strokeWidth: paint.strokeWidth,
 		strokeDasharray: paint.strokeDasharray,
@@ -72,7 +103,7 @@ function SceneElement({
 				<path
 					{...data}
 					d={roundedBarPath({ ...node, radius: node.corners })}
-					{...paintProps(node.paint)}
+					{...paintProps(node.paint, clipPrefix)}
 				/>
 			) : (
 				<rect
@@ -81,11 +112,13 @@ function SceneElement({
 					y={node.y}
 					width={node.width}
 					height={node.height}
-					{...paintProps(node.paint)}
+					{...paintProps(node.paint, clipPrefix)}
 				/>
 			);
 		case "path":
-			return <path {...data} d={node.d} {...paintProps(node.paint)} />;
+			return (
+				<path {...data} d={node.d} {...paintProps(node.paint, clipPrefix)} />
+			);
 		case "circle":
 			return (
 				<circle
@@ -93,7 +126,7 @@ function SceneElement({
 					cx={node.cx}
 					cy={node.cy}
 					r={node.r}
-					{...paintProps(node.paint)}
+					{...paintProps(node.paint, clipPrefix)}
 				/>
 			);
 		case "line":
@@ -104,7 +137,7 @@ function SceneElement({
 					y1={node.y1}
 					x2={node.x2}
 					y2={node.y2}
-					{...paintProps(node.paint)}
+					{...paintProps(node.paint, clipPrefix)}
 				/>
 			);
 		case "text":
@@ -124,7 +157,7 @@ function SceneElement({
 					dominantBaseline={
 						node.paint.baseline ? BASELINE[node.paint.baseline] : undefined
 					}
-					{...paintProps(node.paint)}
+					{...paintProps(node.paint, clipPrefix)}
 				>
 					{node.text}
 				</text>
@@ -140,7 +173,35 @@ export function SvgSceneNodes({
 	scene: ChartScene;
 	clipPrefix: string;
 }) {
-	return scene.nodes.map((node) => (
-		<SceneElement key={node.key} node={node} clipPrefix={clipPrefix} />
-	));
+	const hatches = [...hatchColors(scene.nodes)];
+	return (
+		<>
+			{hatches.length > 0 ? (
+				<defs>
+					{hatches.map((color) => (
+						<pattern
+							key={color}
+							id={hatchId(clipPrefix, color)}
+							width={HATCH_STEP}
+							height={HATCH_STEP}
+							patternUnits="userSpaceOnUse"
+							patternTransform="rotate(45)"
+						>
+							<line
+								x1={0}
+								y1={0}
+								x2={0}
+								y2={HATCH_STEP}
+								stroke={color}
+								strokeWidth={1.5}
+							/>
+						</pattern>
+					))}
+				</defs>
+			) : null}
+			{scene.nodes.map((node) => (
+				<SceneElement key={node.key} node={node} clipPrefix={clipPrefix} />
+			))}
+		</>
+	);
 }