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/OverviewFrame.tsx

@@ -1,6 +1,7 @@
 /**
- * The part of Overview that does not wait for anything: the heading, the period
- * picker, and the pulsing body the page shows while the window is in flight.
+ * The part of Overview that does not wait for anything: the heading, the
+ * toolbar with the device and period selectors, and the pulsing body the page
+ * shows while the window is in flight.
  *
  * It lives apart from `OverviewPage` so the route's pending component can render
  * the identical surface while the page chunk loads. Importing the page itself
@@ -8,19 +9,37 @@
  * the frame would drift. Nothing here imports a chart.
  */
 
+import { useCallback } from "react";
 import * as stylex from "@stylexjs/stylex";
+import { useQuery } from "@tanstack/react-query";
 import { useNavigate, useSearch } from "@tanstack/react-router";
-import { Radio, RadioGroup } from "react-aria-components";
+import { clientLabel, useClientNames } from "@/features/clients/clientNames";
+import { clientsQuery } from "@/lib/queries";
 import type { Period } from "@/lib/types";
+import Select, { type SelectOption } from "@/ui/Select";
 import { styles as shared } from "@/ui/styles";
-import { colors, metrics } from "@/ui/tokens.stylex";
+import { colors } from "@/ui/tokens.stylex";
 import { DEFAULT_PERIOD, PERIODS } from "./period";
 
+const NARROW = "@media (max-width: 800px)";
+
+const PERIOD_LABELS: Record<Period, string> = {
+	"1h": "Last hour",
+	"24h": "Last 24 hours",
+	"7d": "Last 7 days",
+	"30d": "Last 30 days",
+};
+
+const PERIOD_OPTIONS: SelectOption[] = PERIODS.map((period) => ({ value: period, label: PERIOD_LABELS[period] }));
+
+/** The Select's key for the whole household; a client scope is the address itself. */
+const ALL_DEVICES = "";
+
 const styles = stylex.create({
 	page: {
 		display: "flex",
 		flexDirection: "column",
-		gap: "1rem",
+		gap: "1.25rem",
 	},
 	headingRow: {
 		display: "flex",
@@ -30,60 +49,43 @@ const styles = stylex.create({
 		gap: "0.75rem",
 	},
 	heading: {
+		margin: 0,
 		fontSize: "1.5rem",
 		lineHeight: "2rem",
-		fontWeight: 600,
+		fontWeight: 650,
+		letterSpacing: "-0.015em",
 		textWrap: "balance",
 	},
-	periodGroup: {
+	/** Device on the left, period on the right; on a phone the pair takes the whole row. */
+	toolbar: {
 		display: "flex",
-		gap: "0.25rem",
+		gap: "0.5rem",
+		flexBasis: { default: null, [NARROW]: "100%" },
 	},
-	/**
-	 * The weight lives here rather than on the selected variant: selection may
-	 * change colour, but a heavier label would re-measure the row and shift every
-	 * option beside it.
-	 */
-	period: {
+	control: {
+		minWidth: { default: "11rem", [NARROW]: 0 },
+		flex: { default: null, [NARROW]: 1 },
+	},
+	/** Under the Device control: the list behind it did not load, so the control offers the household only. */
+	devicesFailed: {
+		margin: 0,
+		marginTop: "0.25rem",
+		fontSize: "0.75rem",
+		lineHeight: "1rem",
+		color: colors.textMuted,
+	},
+	retry: {
+		padding: 0,
+		borderWidth: 0,
+		backgroundColor: "transparent",
+		font: "inherit",
+		color: colors.primaryOnSurface,
 		cursor: "pointer",
-		display: "inline-flex",
-		alignItems: "center",
-		justifyContent: "center",
-		minHeight: metrics.hitTarget,
-		minWidth: metrics.hitTarget,
-		borderStyle: "none",
-		borderRadius: "0.25rem",
-		paddingInline: "0.625rem",
-		paddingBlock: "0.25rem",
-		fontSize: "0.875rem",
-		lineHeight: "1.25rem",
-		fontWeight: 500,
-	},
-	/** A Radio is a `label`, so RAC drives the ring rather than `:focus-visible`. */
-	periodFocusVisible: {
-		outlineWidth: 2,
-		outlineStyle: "solid",
-		outlineColor: colors.focus,
-		outlineOffset: 2,
-	},
-	/** The pressed fill is heavier than `surfaceHover`, so a hover cannot mimic it. */
-	periodSelected: {
-		backgroundColor: {
-			default: "oklch(92% 0.004 286.32)",
-			"@media (prefers-color-scheme: dark)": "oklch(37% 0.013 285.805)",
-		},
-		color: colors.text,
-	},
-	periodIdle: {
-		backgroundColor: { default: "transparent", ":hover": colors.surfaceHover },
-		color: colors.textSecondary,
-		transitionProperty: metrics.transitionProperty,
-		transitionDuration: { default: metrics.transitionDuration, "@media (prefers-reduced-motion: reduce)": "0s" },
 	},
 	/**
-	 * The height approximates the filled overview — stat tiles, a 240px chart and
-	 * a 180px donut with the panel chrome around them — so that the page does not
-	 * jump when the window lands. That is where the number comes from.
+	 * The height approximates the filled overview — stat tiles, two 240px charts
+	 * and the row of cards under them — so that the page does not jump when the
+	 * window lands. That is where the number comes from.
 	 */
 	loading: {
 		minHeight: "48rem",
@@ -93,31 +95,72 @@ const styles = stylex.create({
 	},
 });
 
-export function PeriodPicker({ period, onChange }: { period: Period; onChange: (period: Period) => void }) {
+export interface OverviewScope {
+	period: Period;
+	client: string | undefined;
+}
+
+/**
+ * The devices the reader can scope to: the whole household first, then every
+ * registered client under its name. A scope the URL carries that the list has
+ * never seen is still offered, as its address, so the control shows the scope
+ * the page is actually under rather than silently claiming the household. A
+ * list that failed to load is said so under the control, with a retry: the
+ * household-only list is a failure, not the answer.
+ */
+function useDeviceOptions(client: string | undefined) {
+	const clients = useQuery(clientsQuery());
+	const names = useClientNames();
+	const known = (clients.data ?? []).map((one) => ({
+		value: one.ip,
+		label: clientLabel(one.ip, names)?.text ?? one.ip,
+	}));
+	const options = [{ value: ALL_DEVICES, label: "All devices" }, ...known];
+	if (client !== undefined && !known.some((option) => option.value === client)) {
+		options.push({ value: client, label: client });
+	}
+	const { refetch } = clients;
+	const retry = useCallback(() => void refetch(), [refetch]);
+	return { options, failed: clients.isError, retry };
+}
+
+export function OverviewToolbar({
+	scope,
+	onChange,
+}: {
+	scope: OverviewScope;
+	onChange: (next: OverviewScope) => void;
+}) {
+	const devices = useDeviceOptions(scope.client);
 	return (
-		<RadioGroup
-			aria-label="Period"
-			orientation="horizontal"
-			value={period}
-			onChange={(next) => onChange(next as Period)}
-			className={() => stylex.props(styles.periodGroup).className ?? ""}
-		>
-			{PERIODS.map((option) => (
-				<Radio
-					key={option}
-					value={option}
-					className={({ isSelected, isFocusVisible }) =>
-						stylex.props(
-							styles.period,
-							isSelected ? styles.periodSelected : styles.periodIdle,
-							isFocusVisible && styles.periodFocusVisible,
-						).className ?? ""
-					}
-				>
-					{option}
-				</Radio>
-			))}
-		</RadioGroup>
+		<div {...stylex.props(styles.toolbar)}>
+			<div {...stylex.props(styles.control)}>
+				<Select
+					aria-label="Device"
+					variant="toolbar"
+					options={devices.options}
+					value={scope.client ?? ALL_DEVICES}
+					onChange={(value) => onChange({ ...scope, client: value === ALL_DEVICES ? undefined : value })}
+				/>
+				{devices.failed && (
+					<p role="alert" {...stylex.props(styles.devicesFailed)}>
+						Device list unavailable.{" "}
+						<button type="button" onClick={devices.retry} {...stylex.props(styles.retry, shared.focusRing)}>
+							Retry
+						</button>
+					</p>
+				)}
+			</div>
+			<div {...stylex.props(styles.control)}>
+				<Select
+					aria-label="Period"
+					variant="toolbar"
+					options={PERIOD_OPTIONS}
+					value={scope.period}
+					onChange={(value) => onChange({ ...scope, period: value as Period })}
+				/>
+			</div>
+		</div>
 	);
 }
 
@@ -130,19 +173,19 @@ export function OverviewLoading() {
 }
 
 export function OverviewFrame({
-	period,
+	scope,
 	onChange,
 	children,
 }: {
-	period: Period;
-	onChange: (period: Period) => void;
+	scope: OverviewScope;
+	onChange: (next: OverviewScope) => void;
 	children: React.ReactNode;
 }) {
 	return (
 		<div {...stylex.props(styles.page)}>
 			<div {...stylex.props(styles.headingRow)}>
 				<h1 {...stylex.props(styles.heading)}>Overview</h1>
-				<PeriodPicker period={period} onChange={onChange} />
+				<OverviewToolbar scope={scope} onChange={onChange} />
 			</div>
 			{children}
 		</div>
@@ -150,17 +193,33 @@ export function OverviewFrame({
 }
 
 /**
- * The route's pending surface. The picker stays live because it only writes the
- * search parameter, which the route already re-reads on its own.
+ * The scope the URL names, and the navigation that rewrites it. The default
+ * period and the household scope are the absence of a parameter, so a link to
+ * the plain page stays `/overview` rather than growing `?period=24h`.
+ */
+export function useOverviewScope(): [OverviewScope, (next: OverviewScope) => void] {
+	const search = useSearch({ from: "/shell/overview" });
+	const navigate = useNavigate({ from: "/overview" });
+	const scope = { period: search.period ?? DEFAULT_PERIOD, client: search.client };
+	const setScope = (next: OverviewScope) =>
+		void navigate({
+			search: (prev) => ({
+				...prev,
+				period: next.period === DEFAULT_PERIOD ? undefined : next.period,
+				client: next.client,
+			}),
+		});
+	return [scope, setScope];
+}
+
+/**
+ * The route's pending surface. The toolbar stays live because it only writes
+ * the search parameters, which the route already re-reads on its own.
  */
 export function OverviewPending() {
-	const period = useSearch({ from: "/shell/overview" }).period ?? DEFAULT_PERIOD;
-	const navigate = useNavigate({ from: "/overview" });
+	const [scope, setScope] = useOverviewScope();
 	return (
-		<OverviewFrame
-			period={period}
-			onChange={(next) => void navigate({ search: (prev) => ({ ...prev, period: next }) })}
-		>
+		<OverviewFrame scope={scope} onChange={setScope}>
 			<OverviewLoading />
 		</OverviewFrame>
 	);