@checkstack/dashboard-frontend 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # @checkstack/dashboard-frontend
 
+## 0.2.0
+
+### Minor Changes
+
+- 180be38: # Queue Lag Warning
+
+  Added a queue lag warning system that displays alerts when pending jobs exceed configurable thresholds.
+
+  ## Features
+
+  - **Backend Stats API**: New `getStats`, `getLagStatus`, and `updateLagThresholds` RPC endpoints
+  - **Signal-based Updates**: `QUEUE_LAG_CHANGED` signal for real-time frontend updates
+  - **Aggregated Stats**: `QueueManager.getAggregatedStats()` sums stats across all queues
+  - **Configurable Thresholds**: Warning (default 100) and Critical (default 500) thresholds stored in config
+  - **Dashboard Integration**: Queue lag alert displayed on main Dashboard (access-gated)
+  - **Queue Settings Page**: Lag alert and Performance Tuning guidance card with concurrency tips
+
+  ## UI Changes
+
+  - Queue lag alert banner appears on Dashboard and Queue Settings when pending jobs exceed thresholds
+  - New "Performance Tuning" card with concurrency settings guidance and bottleneck indicators
+
+- 7a23261: ## TanStack Query Integration
+
+  Migrated all frontend components to use `usePluginClient` hook with TanStack Query integration, replacing the legacy `forPlugin()` pattern.
+
+  ### New Features
+
+  - **`usePluginClient` hook**: Provides type-safe access to plugin APIs with `.useQuery()` and `.useMutation()` methods
+  - **Automatic request deduplication**: Multiple components requesting the same data share a single network request
+  - **Built-in caching**: Configurable stale time and cache duration per query
+  - **Loading/error states**: TanStack Query provides `isLoading`, `error`, `isRefetching` states automatically
+  - **Background refetching**: Stale data is automatically refreshed when components mount
+
+  ### Contract Changes
+
+  All RPC contracts now require `operationType: "query"` or `operationType: "mutation"` metadata:
+
+  ```typescript
+  const getItems = proc()
+    .meta({ operationType: "query", access: [access.read] })
+    .output(z.array(itemSchema))
+    .query();
+
+  const createItem = proc()
+    .meta({ operationType: "mutation", access: [access.manage] })
+    .input(createItemSchema)
+    .output(itemSchema)
+    .mutation();
+  ```
+
+  ### Migration
+
+  ```typescript
+  // Before (forPlugin pattern)
+  const api = useApi(myPluginApiRef);
+  const [items, setItems] = useState<Item[]>([]);
+  useEffect(() => {
+    api.getItems().then(setItems);
+  }, [api]);
+
+  // After (usePluginClient pattern)
+  const client = usePluginClient(MyPluginApi);
+  const { data: items, isLoading } = client.getItems.useQuery({});
+  ```
+
+  ### Bug Fixes
+
+  - Fixed `rpc.test.ts` test setup for middleware type inference
+  - Fixed `SearchDialog` to use `setQuery` instead of deprecated `search` method
+  - Fixed null→undefined warnings in notification and queue frontends
+
+### Patch Changes
+
+- Updated dependencies [180be38]
+- Updated dependencies [7a23261]
+  - @checkstack/queue-frontend@0.2.0
+  - @checkstack/frontend-api@0.2.0
+  - @checkstack/common@0.3.0
+  - @checkstack/auth-frontend@0.3.0
+  - @checkstack/catalog-frontend@0.3.0
+  - @checkstack/catalog-common@1.2.0
+  - @checkstack/command-frontend@0.2.0
+  - @checkstack/command-common@0.2.0
+  - @checkstack/healthcheck-common@0.4.0
+  - @checkstack/incident-common@0.3.0
+  - @checkstack/maintenance-common@0.3.0
+  - @checkstack/notification-common@0.2.0
+  - @checkstack/ui@0.2.1
+  - @checkstack/signal-frontend@0.0.7
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [9faec1f]
+- Updated dependencies [95eeec7]
+- Updated dependencies [f533141]
+  - @checkstack/auth-frontend@0.2.0
+  - @checkstack/catalog-common@1.1.0
+  - @checkstack/catalog-frontend@0.2.0
+  - @checkstack/command-common@0.1.0
+  - @checkstack/command-frontend@0.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/frontend-api@0.1.0
+  - @checkstack/healthcheck-common@0.3.0
+  - @checkstack/incident-common@0.2.0
+  - @checkstack/maintenance-common@0.2.0
+  - @checkstack/notification-common@0.1.0
+  - @checkstack/ui@0.2.0
+  - @checkstack/signal-frontend@0.0.6
+
 ## 0.1.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/dashboard-frontend",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.tsx",
   "scripts": {
@@ -9,22 +9,24 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/frontend-api": "workspace:*",
     "@checkstack/auth-frontend": "workspace:*",
-    "@checkstack/common": "workspace:*",
-    "@checkstack/command-frontend": "workspace:*",
-    "@checkstack/command-common": "workspace:*",
-    "@checkstack/notification-common": "workspace:*",
     "@checkstack/catalog-common": "workspace:*",
+    "@checkstack/catalog-frontend": "workspace:*",
+    "@checkstack/command-common": "workspace:*",
+    "@checkstack/command-frontend": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/frontend-api": "workspace:*",
+    "@checkstack/healthcheck-common": "workspace:*",
     "@checkstack/incident-common": "workspace:*",
     "@checkstack/maintenance-common": "workspace:*",
-    "@checkstack/healthcheck-common": "workspace:*",
+    "@checkstack/notification-common": "workspace:*",
+    "@checkstack/queue-frontend": "workspace:*",
     "@checkstack/signal-frontend": "workspace:*",
     "@checkstack/ui": "workspace:*",
-    "@checkstack/catalog-frontend": "workspace:*",
+    "@tanstack/react-query": "^5.90.18",
+    "lucide-react": "^0.344.0",
     "react": "^18.2.0",
-    "react-router-dom": "^6.22.0",
-    "lucide-react": "^0.344.0"
+    "react-router-dom": "^6.22.0"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/src/Dashboard.tsx

@@ -1,8 +1,12 @@
-import React, { useEffect, useState, useCallback } from "react";
+import React, { useState, useMemo } from "react";
 import { useNavigate } from "react-router-dom";
-import { useApi, rpcApiRef, ExtensionSlot } from "@checkstack/frontend-api";
-import { catalogApiRef } from "@checkstack/catalog-frontend";
 import {
+  useApi,
+  usePluginClient,
+  ExtensionSlot,
+} from "@checkstack/frontend-api";
+import {
+  CatalogApi,
   catalogRoutes,
   SystemStateBadgesSlot,
   System,
@@ -17,6 +21,7 @@ import { IncidentApi } from "@checkstack/incident-common";
 import { MaintenanceApi } from "@checkstack/maintenance-common";
 import { HEALTH_CHECK_RUN_COMPLETED } from "@checkstack/healthcheck-common";
 import { useSignal } from "@checkstack/signal-frontend";
+import { useQueryClient } from "@tanstack/react-query";
 import {
   Card,
   CardHeader,
@@ -42,20 +47,21 @@ import {
   Terminal,
 } from "lucide-react";
 import { authApiRef } from "@checkstack/auth-frontend/api";
+import { QueueLagAlert } from "@checkstack/queue-frontend";
+import { SystemBadgeDataProvider } from "./components/SystemBadgeDataProvider";
 
 const CATALOG_PLUGIN_ID = "catalog";
 const MAX_TERMINAL_ENTRIES = 8;
 
-const getGroupId = (groupId: string) => `${CATALOG_PLUGIN_ID}.group.${groupId}`;
-
 interface GroupWithSystems extends Group {
   systems: System[];
 }
 
-// Map health check status to terminal entry variant
+const getGroupId = (groupId: string) => `${CATALOG_PLUGIN_ID}:${groupId}`;
+
 const statusToVariant = (
-  status: "healthy" | "degraded" | "unhealthy"
-): TerminalEntry["variant"] => {
+  status: string
+): "default" | "success" | "warning" | "error" => {
   switch (status) {
     case "healthy": {
       return "success";
@@ -66,42 +72,117 @@ const statusToVariant = (
     case "unhealthy": {
       return "error";
     }
+    default: {
+      return "default";
+    }
   }
 };
 
 export const Dashboard: React.FC = () => {
-  const catalogApi = useApi(catalogApiRef);
-  const rpcApi = useApi(rpcApiRef);
-  const notificationApi = rpcApi.forPlugin(NotificationApi);
-  const incidentApi = rpcApi.forPlugin(IncidentApi);
-  const maintenanceApi = rpcApi.forPlugin(MaintenanceApi);
+  const catalogClient = usePluginClient(CatalogApi);
+  const notificationClient = usePluginClient(NotificationApi);
+  const incidentClient = usePluginClient(IncidentApi);
+  const maintenanceClient = usePluginClient(MaintenanceApi);
+
   const navigate = useNavigate();
   const toast = useToast();
   const authApi = useApi(authApiRef);
+  const queryClient = useQueryClient();
   const { data: session } = authApi.useSession();
 
-  const [groupsWithSystems, setGroupsWithSystems] = useState<
-    GroupWithSystems[]
-  >([]);
-  const [loading, setLoading] = useState(true);
-
-  // Overview statistics state
-  const [systemsCount, setSystemsCount] = useState(0);
-  const [activeIncidentsCount, setActiveIncidentsCount] = useState(0);
-  const [activeMaintenancesCount, setActiveMaintenancesCount] = useState(0);
-
   // Terminal feed entries from real healthcheck signals
   const [terminalEntries, setTerminalEntries] = useState<TerminalEntry[]>([]);
 
-  // Subscription state
-  const [subscriptions, setSubscriptions] = useState<EnrichedSubscription[]>(
-    []
-  );
+  // Track per-group loading state for subscribe buttons
   const [subscriptionLoading, setSubscriptionLoading] = useState<
     Record<string, boolean>
   >({});
 
-  // Listen for health check runs and add to terminal feed
+  // -------------------------------------------------------------------------
+  // DATA QUERIES
+  // -------------------------------------------------------------------------
+
+  // Fetch entities from catalog (groups and systems in one call)
+  const { data: entitiesData, isLoading: entitiesLoading } =
+    catalogClient.getEntities.useQuery({}, { staleTime: 30_000 });
+  const groups = entitiesData?.groups ?? [];
+  const systems = entitiesData?.systems ?? [];
+
+  // Fetch active incidents
+  const { data: incidentsData, isLoading: incidentsLoading } =
+    incidentClient.listIncidents.useQuery(
+      { includeResolved: false },
+      { staleTime: 30_000 }
+    );
+  const incidents = incidentsData?.incidents ?? [];
+
+  // Fetch active maintenances
+  const { data: maintenancesData, isLoading: maintenancesLoading } =
+    maintenanceClient.listMaintenances.useQuery(
+      { status: "in_progress" },
+      { staleTime: 30_000 }
+    );
+  const maintenances = maintenancesData?.maintenances ?? [];
+
+  // Fetch subscriptions (only when logged in)
+  const { data: subscriptions = [] } =
+    notificationClient.getSubscriptions.useQuery(
+      {},
+      { enabled: !!session, staleTime: 60_000 }
+    );
+
+  // Combined loading state
+  const loading = entitiesLoading || incidentsLoading || maintenancesLoading;
+
+  // -------------------------------------------------------------------------
+  // MUTATIONS
+  // -------------------------------------------------------------------------
+
+  const subscribeMutation = notificationClient.subscribe.useMutation({
+    onSuccess: () => {
+      toast.success("Subscribed to group notifications");
+      // Invalidate subscriptions query to refetch
+      queryClient.invalidateQueries({ queryKey: ["notification"] });
+    },
+    onError: (error: Error) => {
+      toast.error(error.message || "Failed to subscribe");
+    },
+  });
+
+  const unsubscribeMutation = notificationClient.unsubscribe.useMutation({
+    onSuccess: () => {
+      toast.success("Unsubscribed from group notifications");
+      queryClient.invalidateQueries({ queryKey: ["notification"] });
+    },
+    onError: (error: Error) => {
+      toast.error(error.message || "Failed to unsubscribe");
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // COMPUTED DATA
+  // -------------------------------------------------------------------------
+
+  // Derived statistics
+  const systemsCount = systems.length;
+  const activeIncidentsCount = incidents.length;
+  const activeMaintenancesCount = maintenances.length;
+
+  // Map groups to include their systems
+  const groupsWithSystems = useMemo<GroupWithSystems[]>(() => {
+    const systemMap = new Map(systems.map((s) => [s.id, s]));
+    return groups.map((group) => {
+      const groupSystems = (group.systemIds || [])
+        .map((id) => systemMap.get(id))
+        .filter((s): s is System => s !== undefined);
+      return { ...group, systems: groupSystems };
+    });
+  }, [groups, systems]);
+
+  // -------------------------------------------------------------------------
+  // SIGNAL HANDLERS
+  // -------------------------------------------------------------------------
+
   useSignal(
     HEALTH_CHECK_RUN_COMPLETED,
     ({ systemName, configurationName, status, latencyMs }) => {
@@ -119,45 +200,9 @@ export const Dashboard: React.FC = () => {
     }
   );
 
-  useEffect(() => {
-    if (session) {
-      notificationApi.getSubscriptions().then(setSubscriptions);
-    }
-  }, [session, notificationApi]);
-
-  useEffect(() => {
-    Promise.all([
-      catalogApi.getGroups(),
-      catalogApi.getSystems(),
-      incidentApi.listIncidents({ includeResolved: false }),
-      maintenanceApi.listMaintenances({ status: "in_progress" }),
-    ])
-      .then(([groups, { systems }, { incidents }, { maintenances }]) => {
-        // Set overview statistics
-        setSystemsCount(systems.length);
-        setActiveIncidentsCount(incidents.length);
-        setActiveMaintenancesCount(maintenances.length);
-
-        // Create a map of system IDs to systems
-        const systemMap = new Map(systems.map((s) => [s.id, s]));
-
-        // Map groups to include their systems
-        const groupsData: GroupWithSystems[] = groups.map((group) => {
-          const groupSystems = (group.systemIds || [])
-            .map((id) => systemMap.get(id))
-            .filter((s): s is System => s !== undefined);
-
-          return {
-            ...group,
-            systems: groupSystems,
-          };
-        });
-
-        setGroupsWithSystems(groupsData);
-      })
-      .catch(console.error)
-      .finally(() => setLoading(false));
-  }, [catalogApi, incidentApi, maintenanceApi]);
+  // -------------------------------------------------------------------------
+  // HANDLERS
+  // -------------------------------------------------------------------------
 
   const handleSystemClick = (systemId: string) => {
     navigate(resolveRoute(catalogRoutes.routes.systemDetail, { systemId }));
@@ -165,55 +210,40 @@ export const Dashboard: React.FC = () => {
 
   const isSubscribed = (groupId: string) => {
     const fullId = getGroupId(groupId);
-    return subscriptions.some((s) => s.groupId === fullId);
+    return subscriptions.some(
+      (s: EnrichedSubscription) => s.groupId === fullId
+    );
   };
 
-  const handleSubscribe = useCallback(
-    async (groupId: string) => {
-      const fullId = getGroupId(groupId);
-      setSubscriptionLoading((prev) => ({ ...prev, [groupId]: true }));
-      try {
-        await notificationApi.subscribe({ groupId: fullId });
-        setSubscriptions((prev) => [
-          ...prev,
-          {
-            groupId: fullId,
-            groupName: "",
-            groupDescription: "",
-            ownerPlugin: CATALOG_PLUGIN_ID,
-            subscribedAt: new Date(),
-          },
-        ]);
-        toast.success("Subscribed to group notifications");
-      } catch (error) {
-        const message =
-          error instanceof Error ? error.message : "Failed to subscribe";
-        toast.error(message);
-      } finally {
-        setSubscriptionLoading((prev) => ({ ...prev, [groupId]: false }));
+  const handleSubscribe = (groupId: string) => {
+    const fullId = getGroupId(groupId);
+    setSubscriptionLoading((prev) => ({ ...prev, [groupId]: true }));
+    subscribeMutation.mutate(
+      { groupId: fullId },
+      {
+        onSettled: () => {
+          setSubscriptionLoading((prev) => ({ ...prev, [groupId]: false }));
+        },
       }
-    },
-    [notificationApi, toast]
-  );
+    );
+  };
 
-  const handleUnsubscribe = useCallback(
-    async (groupId: string) => {
-      const fullId = getGroupId(groupId);
-      setSubscriptionLoading((prev) => ({ ...prev, [groupId]: true }));
-      try {
-        await notificationApi.unsubscribe({ groupId: fullId });
-        setSubscriptions((prev) => prev.filter((s) => s.groupId !== fullId));
-        toast.success("Unsubscribed from group notifications");
-      } catch (error) {
-        const message =
-          error instanceof Error ? error.message : "Failed to unsubscribe";
-        toast.error(message);
-      } finally {
-        setSubscriptionLoading((prev) => ({ ...prev, [groupId]: false }));
+  const handleUnsubscribe = (groupId: string) => {
+    const fullId = getGroupId(groupId);
+    setSubscriptionLoading((prev) => ({ ...prev, [groupId]: true }));
+    unsubscribeMutation.mutate(
+      { groupId: fullId },
+      {
+        onSettled: () => {
+          setSubscriptionLoading((prev) => ({ ...prev, [groupId]: false }));
+        },
       }
-    },
-    [notificationApi, toast]
-  );
+    );
+  };
+
+  // -------------------------------------------------------------------------
+  // RENDER
+  // -------------------------------------------------------------------------
 
   const renderGroupsContent = () => {
     if (loading) {
@@ -230,79 +260,89 @@ export const Dashboard: React.FC = () => {
       );
     }
 
+    // Collect all system IDs for bulk data fetching
+    const allSystemIds = groupsWithSystems.flatMap((g) =>
+      g.systems.map((s) => s.id)
+    );
+
     return (
-      <div className="space-y-4">
-        {groupsWithSystems.map((group) => (
-          <Card
-            key={group.id}
-            className="border-border shadow-sm hover:shadow-md transition-shadow"
-          >
-            <CardHeader className="border-b border-border bg-muted/30">
-              <div className="flex items-center gap-2">
-                <LayoutGrid className="h-5 w-5 text-muted-foreground" />
-                <CardTitle className="text-lg font-semibold text-foreground">
-                  {group.name}
-                </CardTitle>
-                <span className="ml-auto text-sm text-muted-foreground mr-2">
-                  {group.systems.length}{" "}
-                  {group.systems.length === 1 ? "system" : "systems"}
-                </span>
-                {session && (
-                  <SubscribeButton
-                    isSubscribed={isSubscribed(group.id)}
-                    onSubscribe={() => handleSubscribe(group.id)}
-                    onUnsubscribe={() => handleUnsubscribe(group.id)}
-                    loading={subscriptionLoading[group.id] || false}
-                  />
-                )}
-              </div>
-            </CardHeader>
-            <CardContent className="p-4">
-              {group.systems.length === 0 ? (
-                <div className="py-8 text-center">
-                  <p className="text-sm text-muted-foreground">
-                    No systems in this group yet
-                  </p>
+      <SystemBadgeDataProvider systemIds={allSystemIds}>
+        <div className="space-y-4">
+          {groupsWithSystems.map((group) => (
+            <Card
+              key={group.id}
+              className="border-border shadow-sm hover:shadow-md transition-shadow"
+            >
+              <CardHeader className="border-b border-border bg-muted/30">
+                <div className="flex items-center gap-2">
+                  <LayoutGrid className="h-5 w-5 text-muted-foreground" />
+                  <CardTitle className="text-lg font-semibold text-foreground">
+                    {group.name}
+                  </CardTitle>
+                  <span className="ml-auto text-sm text-muted-foreground mr-2">
+                    {group.systems.length}{" "}
+                    {group.systems.length === 1 ? "system" : "systems"}
+                  </span>
+                  {session && (
+                    <SubscribeButton
+                      isSubscribed={isSubscribed(group.id)}
+                      onSubscribe={() => handleSubscribe(group.id)}
+                      onUnsubscribe={() => handleUnsubscribe(group.id)}
+                      loading={subscriptionLoading[group.id] || false}
+                    />
+                  )}
                 </div>
-              ) : (
-                <div
-                  className={`grid gap-3 ${
-                    group.systems.length === 1
-                      ? "grid-cols-1"
-                      : "grid-cols-1 sm:grid-cols-2"
-                  }`}
-                >
-                  {group.systems.map((system) => (
-                    <button
-                      key={system.id}
-                      onClick={() => handleSystemClick(system.id)}
-                      className="flex items-center justify-between gap-3 rounded-lg border border-border bg-card px-4 py-3 transition-all cursor-pointer hover:border-border/80 hover:shadow-sm text-left"
-                    >
-                      <div className="flex items-center gap-3 min-w-0 flex-1">
-                        <Activity className="h-4 w-4 text-muted-foreground flex-shrink-0" />
-                        <p className="text-sm font-medium text-foreground truncate">
-                          {system.name}
-                        </p>
-                      </div>
-                      <ExtensionSlot
-                        slot={SystemStateBadgesSlot}
-                        context={{ system }}
-                      />
-                      <ChevronRight className="h-4 w-4 text-muted-foreground flex-shrink-0" />
-                    </button>
-                  ))}
-                </div>
-              )}
-            </CardContent>
-          </Card>
-        ))}
-      </div>
+              </CardHeader>
+              <CardContent className="p-4">
+                {group.systems.length === 0 ? (
+                  <div className="py-8 text-center">
+                    <p className="text-sm text-muted-foreground">
+                      No systems in this group yet
+                    </p>
+                  </div>
+                ) : (
+                  <div
+                    className={`grid gap-3 ${
+                      group.systems.length === 1
+                        ? "grid-cols-1"
+                        : "grid-cols-1 sm:grid-cols-2"
+                    }`}
+                  >
+                    {group.systems.map((system) => (
+                      <button
+                        key={system.id}
+                        onClick={() => handleSystemClick(system.id)}
+                        className="flex items-center justify-between gap-3 rounded-lg border border-border bg-card px-4 py-3 transition-all cursor-pointer hover:border-border/80 hover:shadow-sm text-left"
+                      >
+                        <div className="flex items-center gap-3 min-w-0 flex-1">
+                          <Activity className="h-4 w-4 text-muted-foreground flex-shrink-0" />
+                          <p className="text-sm font-medium text-foreground truncate">
+                            {system.name}
+                          </p>
+                        </div>
+                        <ExtensionSlot
+                          slot={SystemStateBadgesSlot}
+                          context={{ system }}
+                        />
+                        <ChevronRight className="h-4 w-4 text-muted-foreground flex-shrink-0" />
+                      </button>
+                    ))}
+                  </div>
+                )}
+              </CardContent>
+            </Card>
+          ))}
+        </div>
+      </SystemBadgeDataProvider>
     );
   };
 
   return (
     <>
       <div className="space-y-8 animate-in fade-in duration-500">
+        {/* Queue Lag Warning */}
+        <QueueLagAlert />
+
         {/* Overview Section */}
         <section>
           <SectionHeader

package/src/components/SystemBadgeDataProvider.tsx

@@ -0,0 +1,189 @@
+import React, { createContext, useContext, useCallback, useMemo } from "react";
+import { usePluginClient } from "@checkstack/frontend-api";
+import { useSignal } from "@checkstack/signal-frontend";
+import { useQueryClient } from "@tanstack/react-query";
+import {
+  HealthCheckApi,
+  HEALTH_CHECK_RUN_COMPLETED,
+  type SystemHealthStatusResponse,
+} from "@checkstack/healthcheck-common";
+import {
+  IncidentApi,
+  INCIDENT_UPDATED,
+  type IncidentWithSystems,
+} from "@checkstack/incident-common";
+import {
+  MaintenanceApi,
+  MAINTENANCE_UPDATED,
+  type MaintenanceWithSystems,
+} from "@checkstack/maintenance-common";
+
+/**
+ * Data structure for system badge data.
+ */
+export interface SystemBadgeData {
+  health?: SystemHealthStatusResponse;
+  incidents: IncidentWithSystems[];
+  maintenances: MaintenanceWithSystems[];
+}
+
+/**
+ * Context value provided by SystemBadgeDataProvider.
+ */
+interface SystemBadgeDataContextValue {
+  getSystemBadgeData: (systemId: string) => SystemBadgeData | undefined;
+  loading: boolean;
+}
+
+const SystemBadgeDataContext = createContext<
+  SystemBadgeDataContextValue | undefined
+>(undefined);
+
+interface SystemBadgeDataProviderProps {
+  systemIds: string[];
+  children: React.ReactNode;
+}
+
+/**
+ * Provider that bulk-fetches badge data (health, incidents, maintenances)
+ * for multiple systems using TanStack Query and provides it via context.
+ */
+export const SystemBadgeDataProvider: React.FC<
+  SystemBadgeDataProviderProps
+> = ({ systemIds, children }) => {
+  const queryClient = useQueryClient();
+  const healthCheckClient = usePluginClient(HealthCheckApi);
+  const incidentClient = usePluginClient(IncidentApi);
+  const maintenanceClient = usePluginClient(MaintenanceApi);
+
+  // -------------------------------------------------------------------------
+  // BULK QUERIES
+  // -------------------------------------------------------------------------
+
+  // Fetch bulk health status
+  const { data: healthData, isLoading: healthLoading } =
+    healthCheckClient.getBulkSystemHealthStatus.useQuery(
+      { systemIds },
+      { enabled: systemIds.length > 0, staleTime: 30_000 }
+    );
+
+  // Fetch bulk incidents
+  const { data: incidentData, isLoading: incidentLoading } =
+    incidentClient.getBulkIncidentsForSystems.useQuery(
+      { systemIds },
+      { enabled: systemIds.length > 0, staleTime: 30_000 }
+    );
+
+  // Fetch bulk maintenances
+  const { data: maintenanceData, isLoading: maintenanceLoading } =
+    maintenanceClient.getBulkMaintenancesForSystems.useQuery(
+      { systemIds },
+      { enabled: systemIds.length > 0, staleTime: 30_000 }
+    );
+
+  const loading = healthLoading || incidentLoading || maintenanceLoading;
+
+  // -------------------------------------------------------------------------
+  // SIGNAL HANDLERS - Invalidate queries on updates
+  // -------------------------------------------------------------------------
+
+  const refetchHealth = useCallback(
+    (systemId: string) => {
+      if (systemIds.includes(systemId)) {
+        // Invalidate the bulk query to refetch
+        queryClient.invalidateQueries({ queryKey: ["healthcheck"] });
+      }
+    },
+    [systemIds, queryClient]
+  );
+
+  useSignal(HEALTH_CHECK_RUN_COMPLETED, ({ systemId }) => {
+    refetchHealth(systemId);
+  });
+
+  const refetchIncidents = useCallback(
+    (affectedSystemIds: string[]) => {
+      const hasAffected = affectedSystemIds.some((id) =>
+        systemIds.includes(id)
+      );
+      if (hasAffected) {
+        queryClient.invalidateQueries({ queryKey: ["incident"] });
+      }
+    },
+    [systemIds, queryClient]
+  );
+
+  useSignal(INCIDENT_UPDATED, ({ systemIds: affectedIds }) => {
+    refetchIncidents(affectedIds);
+  });
+
+  const refetchMaintenances = useCallback(
+    (affectedSystemIds: string[]) => {
+      const hasAffected = affectedSystemIds.some((id) =>
+        systemIds.includes(id)
+      );
+      if (hasAffected) {
+        queryClient.invalidateQueries({ queryKey: ["maintenance"] });
+      }
+    },
+    [systemIds, queryClient]
+  );
+
+  useSignal(MAINTENANCE_UPDATED, ({ systemIds: affectedIds }) => {
+    refetchMaintenances(affectedIds);
+  });
+
+  // -------------------------------------------------------------------------
+  // CONTEXT VALUE
+  // -------------------------------------------------------------------------
+
+  const getSystemBadgeData = useCallback(
+    (systemId: string): SystemBadgeData | undefined => {
+      const health = healthData?.statuses[systemId];
+      const incidents = incidentData?.incidents[systemId];
+      const maintenances = maintenanceData?.maintenances[systemId];
+
+      // Return undefined if no data loaded yet
+      if (!health && !incidents && !maintenances) {
+        return undefined;
+      }
+
+      return {
+        health,
+        incidents: incidents || [],
+        maintenances: maintenances || [],
+      };
+    },
+    [healthData, incidentData, maintenanceData]
+  );
+
+  const contextValue = useMemo(
+    () => ({
+      getSystemBadgeData,
+      loading,
+    }),
+    [getSystemBadgeData, loading]
+  );
+
+  return (
+    <SystemBadgeDataContext.Provider value={contextValue}>
+      {children}
+    </SystemBadgeDataContext.Provider>
+  );
+};
+
+export function useSystemBadgeData(): SystemBadgeDataContextValue {
+  const context = useContext(SystemBadgeDataContext);
+  if (!context) {
+    throw new Error(
+      "useSystemBadgeData must be used within a SystemBadgeDataProvider"
+    );
+  }
+  return context;
+}
+
+export function useSystemBadgeDataOptional():
+  | SystemBadgeDataContextValue
+  | undefined {
+  return useContext(SystemBadgeDataContext);
+}

package/src/index.tsx

@@ -18,3 +18,11 @@ export const dashboardPlugin: FrontendPlugin = {
 };
 
 export default dashboardPlugin;
+
+// Export provider for use in other plugins
+export {
+  SystemBadgeDataProvider,
+  useSystemBadgeData,
+  useSystemBadgeDataOptional,
+  type SystemBadgeData,
+} from "./components/SystemBadgeDataProvider";