@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/HighlightCard/HighlightCard.chart.js

@@ -0,0 +1,660 @@
+import { AXIS_LABEL_LIMIT_EXPR } from "../../lib/vega/axisTicks.js";
+import { arcVegaConfig } from "../../lib/vega/config.js";
+//#region src/components/HighlightCard/HighlightCard.chart.ts
+/** Context plot: every reading, with `hl` and the window's `tone`. */
+const HIGHLIGHT_TABLE_DATASET = "table";
+/** Context plot: the readings outside the window with a `seg` of `before` or `after` — the gray runs. */
+const HIGHLIGHT_OUTSIDE_DATASET = "outside";
+/** Context plot: the readings inside the window — the coloured segment. */
+const HIGHLIGHT_INSIDE_DATASET = "inside";
+/** Context plot: the window's start and end readings — the two dots. */
+const HIGHLIGHT_ENDPOINTS_DATASET = "endpoints";
+/** Context plot: one row `{ start, end, tone }` — the band wash and the axis anchors. */
+const HIGHLIGHT_BAND_DATASET = "band";
+/** Peer strip: one row per compared window, `{ change, isHighlight, … }`. */
+const HIGHLIGHT_PEERS_DATASET = "peers";
+/** Peer strip: one row `{ low, high }` — the typical-range wash. */
+const HIGHLIGHT_TYPICAL_DATASET = "typical";
+/** Peer strip and drivers: one row `{ value: 0 }` — the hairline at no change. */
+const HIGHLIGHT_ZERO_DATASET = "zero";
+/** Drivers: one row per contributor, `{ key, label, value, tone, role }`. */
+const HIGHLIGHT_DRIVERS_DATASET = "drivers";
+/** Context plot: the nearest-reading hover selection. */
+const HIGHLIGHT_HOVER_PARAM = "hover";
+/** Peer strip: the hovered window. */
+const HIGHLIGHT_PEER_HOVER_PARAM = "peer_hover";
+/** Drivers: the hovered bar. */
+const HIGHLIGHT_DRIVER_HOVER_PARAM = "driver_hover";
+/** Context plot: responsive x tick values, recomputed by Vega when the domain or width changes. */
+const HIGHLIGHT_X_TICKS_PARAM = "highlight_x_ticks";
+/** Context plot: the window's snapped bounds, read from the `band` dataset — the x axis labels them. */
+const HIGHLIGHT_START_PARAM = "highlight_start";
+const HIGHLIGHT_END_PARAM = "highlight_end";
+const POINT_SIZE = 64;
+const BAR_WIDTH_EXPR = "min(24, bandwidth('x') * 0.7)";
+/** Bars stay ≤ 24px however tall the rows are. */
+const MAX_DRIVER_BAR_HEIGHT = 24;
+const PLOT_PADDING = 6;
+const BAND_OPACITY = .08;
+const TYPICAL_OPACITY = .14;
+const PEER_OPACITY = .45;
+const RESTING_OPACITY = .75;
+const PX_PER_Y_TICK = 48;
+const MIN_Y_TICKS = 2;
+const DISCRETE_DOMAIN_EXPR = `pluck(data('${HIGHLIGHT_TABLE_DATASET}'), 'x')`;
+const DRIVER_DOMAIN_EXPR = `pluck(data('${HIGHLIGHT_DRIVERS_DATASET}'), 'key')`;
+/**
+* A mark colour that follows a row's polarity — the diverging ends when the
+* move means good or bad (lightness-matched, ≥ 3:1 on both surfaces), the
+* emphasis hue when it is neutral — and `fallback` for rows carrying none
+* (`null`). Kept in the spec as three token values, so the spec stays
+* structural while the data decides.
+*
+* `field` is the row property holding it: the context and driver rows call it
+* `tone`, and a peer row calls it `polarity` because that row is also public
+* API. A mismatch here paints every mark the fallback hue, so the spec tests
+* assert the diverging values are present on each plot.
+*/
+function toneColor(tokens, fallback, field = "tone") {
+	return {
+		condition: [
+			{
+				test: `datum.${field} === 'positive'`,
+				value: tokens.divergingPositive
+			},
+			{
+				test: `datum.${field} === 'negative'`,
+				value: tokens.divergingNegative
+			},
+			{
+				test: `datum.${field} === 'neutral'`,
+				value: tokens.emphasis
+			}
+		],
+		value: fallback
+	};
+}
+/**
+* The window inside the whole series: a quiet band washes its extent, the
+* readings outside it draw in the context gray, the window itself draws in its
+* polarity hue, its start and end are dotted, and the x axis labels the
+* window's bounds before the domain's ends. Lines may crop (`scale: "auto"`);
+* areas and bars keep a zero baseline whatever `scale` says — proportional ink
+* is not negotiable. Gaps stay gaps: Vega-Lite's default `invalid` handling
+* breaks the path at a null reading.
+*/
+function buildHighlightContextSpec(options, tokens) {
+	const { mark, scale, xType, height, axes, tooltip, xTitle, yTitle, valueFormat, timeFormat, axisTimeFormat } = options;
+	const zero = mark !== "line" || scale === "zero";
+	const discreteX = mark === "bar" || xType === "ordinal";
+	const xTickFormat = xType === "temporal" ? axisTimeFormat : "compact";
+	const xTickKind = xType === "temporal" ? "time" : xType === "quantitative" ? "number" : "text";
+	const axisArgs = `domain('x'), width, ${discreteX}, ${JSON.stringify(xTickFormat)}, ${JSON.stringify(xTickKind)}`;
+	const anchorsArg = `, [${HIGHLIGHT_START_PARAM}, ${HIGHLIGHT_END_PARAM}]`;
+	const yTicks = Math.max(MIN_Y_TICKS, Math.round(height / PX_PER_Y_TICK));
+	const xAxisLabels = xType === "temporal" ? {
+		format: axisTimeFormat,
+		formatType: "arcTime"
+	} : xType === "quantitative" ? {
+		format: "compact",
+		formatType: "arcNumber"
+	} : {};
+	const xAxis = axes ? {
+		title: null,
+		orient: "bottom",
+		domain: true,
+		ticks: false,
+		grid: false,
+		values: { expr: HIGHLIGHT_X_TICKS_PARAM },
+		labelAngle: 0,
+		labelAlign: { expr: `arcAxisLabelAlign(datum.value, ${axisArgs}${anchorsArg})` },
+		labelFlush: false,
+		labelOverlap: false,
+		labelLimit: { expr: AXIS_LABEL_LIMIT_EXPR },
+		labelPadding: 4,
+		...xAxisLabels
+	} : null;
+	const yAxis = axes ? {
+		title: null,
+		orient: "left",
+		domain: false,
+		ticks: false,
+		grid: true,
+		tickCount: yTicks,
+		labelOverlap: true,
+		labelPadding: 6,
+		format: valueFormat,
+		formatType: "arcNumber"
+	} : null;
+	const discreteScale = { scale: { domain: { expr: DISCRETE_DOMAIN_EXPR } } };
+	const xField = mark === "bar" ? {
+		field: "x",
+		type: "ordinal",
+		sort: null,
+		axis: xAxis,
+		...discreteScale
+	} : {
+		field: "x",
+		type: xType,
+		axis: xAxis,
+		...xType === "ordinal" ? {
+			sort: null,
+			...discreteScale
+		} : { scale: {
+			nice: false,
+			...xType === "quantitative" ? { zero: false } : {}
+		} }
+	};
+	const yField = {
+		field: "y",
+		type: "quantitative",
+		axis: yAxis,
+		scale: {
+			zero,
+			nice: axes
+		}
+	};
+	const tooltipChannel = [xType === "temporal" ? {
+		field: "x",
+		type: "temporal",
+		title: xTitle,
+		format: timeFormat,
+		formatType: "arcTime"
+	} : xType === "quantitative" ? {
+		field: "x",
+		type: "quantitative",
+		title: xTitle,
+		format: "number",
+		formatType: "arcNumber"
+	} : {
+		field: "x",
+		type: "nominal",
+		title: xTitle
+	}, {
+		field: "y",
+		type: "quantitative",
+		title: yTitle,
+		format: valueFormat,
+		formatType: "arcNumber"
+	}];
+	const layers = [{
+		data: { name: HIGHLIGHT_BAND_DATASET },
+		mark: {
+			type: "rect",
+			opacity: BAND_OPACITY,
+			aria: false
+		},
+		encoding: {
+			x: {
+				...xField,
+				field: "start",
+				...discreteX ? { bandPosition: 0 } : {}
+			},
+			x2: {
+				field: "end",
+				...discreteX ? { bandPosition: 1 } : {}
+			},
+			fill: toneColor(tokens, tokens.emphasis)
+		}
+	}];
+	if (mark === "bar") layers.push({
+		...tooltip ? { params: [{
+			name: HIGHLIGHT_HOVER_PARAM,
+			select: {
+				type: "point",
+				on: "pointerover",
+				clear: "pointerout",
+				encodings: ["x"]
+			}
+		}] } : {},
+		mark: {
+			type: "bar",
+			cornerRadiusEnd: 2,
+			width: { expr: BAR_WIDTH_EXPR }
+		},
+		encoding: {
+			x: xField,
+			y: yField,
+			fill: toneColor(tokens, tokens.context),
+			...tooltip ? {
+				opacity: {
+					condition: {
+						param: HIGHLIGHT_HOVER_PARAM,
+						empty: false,
+						value: 1
+					},
+					value: RESTING_OPACITY
+				},
+				tooltip: tooltipChannel
+			} : {}
+		}
+	});
+	else {
+		const outsideEncoding = {
+			x: xField,
+			y: yField,
+			detail: {
+				field: "seg",
+				type: "nominal"
+			}
+		};
+		if (mark === "area") layers.push({
+			data: { name: HIGHLIGHT_OUTSIDE_DATASET },
+			mark: {
+				type: "area",
+				fill: tokens.context,
+				fillOpacity: .12,
+				line: false,
+				interpolate: "linear"
+			},
+			encoding: outsideEncoding
+		});
+		layers.push({
+			data: { name: HIGHLIGHT_OUTSIDE_DATASET },
+			mark: {
+				type: "line",
+				stroke: tokens.context,
+				strokeWidth: 2,
+				strokeCap: "round",
+				strokeJoin: "round",
+				interpolate: "linear"
+			},
+			encoding: outsideEncoding
+		});
+		if (mark === "area") layers.push({
+			data: { name: HIGHLIGHT_INSIDE_DATASET },
+			mark: {
+				type: "area",
+				fillOpacity: .12,
+				line: false,
+				interpolate: "linear"
+			},
+			encoding: {
+				x: xField,
+				y: yField,
+				fill: toneColor(tokens, tokens.emphasis)
+			}
+		});
+		layers.push({
+			data: { name: HIGHLIGHT_INSIDE_DATASET },
+			mark: {
+				type: "line",
+				strokeWidth: 2,
+				strokeCap: "round",
+				strokeJoin: "round",
+				interpolate: "linear"
+			},
+			encoding: {
+				x: xField,
+				y: yField,
+				stroke: toneColor(tokens, tokens.emphasis)
+			}
+		});
+		const dot = {
+			type: "point",
+			filled: true,
+			size: POINT_SIZE,
+			stroke: tokens.background,
+			strokeWidth: 1.5,
+			opacity: 1,
+			aria: false
+		};
+		layers.push({
+			data: { name: HIGHLIGHT_ENDPOINTS_DATASET },
+			mark: dot,
+			encoding: {
+				x: xField,
+				y: yField,
+				fill: toneColor(tokens, tokens.emphasis)
+			}
+		});
+		if (tooltip) layers.push({
+			params: [{
+				name: HIGHLIGHT_HOVER_PARAM,
+				select: {
+					type: "point",
+					on: "pointermove",
+					nearest: true,
+					clear: "pointerout",
+					encodings: ["x"]
+				}
+			}],
+			mark: {
+				type: "point",
+				filled: true,
+				size: POINT_SIZE,
+				stroke: tokens.background,
+				strokeWidth: 1.5,
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				y: yField,
+				fill: toneColor(tokens, tokens.context),
+				opacity: {
+					condition: {
+						param: HIGHLIGHT_HOVER_PARAM,
+						empty: false,
+						value: 1
+					},
+					value: 0
+				},
+				tooltip: tooltipChannel
+			}
+		});
+	}
+	const params = [{
+		name: HIGHLIGHT_START_PARAM,
+		expr: `length(data('${HIGHLIGHT_BAND_DATASET}')) ? data('${HIGHLIGHT_BAND_DATASET}')[0].start : null`
+	}, {
+		name: HIGHLIGHT_END_PARAM,
+		expr: `length(data('${HIGHLIGHT_BAND_DATASET}')) ? data('${HIGHLIGHT_BAND_DATASET}')[0].end : null`
+	}];
+	if (axes) params.push({
+		name: HIGHLIGHT_X_TICKS_PARAM,
+		expr: `arcAxisTicks(${axisArgs}${anchorsArg})`
+	});
+	return {
+		$schema: "https://vega.github.io/schema/vega-lite/v6.json",
+		width: 360,
+		height,
+		autosize: {
+			type: "fit",
+			contains: "padding"
+		},
+		padding: PLOT_PADDING,
+		background: "transparent",
+		data: { name: HIGHLIGHT_TABLE_DATASET },
+		params,
+		layer: layers,
+		config: arcVegaConfig(tokens, {
+			locale: options.locale,
+			timeZone: options.timeZone
+		})
+	};
+}
+/**
+* Every comparable window's change on ONE shared position scale, as a strip
+* plot: the typical range as a quiet wash, a hairline at no change, one thin
+* tick per compared window in the context gray, and the highlighted window as
+* a solid dot in its polarity hue.
+*
+* A strip plot, not a summary statistic, because showing the peers is the
+* honest way to say "unusual" — the reader sees the spread they are being
+* asked to accept, the crowd near zero and the tail this window sits in.
+* Every tick is also a row in the panel's table, so nothing lives only here.
+*/
+function buildHighlightPeersSpec(options, tokens) {
+	const { height, tooltip, windowTitle, changeTitle, changeFormat, typicalTitle } = options;
+	const xField = {
+		field: "change",
+		type: "quantitative",
+		axis: {
+			title: null,
+			orient: "bottom",
+			domain: false,
+			ticks: false,
+			grid: true,
+			tickCount: 4,
+			labelOverlap: true,
+			labelPadding: 4,
+			format: changeFormat,
+			formatType: "arcNumber"
+		},
+		scale: {
+			zero: true,
+			nice: true
+		}
+	};
+	const tooltipChannel = [{
+		field: "rangeText",
+		type: "nominal",
+		title: windowTitle
+	}, {
+		field: "change",
+		type: "quantitative",
+		title: changeTitle,
+		format: changeFormat,
+		formatType: "arcNumber"
+	}];
+	const layers = [
+		{
+			data: { name: HIGHLIGHT_TYPICAL_DATASET },
+			mark: {
+				type: "rect",
+				fill: tokens.brush,
+				opacity: TYPICAL_OPACITY,
+				aria: false
+			},
+			encoding: {
+				x: {
+					...xField,
+					field: "low"
+				},
+				x2: { field: "high" },
+				...tooltip ? { tooltip: [{
+					field: "low",
+					type: "quantitative",
+					title: typicalTitle,
+					format: changeFormat,
+					formatType: "arcNumber"
+				}, {
+					field: "high",
+					type: "quantitative",
+					title: "",
+					format: changeFormat,
+					formatType: "arcNumber"
+				}] } : {}
+			}
+		},
+		{
+			data: { name: HIGHLIGHT_ZERO_DATASET },
+			mark: {
+				type: "rule",
+				stroke: tokens.reference,
+				strokeWidth: 1,
+				opacity: .8,
+				aria: false
+			},
+			encoding: { x: {
+				...xField,
+				field: "value"
+			} }
+		},
+		{
+			...tooltip ? { params: [{
+				name: HIGHLIGHT_PEER_HOVER_PARAM,
+				select: {
+					type: "point",
+					on: "pointerover",
+					clear: "pointerout",
+					nearest: true
+				}
+			}] } : {},
+			data: { name: HIGHLIGHT_PEERS_DATASET },
+			transform: [{ filter: "!datum.isHighlight" }],
+			mark: {
+				type: "tick",
+				thickness: 1.5,
+				size: height * .5,
+				stroke: tokens.context,
+				ariaRoleDescription: "window"
+			},
+			encoding: {
+				x: xField,
+				...tooltip ? {
+					opacity: {
+						condition: {
+							param: HIGHLIGHT_PEER_HOVER_PARAM,
+							empty: false,
+							value: 1
+						},
+						value: PEER_OPACITY
+					},
+					tooltip: tooltipChannel
+				} : { opacity: { value: PEER_OPACITY } }
+			}
+		},
+		{
+			data: { name: HIGHLIGHT_PEERS_DATASET },
+			transform: [{ filter: "datum.isHighlight" }],
+			mark: {
+				type: "point",
+				filled: true,
+				size: 88,
+				stroke: tokens.background,
+				strokeWidth: 1.5,
+				opacity: 1,
+				ariaRoleDescription: "highlighted window"
+			},
+			encoding: {
+				x: xField,
+				fill: toneColor(tokens, tokens.emphasis, "polarity"),
+				...tooltip ? { tooltip: tooltipChannel } : {}
+			}
+		}
+	];
+	return {
+		$schema: "https://vega.github.io/schema/vega-lite/v6.json",
+		width: 360,
+		height,
+		autosize: {
+			type: "fit",
+			contains: "padding"
+		},
+		padding: PLOT_PADDING,
+		background: "transparent",
+		data: { name: HIGHLIGHT_PEERS_DATASET },
+		layer: layers,
+		config: arcVegaConfig(tokens, {
+			locale: options.locale,
+			timeZone: options.timeZone
+		})
+	};
+}
+/**
+* The window's change decomposed: one horizontal bar per contributor from a
+* shared zero, positive to the right and negative to the left, in the
+* diverging polarity hues. Sorted by absolute contribution upstream, so the
+* biggest mover is the first row.
+*
+* Bars only — the names, amounts and shares are DOM text beside the plot, so
+* every band has no padding and the bar centers line up with the rows that
+* carry the text. A hairline at zero is always drawn: these values are signed
+* by nature, and the reader must see which side of no-change each one is on.
+*/
+function buildHighlightDriversSpec(options, tokens) {
+	const { barHeight, height, tooltip, driverTitle, contributionTitle, shareTitle, valueFormat } = options;
+	const xField = {
+		field: "value",
+		type: "quantitative",
+		axis: null,
+		scale: {
+			zero: true,
+			nice: false
+		}
+	};
+	const yField = {
+		field: "key",
+		type: "nominal",
+		sort: null,
+		axis: null,
+		scale: {
+			domain: { expr: DRIVER_DOMAIN_EXPR },
+			paddingInner: 0,
+			paddingOuter: 0
+		}
+	};
+	const tooltipChannel = [
+		{
+			field: "label",
+			type: "nominal",
+			title: driverTitle
+		},
+		{
+			field: "value",
+			type: "quantitative",
+			title: contributionTitle,
+			format: valueFormat,
+			formatType: "arcNumber"
+		},
+		{
+			field: "share",
+			type: "quantitative",
+			title: shareTitle,
+			format: "percent:0",
+			formatType: "arcNumber"
+		}
+	];
+	const layers = [{
+		...tooltip ? { params: [{
+			name: HIGHLIGHT_DRIVER_HOVER_PARAM,
+			select: {
+				type: "point",
+				on: "pointerover",
+				clear: "pointerout",
+				encodings: ["y"]
+			}
+		}] } : {},
+		mark: {
+			type: "bar",
+			height: barHeight,
+			cornerRadiusEnd: 2
+		},
+		encoding: {
+			x: xField,
+			y: yField,
+			fill: toneColor(tokens, tokens.emphasis),
+			fillOpacity: {
+				condition: {
+					test: "datum.role === 'residual'",
+					value: .35
+				},
+				value: 1
+			},
+			...tooltip ? {
+				opacity: {
+					condition: {
+						param: HIGHLIGHT_DRIVER_HOVER_PARAM,
+						empty: false,
+						value: 1
+					},
+					value: RESTING_OPACITY
+				},
+				tooltip: tooltipChannel
+			} : {}
+		}
+	}, {
+		data: { name: HIGHLIGHT_ZERO_DATASET },
+		mark: {
+			type: "rule",
+			stroke: tokens.axis,
+			strokeWidth: 1,
+			opacity: .9,
+			aria: false
+		},
+		encoding: { x: {
+			...xField,
+			field: "value"
+		} }
+	}];
+	return {
+		$schema: "https://vega.github.io/schema/vega-lite/v6.json",
+		width: 240,
+		height,
+		autosize: {
+			type: "fit",
+			contains: "padding"
+		},
+		padding: 0,
+		background: "transparent",
+		data: { name: HIGHLIGHT_DRIVERS_DATASET },
+		layer: layers,
+		config: arcVegaConfig(tokens, {
+			locale: options.locale,
+			timeZone: options.timeZone
+		})
+	};
+}
+//#endregion
+export { HIGHLIGHT_BAND_DATASET, HIGHLIGHT_DRIVERS_DATASET, HIGHLIGHT_DRIVER_HOVER_PARAM, HIGHLIGHT_ENDPOINTS_DATASET, HIGHLIGHT_END_PARAM, HIGHLIGHT_HOVER_PARAM, HIGHLIGHT_INSIDE_DATASET, HIGHLIGHT_OUTSIDE_DATASET, HIGHLIGHT_PEERS_DATASET, HIGHLIGHT_PEER_HOVER_PARAM, HIGHLIGHT_START_PARAM, HIGHLIGHT_TABLE_DATASET, HIGHLIGHT_TYPICAL_DATASET, HIGHLIGHT_X_TICKS_PARAM, HIGHLIGHT_ZERO_DATASET, MAX_DRIVER_BAR_HEIGHT, buildHighlightContextSpec, buildHighlightDriversSpec, buildHighlightPeersSpec };