admin: overview redesign, device scope, one formatting contract (milestone 39)

The Overview page takes the decided visual language (specs/ui-visual-redesign.md): four centred totals with their Activity links, a smoothed area chart of total and blocked queries with point hover and a tooltip centred beside the point, a stacked client chart in eight distinct hues plus one Other band that is always a series, and a card row with the cache hit rate, the query types as a single-hue ramp ring, and the upstream breakdown. The count axis grows its margin with the widest grouped tick and draws whole-number ticks only.

GET /api/overview takes a client parameter; the scoped read uses idx_query_log_ts and the cache keeps scoped slots. The device selector beside the period selector is URL state, so a scoped view is a link, and the tile links carry the scope into Activity. The route reduces a pasted IPv6 scope to the RFC 5952 spelling the logger stores, mapped addresses included, and drops anything that is not an address. A failed device list says so under the selector with a retry.

All measured quantities go through admin/src/lib/format.ts: grouped counts, two-decimal percentages, one-decimal rates, durations as the two largest nonzero units. Identifiers, configured values and preset labels render as written; the module header states that scope. A sweep test refuses toFixed, toLocaleString, Intl.NumberFormat and padStart anywhere else.

Chrome: one 4px radius from the metrics constants, shared Card with a prominent title and a one-line description on every panel, the settings form sections on the same card with a floated legend, the sidebar grouped into Monitoring and System with a status block (protection, queries per minute on Overview, uptime), keyboard-focusable table scroll wrappers, and the accent darkened to 5.43:1 on its wash.

Not built: the spec's ranked-list primitive, which has no consumer and no API rows. Codex reviewed sessions B to D over five rounds (thirty-three findings fixed, thirteen rejected as non-quantities); the owner skipped a sixth round.

Claude-Session: https://claude.ai/code/session_01VTgx3a1zz1R78o4K55kkwR

admin/src/features/overview/ClientChart.tsx

@@ -3,27 +3,28 @@
  * series per named client, plus everything outside the top eight as "Other".
  *
  * The x-axis is derived from this response's own `since` and `bucket_seconds`,
- * which the API aligns with the timeseries endpoint's buckets, so the two charts
- * stack directly above one another and a spike in one is at the same horizontal
- * position in the other. Colour keys on the client string, so a client that
- * changes rank between polls keeps its colour.
+ * which the API aligns with the timeseries buckets, so the two charts stack
+ * directly above one another and a spike in one is at the same horizontal
+ * position in the other. Colour goes by rank (`seriesColors.ts`): the busiest
+ * client wears the first palette hue, and the legend names every band.
  */
 
 import * as stylex from "@stylexjs/stylex";
 import { Group } from "@visx/group";
 import { BarStack } from "@visx/shape";
-import { formatTime } from "@/lib/format";
+import { formatCount, formatTime } from "@/lib/format";
 import type { OverviewClientSeries } from "@/lib/types";
 import { styles as shared } from "@/ui/styles";
-import { colors } from "@/ui/tokens.stylex";
 import { clientLabel, useClientNames, type ClientNames } from "@/features/clients/clientNames";
 import {
-	BucketOverlay,
 	CHART_HEIGHT,
 	ChartFrame,
+	ChartLegend,
 	ChartRoot,
 	ChartTooltip,
 	EmptyChart,
+	HitBands,
+	STACK_BLEED,
 	StackSegment,
 	bandScale,
 	labelTickValues,
@@ -35,36 +36,10 @@ import {
 	valueTicks,
 	type TooltipContent,
 } from "./chartKit";
-import { OTHER_KEY, clientKey, seriesColor } from "./seriesColors";
+import { OTHER_KEY, clientKey, clientSeriesColor, seriesColor } from "./seriesColors";
 
-const styles = stylex.create({
-	legend: {
-		marginTop: "0.5rem",
-		display: "flex",
-		flexWrap: "wrap",
-		columnGap: "1rem",
-		rowGap: "0.25rem",
-		listStyleType: "none",
-		padding: 0,
-		margin: 0,
-		fontSize: "0.75rem",
-		lineHeight: "1rem",
-		color: colors.textSecondary,
-	},
-	legendItem: {
-		display: "flex",
-		alignItems: "center",
-		gap: "0.375rem",
-	},
-	swatch: {
-		display: "inline-block",
-		width: "0.625rem",
-		height: "0.625rem",
-		borderRadius: "0.125rem",
-	},
-	/** Dynamic: the swatch takes the colour the bars are drawn in. */
-	swatchColor: (color: string) => ({ backgroundColor: color }),
-});
+/** How many named clients a bucket's tooltip lists before the aggregate and the total. */
+const TOOLTIP_CLIENTS = 4;
 
 interface Series {
 	key: string;
@@ -74,23 +49,20 @@ interface Series {
 }
 
 /**
- * "Other" last, so it sits at the top of every column rather than under a client,
- * and dropped entirely when it counted nothing across the window: an aggregation
- * bucket that aggregated nothing is a legend entry, a stack key, a tooltip row
- * and a table column all saying zero. The named clients stay at zero, because a
- * client that went quiet is something the reader wants to see.
+ * "Other" last, so it sits at the top of every column rather than under a client.
+ * It is always a series, even at zero across the window (ui-visual-redesign.md:
+ * eight named clients plus Other): a reader comparing two scopes sees the same
+ * legend in both, and a zero says the named clients were the whole story.
  */
 function seriesOf(data: ClientChartData, names: ClientNames): Series[] {
-	const named = data.clients.map((client) => ({
+	const named = data.clients.map((client, rank) => ({
 		key: clientKey(client.client),
 		// The name if the client is registered under one, the address otherwise —
-		// the same precedence and the same lookup the query tables use. The colour
-		// keys on the address regardless, so naming a client never repaints it.
+		// the same precedence and the same lookup the query tables use.
 		label: clientLabel(client.client, names)?.text ?? client.client,
-		color: seriesColor(clientKey(client.client)),
+		color: clientSeriesColor(rank),
 		buckets: client.buckets,
 	}));
-	if (data.other.every((count) => count === 0)) return named;
 	return [...named, { key: OTHER_KEY, label: "Other", color: seriesColor(OTHER_KEY), buckets: data.other }];
 }
 
@@ -129,7 +101,7 @@ export default function ClientChart({ data }: { data: ClientChartData }) {
 
 	const timestamps = columns.map((column) => column.ts);
 	const totals = columns.map((column) => series.reduce((sum, one) => sum + column[one.key], 0));
-	const plot = plotArea(width);
+	const plot = plotArea(width, Math.max(...totals));
 	const xScale = bandScale(timestamps, plot);
 	// Every series here is a disjoint part of the whole rather than a highlighted
 	// subset of a separately reported total, so the tallest column's own sum is
@@ -137,19 +109,30 @@ export default function ClientChart({ data }: { data: ClientChartData }) {
 	const yScale = valueScale(Math.max(...totals), [plot.bottom, plot.y]);
 	const yTicks = valueTicks(yScale);
 	const colorOf = new Map(series.map((one) => [one.key, one.color]));
+	const centers = timestamps.map((ts) => slotCenter(xScale, ts, plot));
 
+	/**
+	 * The bucket's busiest clients, then Other, then the total — eight named
+	 * rows would be a table, and the reader pointing at a spike wants to know
+	 * who made it. Other is always there, at zero when the named clients were
+	 * the whole bucket, so the rows read the same from bucket to bucket.
+	 */
 	function tooltipOf(index: number): TooltipContent {
+		const column = columns[index];
+		const named = series
+			.filter((one) => one.key !== OTHER_KEY && column[one.key] > 0)
+			.sort((a, b) => column[b.key] - column[a.key])
+			.slice(0, TOOLTIP_CLIENTS);
+		const other = series.find((one) => one.key === OTHER_KEY);
+		const rows = [...named, ...(other !== undefined ? [other] : [])].map((one) => ({
+			key: one.key,
+			label: one.label,
+			color: one.color,
+			value: formatCount(column[one.key]),
+		}));
 		return {
-			title: formatTime(columns[index].ts),
-			rows: [
-				{ key: "queries", label: "Queries", value: String(totals[index]) },
-				...series.map((one) => ({
-					key: one.key,
-					label: one.label,
-					color: one.color,
-					value: String(columns[index][one.key]),
-				})),
-			],
+			title: formatTime(column.ts),
+			rows: [...rows, { key: "total", label: "All clients", value: formatCount(totals[index]) }],
 		};
 	}
 
@@ -157,7 +140,7 @@ export default function ClientChart({ data }: { data: ClientChartData }) {
 		<ChartRoot containerRef={containerRef}>
 			<svg
 				role="img"
-				aria-label={`Client activity over time, ${bucketCount} buckets, ${series.length} series`}
+				aria-label={`Client activity over time, ${formatCount(bucketCount)} buckets, ${formatCount(series.length)} series`}
 				width="100%"
 				height={CHART_HEIGHT}
 				viewBox={`0 0 ${width} ${CHART_HEIGHT}`}
@@ -187,6 +170,7 @@ export default function ClientChart({ data }: { data: ClientChartData }) {
 							>
 								{stacks.map((stack) => {
 									const bar = stack.bars[index];
+									const restsOnAnother = bar.y + bar.height < plot.bottom - STACK_BLEED;
 									return (
 										<StackSegment
 											key={stack.key}
@@ -195,6 +179,7 @@ export default function ClientChart({ data }: { data: ClientChartData }) {
 											width={bar.width}
 											height={bar.height}
 											fill={bar.color}
+											bleed={restsOnAnother ? STACK_BLEED : 0}
 										/>
 									);
 								})}
@@ -202,23 +187,12 @@ export default function ClientChart({ data }: { data: ClientChartData }) {
 						))
 					}
 				</BarStack>
-				<BucketOverlay plot={plot} values={timestamps} xScale={xScale} onEnter={hovered.show} />
+				<HitBands plot={plot} centers={centers} onEnter={hovered.show} />
 			</svg>
 			{hovered.index !== null && (
-				<ChartTooltip
-					index={hovered.index}
-					content={tooltipOf(hovered.index)}
-					left={slotCenter(xScale, timestamps[hovered.index], plot)}
-				/>
+				<ChartTooltip index={hovered.index} content={tooltipOf(hovered.index)} left={centers[hovered.index]} />
 			)}
-			<ul {...stylex.props(styles.legend)}>
-				{series.map((one) => (
-					<li key={one.key} {...stylex.props(styles.legendItem)}>
-						<span aria-hidden="true" {...stylex.props(styles.swatch, styles.swatchColor(one.color))} />
-						{one.label}
-					</li>
-				))}
-			</ul>
+			<ChartLegend entries={series} />
 			<div {...stylex.props(shared.srOnly)}>
 				<table>
 					<caption>Queries per client per time bucket</caption>
@@ -237,7 +211,7 @@ export default function ClientChart({ data }: { data: ClientChartData }) {
 							<tr key={column.ts}>
 								<th scope="row">{formatTime(column.ts)}</th>
 								{series.map((one) => (
-									<td key={one.key}>{column[one.key]}</td>
+									<td key={one.key}>{formatCount(column[one.key])}</td>
 								))}
 							</tr>
 						))}