From 7e4222ef0092704a1334023ba4df37510d0f761f Mon Sep 17 00:00:00 2001
From: Developer <dev@headquarter.local>
Date: Sun, 12 Jul 2026 12:00:11 +0000
Subject: [PATCH] fix(widgets): expose unit/scale options in the frontend
 widget registry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The config dialog reads each widget kind's schema from the static frontend
SERVICE_REGISTRY (registry.ts), not the backend pydantic schema. The previous
commit added unit/scale to the backend configs but not to the frontend mirror,
so the options never appeared in the dialog — the Prometheus "chart" binding
still listed only promql/window and the qBittorrent "speed" binding had an
empty configSchema.

Add a shared AXIS_FORMAT_PROPERTIES fragment (unit + scale enums) and spread
it into the prometheus chart and qbittorrent speed bindings, with matching
defaultConfig (chart: none/auto; speed: bytes_per_sec/auto). Combined with the
enum <Select> rendering already added to WidgetConfigDialog, the options now
show up as dropdowns when editing those widgets.

Test: registry exposes unit/scale enums on chart + speed; speed defaults to
bytes_per_sec. 180/180 frontend tests pass; tsc + ESLint clean.
---
 frontend/src/integrations/.pi-map.index.md |  2 +-
 frontend/src/integrations/.pi-map.md       | 12 ++++----
 frontend/src/integrations/registry.test.ts | 16 ++++++++++
 frontend/src/integrations/registry.ts      | 36 ++++++++++++++++++++--
 4 files changed, 56 insertions(+), 10 deletions(-)

diff --git a/frontend/src/integrations/.pi-map.index.md b/frontend/src/integrations/.pi-map.index.md
index d53ff9f..187bb25 100644
--- a/frontend/src/integrations/.pi-map.index.md
+++ b/frontend/src/integrations/.pi-map.index.md
@@ -2,7 +2,7 @@
 dir: frontend/src/integrations
 
 ## role
-Central registry and integration layer that maps external services and built-in widgets to their React components, metadata, and navigation entries.
+Central integration layer that maps backend service types to frontend React components, navigation entries, and configuration schemas.
 ## parent
 index: frontend/src/.pi-map.index.md
 map: frontend/src/.pi-map.md
diff --git a/frontend/src/integrations/.pi-map.md b/frontend/src/integrations/.pi-map.md
index 5904be5..bc3673a 100644
--- a/frontend/src/integrations/.pi-map.md
+++ b/frontend/src/integrations/.pi-map.md
@@ -4,15 +4,15 @@ dir: frontend/src/integrations
 index: frontend/src/integrations/.pi-map.index.md
 
 ## role
-Central registry and integration layer that maps external services and built-in widgets to their React components, metadata, and navigation entries.
+Central integration layer that maps backend service types to frontend React components, navigation entries, and configuration schemas.
 ## files
-- navEntries.ts | Defines a static mapping of service types to their navigation entries and provides a filter function to return only entries for currently configured services. | exp: NavEntry, SERVICE_TYPE_NAV_ENTRIES, func:configuredNavEntries(configuredTypes: Set<string>) → NavEntry[], call:SERVICE_TYPE_NAV_ENTRIES.filter, call:configuredTypes.has | dep: lucide-react
-- registry.test.ts | Tests the service and widget registry module, validating service registrations, widget bindings, and widget resolution logic. | dep: vitest, ./registry, ../types
-- registry.ts | Maps service types and built-in widgets to their respective React components, metadata, and config schemas, and provides lookup functions to resolve widget instances. | exp: WidgetComponentProps, ServiceWidgetBinding, ServiceBinding, SERVICE_REGISTRY, BUILTIN_WIDGETS, ResolvedWidget, func:getServiceBinding(serviceType: string) → ServiceBinding | undefined, func:getBuiltinBinding(kind: string) → ServiceWidgetBinding | undefined, func:resolveWidget(widget: WidgetInstance, services: ServiceInstance[]) → ResolvedWidget | undefined, call:services.find, call:getServiceBinding, call:binding?.widgets.find, call:getBuiltinBinding, func:enrichServiceTypes(types: ServiceTypeInfo[]) → ServiceTypeInfo[] | dep: react, ../widgets/AlertmanagerAlertsWidget, ../widgets/BackupsWidget, ../widgets/PrometheusChartWidget, ../widgets/PrometheusGaugeWidget, ../widgets/PrometheusMeanWidget, ../widgets/JellyfinWidget, ../widgets/JellyfinNowPlayingWidget, ../widgets/PrometheusMetricWidget, ../widgets/QbittorrentActiveTorrentsWidget, ../widgets/QbittorrentSpeedWidget, ../widgets/QbittorrentTotalsWidget, ../widgets/SshTaskWidget, ../widgets/StaticWidget, ../types, various widget components, types
+- navEntries.ts | Defines a static mapping of service types to navigation entries and provides a filter function to return only entries for currently configured services. | exp: NavEntry, SERVICE_TYPE_NAV_ENTRIES, func:configuredNavEntries(configuredTypes: Set<string>) → NavEntry[], call:SERVICE_TYPE_NAV_ENTRIES.filter, call:configuredTypes.has | dep: lucide-react
+- registry.test.ts | Tests the service and widget registry, verifying service registrations, widget bindings, configuration schemas, and widget resolution logic. | dep: vitest, ./registry, ../types
+- registry.ts | Provides a frontend registry that maps service types and built-in widget kinds to their corresponding React components, metadata, and configuration schemas. | exp: WidgetComponentProps, ServiceWidgetBinding, ServiceBinding, SERVICE_REGISTRY, BUILTIN_WIDGETS, ResolvedWidget, func:getServiceBinding(serviceType: string) → ServiceBinding | undefined, func:getBuiltinBinding(kind: string) → ServiceWidgetBinding | undefined, func:resolveWidget(widget: WidgetInstance, services: ServiceInstance[]) → ResolvedWidget | undefined, call:services.find, call:getServiceBinding, call:binding?.widgets.find, call:getBuiltinBinding, func:enrichServiceTypes(types: ServiceTypeInfo[]) → ServiceTypeInfo[] | dep: react, ../widgets/AlertmanagerAlertsWidget, ../widgets/BackupsWidget, ../widgets/MetricChartWidget, ../widgets/MetricGaugeWidget, ../widgets/MetricMeanWidget, ../widgets/JellyfinWidget, ../widgets/JellyfinNowPlayingWidget, ../widgets/PrometheusMetricWidget, ../widgets/QbittorrentActiveTorrentsWidget, ../widgets/QbittorrentSpeedWidget, ../widgets/QbittorrentTotalsWidget, ../widgets/SshTaskWidget, ../widgets/StaticWidget, ../types, various widget components, internal types module
 ## arch
-Registry pattern with static mappings, lookup/resolution functions, and filter utilities to dynamically expose only configured service integrations.
+Registry pattern with static navigation mappings, component resolution logic, and test-validated service/widget bindings.
 ## tags
-service, widgets, widget, binding, nav, entries, types, registry
+service, widgets, widget, binding, nav, entries, registry, types
 ## symbols
 - configuredNavEntries
 - getServiceBinding
diff --git a/frontend/src/integrations/registry.test.ts b/frontend/src/integrations/registry.test.ts
index 1377048..16400f2 100644
--- a/frontend/src/integrations/registry.test.ts
+++ b/frontend/src/integrations/registry.test.ts
@@ -40,6 +40,22 @@ describe("service registry", () => {
 		expect(Object.keys(BUILTIN_WIDGETS).sort()).toEqual(["backups", "static"]);
 	});
 
+	it("exposes unit/scale options on graph widget kinds", () => {
+		const propsOf = (binding: { configSchema: Record<string, unknown> } | undefined) =>
+			(binding?.configSchema as { properties?: Record<string, { enum?: string[] }> } | undefined)
+					?.properties ?? {};
+		const chart = getServiceBinding("prometheus")?.widgets.find((w) => w.kind === "chart");
+		const speed = getServiceBinding("qbittorrent")?.widgets.find(
+			(w) => w.kind === "speed",
+		);
+		expect(propsOf(chart).unit?.enum).toContain("bytes_per_sec");
+		expect(propsOf(chart).scale?.enum).toEqual(["auto", "k", "m", "g", "t"]);
+		expect(propsOf(speed).unit?.enum).toContain("bytes_per_sec");
+		expect(propsOf(speed).scale?.enum).toEqual(["auto", "k", "m", "g", "t"]);
+		// qBittorrent speed defaults to bytes/sec.
+		expect(speed?.defaultConfig.unit).toBe("bytes_per_sec");
+	});
+
 	it("resolves a prometheus metric widget via the services list", () => {
 		const widget: WidgetInstance = {
 			id: "w1",
diff --git a/frontend/src/integrations/registry.ts b/frontend/src/integrations/registry.ts
index 6e138af..a515f71 100644
--- a/frontend/src/integrations/registry.ts
+++ b/frontend/src/integrations/registry.ts
@@ -48,6 +48,31 @@ export interface ServiceBinding {
 	widgets: ServiceWidgetBinding[];
 }
 
+/** Shared Y-axis format options mirrored on every graph widget kind. */
+const UNIT_VALUES = [
+	"none",
+	"bytes",
+	"bytes_per_sec",
+	"bits_per_sec",
+	"bits",
+	"percent",
+	"seconds",
+];
+const SCALE_VALUES = ["auto", "k", "m", "g", "t"];
+const AXIS_FORMAT_PROPERTIES = {
+	unit: {
+		type: "string",
+		enum: UNIT_VALUES,
+		description:
+			"Display unit; auto-scales the Y axis + tooltip (kB/MB/GB, kbps/Mbps, …)",
+	},
+	scale: {
+		type: "string",
+		enum: SCALE_VALUES,
+		description: "auto picks a prefix from the data; k/M/G/T force one",
+	},
+};
+
 export const SERVICE_REGISTRY: Record<string, ServiceBinding> = {
 	alertmanager: {
 		serviceType: "alertmanager",
@@ -94,7 +119,7 @@ export const SERVICE_REGISTRY: Record<string, ServiceBinding> = {
 				name: "Chart",
 				description: "Multi-series line chart from a PromQL range query.",
 				refreshIntervalMs: 60_000,
-				defaultConfig: { promql: "", window: "1h" },
+				defaultConfig: { promql: "", window: "1h", unit: "none", scale: "auto" },
 				configSchema: {
 					type: "object",
 					properties: {
@@ -106,6 +131,7 @@ export const SERVICE_REGISTRY: Record<string, ServiceBinding> = {
 							type: "string",
 							description: "Time window preset (1h, 6h, 24h, 7d)",
 						},
+						...AXIS_FORMAT_PROPERTIES,
 					},
 					required: ["promql"],
 				},
@@ -188,8 +214,12 @@ export const SERVICE_REGISTRY: Record<string, ServiceBinding> = {
 				name: "Speed chart",
 				description: "Live download/upload speed over a short window.",
 				refreshIntervalMs: 5_000,
-				defaultConfig: {},
-				configSchema: { type: "object", properties: {}, required: [] },
+				defaultConfig: { unit: "bytes_per_sec", scale: "auto" },
+				configSchema: {
+					type: "object",
+					properties: { ...AXIS_FORMAT_PROPERTIES },
+					required: [],
+				},
 				component: QbittorrentSpeedWidget,
 			},
 		],