,
+): ResourceStatus {
+ return {
+ severity: "pending",
+ startedAt: Date.now(),
+ ...overrides,
+ };
+}
+
+describe("useResourceStatus / useResourceStatusPublisher", () => {
+ test("returns the empty/idle aggregate when no provider is mounted", () => {
+ const { result } = renderHook(() => useResourceStatus());
+ expect(result.current).toEqual({
+ worst: null,
+ byKind: {},
+ affectedLabels: [],
+ activeCount: 0,
+ elapsedMs: 0,
+ version: 0,
+ });
+ });
+
+ test("aggregates statuses across kinds, picking the worst by severity", async () => {
+ function Publishers() {
+ const { publish: pubA } = useResourceStatusPublisher("a", "lakebase-a");
+ const { publish: pubB } = useResourceStatusPublisher("b", "warehouse-b");
+ const aggregate = useResourceStatus();
+ return (
+
+
+ {aggregate.worst?.kind ?? "none"}
+
+
+ {aggregate.worst?.state ?? "none"}
+
+ {aggregate.activeCount}
+ {aggregate.affectedLabels.join(",")}
+ {
+ pubA(
+ makeStatus({
+ kind: "lakebase",
+ state: "STARTING",
+ severity: "pending",
+ }),
+ );
+ }}
+ />
+ {
+ pubB(
+ makeStatus({
+ kind: "warehouse",
+ state: "DELETED",
+ severity: "error",
+ }),
+ );
+ }}
+ />
+
+ );
+ }
+
+ const { getByTestId } = render(
+
+ ,
+ );
+
+ // a: lakebase pending
+ act(() => {
+ getByTestId("pub-pending-a").click();
+ });
+ await waitFor(() => {
+ expect(getByTestId("worst-kind").textContent).toBe("lakebase");
+ });
+ expect(getByTestId("worst-state").textContent).toBe("STARTING");
+ expect(getByTestId("active").textContent).toBe("1");
+ expect(getByTestId("labels").textContent).toBe("lakebase-a");
+
+ // b: warehouse error → outranks pending
+ act(() => {
+ getByTestId("pub-error-b").click();
+ });
+ await waitFor(() => {
+ expect(getByTestId("worst-kind").textContent).toBe("warehouse");
+ });
+ expect(getByTestId("worst-state").textContent).toBe("DELETED");
+ expect(getByTestId("active").textContent).toBe("2");
+ expect(getByTestId("labels").textContent).toBe("lakebase-a,warehouse-b");
+ });
+
+ test("filters the aggregate to a single kind", async () => {
+ function Publishers() {
+ const { publish: pubA } = useResourceStatusPublisher("a", "lakebase-a");
+ const { publish: pubB } = useResourceStatusPublisher("b", "warehouse-b");
+ const warehouseAgg = useResourceStatus({ kind: "warehouse" });
+ return (
+
+
+ {warehouseAgg.worst?.state ?? "none"}
+
+ {warehouseAgg.activeCount}
+ {
+ pubA(
+ makeStatus({
+ kind: "lakebase",
+ state: "STARTING",
+ severity: "pending",
+ }),
+ );
+ }}
+ />
+ {
+ pubB(
+ makeStatus({
+ kind: "warehouse",
+ state: "STOPPED",
+ severity: "pending",
+ }),
+ );
+ }}
+ />
+
+ );
+ }
+
+ const { getByTestId } = render(
+
+ ,
+ );
+
+ // Lakebase publishes — warehouse-scoped aggregate stays empty.
+ act(() => {
+ getByTestId("pub-lakebase").click();
+ });
+ await waitFor(() => {
+ expect(getByTestId("warehouse-state").textContent).toBe("none");
+ });
+
+ // Warehouse publishes — warehouse-scoped aggregate lights up.
+ act(() => {
+ getByTestId("pub-warehouse").click();
+ });
+ await waitFor(() => {
+ expect(getByTestId("warehouse-state").textContent).toBe("STOPPED");
+ });
+ expect(getByTestId("warehouse-active").textContent).toBe("1");
+ });
+
+ test("kindHint keeps null-status slots associated with their kind", async () => {
+ function Publisher() {
+ const { publish } = useResourceStatusPublisher("a", "x", {
+ kindHint: "lakebase",
+ });
+ const lakebase = useResourceStatus({ kind: "lakebase" });
+ return (
+
+ {lakebase.activeCount}
+
+ {lakebase.worst?.state ?? "none"}
+
+ {
+ publish(null);
+ }}
+ />
+
+ );
+ }
+
+ const { getByTestId } = render(
+
+ ,
+ );
+
+ act(() => {
+ getByTestId("register").click();
+ });
+ await waitFor(() => {
+ expect(getByTestId("lakebase-active").textContent).toBe("1");
+ expect(getByTestId("lakebase-state").textContent).toBe("none");
+ });
+ });
+
+ test("unpublish removes the entry from the aggregate", async () => {
+ function App() {
+ const { publish, unpublish } = useResourceStatusPublisher("a", "x");
+ const aggregate = useResourceStatus();
+ return (
+
+ {aggregate.activeCount}
+ {aggregate.worst?.state ?? "none"}
+ {
+ publish(
+ makeStatus({
+ kind: "warehouse",
+ state: "STOPPED",
+ severity: "pending",
+ }),
+ );
+ }}
+ />
+ {
+ unpublish();
+ }}
+ />
+
+ );
+ }
+
+ const { getByTestId } = render(
+
+ ,
+ );
+
+ act(() => {
+ getByTestId("pub").click();
+ });
+ await waitFor(() => {
+ expect(getByTestId("state").textContent).toBe("STOPPED");
+ });
+
+ act(() => {
+ getByTestId("unpub").click();
+ });
+ await waitFor(() => {
+ expect(getByTestId("state").textContent).toBe("none");
+ });
+ expect(getByTestId("active").textContent).toBe("0");
+ });
+});
+
+describe("ResourceStatusIndicator", () => {
+ test("mounts no toast when the aggregate is empty", () => {
+ render(
+
+ ,
+ );
+ expect(queryIndicatorToast()).toBeNull();
+ });
+
+ test("renders kind-specific copy for known kinds (warehouse)", async () => {
+ function Trigger() {
+ const { publish } = useResourceStatusPublisher("a", "my_chart");
+ return (
+ {
+ publish(
+ makeStatus({
+ kind: "warehouse",
+ state: "STARTING",
+ severity: "pending",
+ }),
+ );
+ }}
+ />
+ );
+ }
+
+ const { getByTestId } = render(
+
+ ,
+ );
+
+ act(() => {
+ getByTestId("pub").click();
+ });
+
+ const node = await findIndicatorToast();
+ expect(node.getAttribute("data-type")).toBe("loading");
+ expect(node.textContent).toMatch(/warming up|warehouse/i);
+ });
+
+ test("falls back to a generic message for unknown kinds", async () => {
+ function Trigger() {
+ const { publish } = useResourceStatusPublisher("a", "my_thing");
+ return (
+ {
+ publish(
+ makeStatus({
+ kind: "model-endpoint",
+ state: "COLD_START",
+ severity: "pending",
+ }),
+ );
+ }}
+ />
+ );
+ }
+
+ const { getByTestId } = render(
+
+ ,
+ );
+
+ act(() => {
+ getByTestId("pub").click();
+ });
+
+ const node = await findIndicatorToast();
+ // Humanized kind name (Model Endpoint) appears in the title.
+ expect(node.textContent).toMatch(/Model Endpoint/i);
+ });
+
+ test("uses the error treatment for error severity", async () => {
+ function Trigger() {
+ const { publish } = useResourceStatusPublisher("a", "my_thing");
+ return (
+ {
+ publish(
+ makeStatus({
+ kind: "warehouse",
+ state: "DELETED",
+ severity: "error",
+ summary: "It is gone",
+ }),
+ );
+ }}
+ />
+ );
+ }
+
+ const { getByTestId } = render(
+
+ ,
+ );
+
+ act(() => {
+ getByTestId("pub").click();
+ });
+
+ const node = await findIndicatorToast();
+ expect(node.getAttribute("data-type")).toBe("error");
+ expect(node.textContent).toMatch(/unavailable|It is gone/i);
+ });
+
+ test("morphs from loading to error when severity flips within a kind", async () => {
+ function Trigger() {
+ const { publish } = useResourceStatusPublisher("a", "my_chart");
+ return (
+
+ {
+ publish(
+ makeStatus({
+ kind: "warehouse",
+ state: "STARTING",
+ severity: "pending",
+ }),
+ );
+ }}
+ />
+ {
+ publish(
+ makeStatus({
+ kind: "warehouse",
+ state: "DELETED",
+ severity: "error",
+ summary: "Gone",
+ }),
+ );
+ }}
+ />
+
+ );
+ }
+
+ const { getByTestId } = render(
+
+ ,
+ );
+
+ act(() => {
+ getByTestId("pub-pending").click();
+ });
+ const loading = await findIndicatorToast();
+ expect(loading.getAttribute("data-type")).toBe("loading");
+
+ act(() => {
+ getByTestId("pub-error").click();
+ });
+ await waitFor(() => {
+ expect(queryIndicatorToast()?.getAttribute("data-type")).toBe("error");
+ });
+ expect(queryIndicatorToast()?.textContent).toMatch(/unavailable|Gone/i);
+ });
+
+ test("kind prop scopes to a single kind", async () => {
+ function Trigger() {
+ const { publish: pubLake } = useResourceStatusPublisher("a", "x");
+ const { publish: pubWh } = useResourceStatusPublisher("b", "y");
+ return (
+
+ {
+ pubLake(
+ makeStatus({
+ kind: "lakebase",
+ state: "STARTING",
+ severity: "pending",
+ }),
+ );
+ }}
+ />
+ {
+ pubWh(
+ makeStatus({
+ kind: "warehouse",
+ state: "STARTING",
+ severity: "pending",
+ }),
+ );
+ }}
+ />
+
+ );
+ }
+
+ const { getByTestId } = render(
+
+ ,
+ );
+
+ // Lakebase pending — warehouse-scoped indicator stays silent.
+ act(() => {
+ getByTestId("pub-lake").click();
+ });
+ expect(queryIndicatorToast()).toBeNull();
+
+ // Warehouse pending — toast appears.
+ act(() => {
+ getByTestId("pub-wh").click();
+ });
+ const node = await findIndicatorToast();
+ expect(node.textContent).toMatch(/warehouse|warming/i);
+ });
+
+ test("supports a full custom render override", async () => {
+ function Trigger() {
+ const { publish } = useResourceStatusPublisher("a", "x");
+ return (
+ {
+ publish(
+ makeStatus({
+ kind: "warehouse",
+ state: "STARTING",
+ severity: "pending",
+ }),
+ );
+ }}
+ />
+ );
+ }
+
+ const { getByTestId, findByTestId } = render(
+
+ (
+
+ {agg.worst?.kind}:{agg.worst?.state}:{agg.activeCount}
+
+ )}
+ />
+ ,
+ );
+
+ act(() => {
+ getByTestId("pub").click();
+ });
+ const custom = await findByTestId("custom");
+ expect(custom.textContent).toBe("warehouse:STARTING:1");
+ });
+
+ test("ticks the elapsed counter at ~1Hz while a wait is active", async () => {
+ // Pin Date.now without fake timers — fake setInterval conflicts with
+ // sonner's rAF/setTimeout-driven mount lifecycle. The indicator's
+ // real setInterval re-issues toast updates against the moving clock.
+ const dateNowSpy = vi.spyOn(Date, "now").mockReturnValue(1_000_000);
+
+ function Trigger() {
+ const { publish } = useResourceStatusPublisher("a", "my_chart");
+ return (
+ {
+ publish({
+ kind: "warehouse",
+ state: "STARTING",
+ severity: "pending",
+ startedAt: Date.now(),
+ });
+ }}
+ />
+ );
+ }
+
+ try {
+ const { getByTestId } = render(
+
+ ,
+ );
+
+ act(() => {
+ getByTestId("pub").click();
+ });
+
+ const initial = await findIndicatorToast();
+ expect(initial.textContent).toMatch(/0s/);
+
+ // Advance 3.5s; the indicator's ~1Hz tick re-issues toast.loading.
+ dateNowSpy.mockReturnValue(1_000_000 + 3_500);
+
+ await waitFor(
+ () => {
+ expect(queryIndicatorToast()?.textContent).toMatch(/3s/);
+ },
+ { timeout: 2_000 },
+ );
+ } finally {
+ dateNowSpy.mockRestore();
+ }
+ });
+});
diff --git a/packages/appkit-ui/src/react/hooks/index.ts b/packages/appkit-ui/src/react/hooks/index.ts
index e272616d2..63b639761 100644
--- a/packages/appkit-ui/src/react/hooks/index.ts
+++ b/packages/appkit-ui/src/react/hooks/index.ts
@@ -1,3 +1,10 @@
+export {
+ type ResourceKindRenderer,
+ ResourceStatusIndicator,
+ type ResourceStatusIndicatorProps,
+ type ResourceStatusToasterOptions,
+ useResourceStatusToaster,
+} from "../resource-status-indicator";
export type {
AnalyticsFormat,
InferResultByFormat,
@@ -12,6 +19,8 @@ export type {
TypedArrowTable,
UseAnalyticsQueryOptions,
UseAnalyticsQueryResult,
+ WarehouseState,
+ WarehouseStatus,
} from "./types";
export {
type AgentChatEvent,
@@ -27,6 +36,16 @@ export {
} from "./use-chart-data";
export { useIsMobile } from "./use-mobile";
export { usePluginClientConfig } from "./use-plugin-config";
+export {
+ type AggregatedResourceStatus,
+ type ResourceSeverity,
+ type ResourceStatus,
+ type ResourceStatusFilter,
+ ResourceStatusProvider,
+ type ResourceStatusProviderProps,
+ useResourceStatus,
+ useResourceStatusPublisher,
+} from "./use-resource-status";
export {
type UseServingInvokeOptions,
type UseServingInvokeResult,
diff --git a/packages/appkit-ui/src/react/hooks/types.ts b/packages/appkit-ui/src/react/hooks/types.ts
index 60fc5f63b..8d96b6174 100644
--- a/packages/appkit-ui/src/react/hooks/types.ts
+++ b/packages/appkit-ui/src/react/hooks/types.ts
@@ -57,6 +57,35 @@ export interface UseAnalyticsQueryOptions<
autoStart?: boolean;
}
+/**
+ * SQL warehouse lifecycle state surfaced by `useAnalyticsQuery`.
+ * Mirrors the states emitted by the analytics plugin (which mirror the
+ * Databricks SQL SDK `sql.State`).
+ */
+export type WarehouseState =
+ | "RUNNING"
+ | "STARTING"
+ | "STOPPED"
+ | "STOPPING"
+ | "DELETED"
+ | "DELETING";
+
+/**
+ * Snapshot of warehouse readiness streamed by the analytics route before the
+ * SQL result. Useful for rendering "warehouse starting…" affordances during
+ * cold starts instead of a frozen spinner.
+ *
+ * Note: the SDK's `health.summary` is intentionally NOT included on the wire
+ * — it's free-form operator-oriented diagnostic text (cluster IDs, capacity
+ * reasons, internal RPC errors) that must not reach end users; it stays in
+ * server-side telemetry only.
+ */
+export interface WarehouseStatus {
+ state: WarehouseState;
+ /** Milliseconds elapsed since the route began waiting for the warehouse. */
+ elapsedMs: number;
+}
+
/** Result state returned by useAnalyticsQuery */
export interface UseAnalyticsQueryResult {
/** Latest query result data */
@@ -65,6 +94,12 @@ export interface UseAnalyticsQueryResult {
loading: boolean;
/** Error state of the query */
error: string | null;
+ /**
+ * Latest warehouse status emitted by the server while waiting for the SQL
+ * warehouse to reach RUNNING. `null` until the first status event arrives;
+ * remains `null` for cache hits where the server skips the readiness check.
+ */
+ warehouseStatus: WarehouseStatus | null;
}
/**
diff --git a/packages/appkit-ui/src/react/hooks/use-analytics-query.ts b/packages/appkit-ui/src/react/hooks/use-analytics-query.ts
index 05a32ee02..de914a77c 100644
--- a/packages/appkit-ui/src/react/hooks/use-analytics-query.ts
+++ b/packages/appkit-ui/src/react/hooks/use-analytics-query.ts
@@ -1,4 +1,11 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+ useCallback,
+ useEffect,
+ useId,
+ useMemo,
+ useRef,
+ useState,
+} from "react";
import { ArrowClient, connectSSE } from "@/js";
import type {
AnalyticsFormat,
@@ -7,17 +14,12 @@ import type {
QueryKey,
UseAnalyticsQueryOptions,
UseAnalyticsQueryResult,
+ WarehouseStatus,
} from "./types";
+import { useAnalyticsWarehousePublisher } from "./use-analytics-warehouse-status";
import { useQueryHMR } from "./use-query-hmr";
-/**
- * Shallow structural equality for analytics query parameter objects.
- *
- * Analytics query parameters are produced by the `sql.*` builders and are
- * always plain objects keyed to primitive values (string | number | boolean
- * | null | undefined), so shallow equality is sufficient and substantially
- * cheaper than a full deep-equal.
- */
+/** Shallow equality for plain-object query parameters (primitive values only). */
function shallowEqualParams(a: unknown, b: unknown): boolean {
if (Object.is(a, b)) return true;
if (
@@ -45,12 +47,7 @@ function shallowEqualParams(a: unknown, b: unknown): boolean {
return true;
}
-/**
- * Stabilize a value's identity across renders when it is structurally equal
- * to the previous value. Used to make object-literal parameters safe to pass
- * directly to `useAnalyticsQuery` without forcing every consumer to wrap
- * params in `useMemo`.
- */
+/** Keep structurally-equal params referentially stable across renders. */
function useStableParams(value: T): T {
const ref = useRef(value);
if (!shallowEqualParams(ref.current, value)) {
@@ -59,18 +56,95 @@ function useStableParams(value: T): T {
return ref.current;
}
-function getDevMode() {
- const url = new URL(window.location.href);
- const searchParams = url.searchParams;
- const dev = searchParams.get("dev");
-
+function getDevMode(): string {
+ const dev = new URL(window.location.href).searchParams.get("dev");
return dev ? `?dev=${dev}` : "";
}
-function getArrowStreamUrl(id: string) {
+function getArrowStreamUrl(id: string): string {
return `/api/analytics/arrow-result/${id}`;
}
+const GENERIC_LOAD_ERROR = "Unable to load data, please try again";
+
+interface AnalyticsQuerySseContext {
+ setLoading: (loading: boolean) => void;
+ setError: (error: string | null) => void;
+ setData: (data: ResultType | null) => void;
+ setWarehouseStatus: (status: WarehouseStatus | null) => void;
+ publishWarehouseStatus: (status: WarehouseStatus | null) => void;
+ unpublishWarehouseStatus: () => void;
+}
+
+function isWarehouseStatusPayload(value: unknown): value is WarehouseStatus {
+ return (
+ typeof value === "object" &&
+ value !== null &&
+ typeof (value as WarehouseStatus).state === "string"
+ );
+}
+
+async function handleAnalyticsSseMessage(
+ parsed: Record,
+ ctx: AnalyticsQuerySseContext,
+): Promise {
+ if (parsed.type === "warehouse_status") {
+ if (!isWarehouseStatusPayload(parsed.status)) {
+ ctx.setLoading(false);
+ ctx.setError(GENERIC_LOAD_ERROR);
+ ctx.unpublishWarehouseStatus();
+ console.error(
+ "[useAnalyticsQuery] Malformed warehouse_status event",
+ parsed,
+ );
+ return;
+ }
+ ctx.setWarehouseStatus(parsed.status);
+ ctx.publishWarehouseStatus(parsed.status);
+ return;
+ }
+
+ if (parsed.type === "result") {
+ ctx.setLoading(false);
+ ctx.setData(parsed.data as ResultType);
+ ctx.unpublishWarehouseStatus();
+ return;
+ }
+
+ if (parsed.type === "arrow") {
+ try {
+ const arrowData = await ArrowClient.fetchArrow(
+ getArrowStreamUrl(parsed.statement_id as string),
+ );
+ const table = await ArrowClient.processArrowBuffer(arrowData);
+ ctx.setLoading(false);
+ ctx.setData(table as ResultType);
+ ctx.unpublishWarehouseStatus();
+ } catch (error) {
+ console.error("[useAnalyticsQuery] Failed to fetch Arrow data", error);
+ ctx.setLoading(false);
+ ctx.setError(GENERIC_LOAD_ERROR);
+ ctx.unpublishWarehouseStatus();
+ }
+ return;
+ }
+
+ if (parsed.type === "error" || parsed.error || parsed.code) {
+ const errorMsg =
+ (parsed.error as string | undefined) ||
+ (parsed.message as string | undefined) ||
+ "Unable to execute query";
+ ctx.setLoading(false);
+ ctx.setError(errorMsg);
+ ctx.unpublishWarehouseStatus();
+ if (parsed.code) {
+ console.error(
+ `[useAnalyticsQuery] Code: ${parsed.code}, Message: ${errorMsg}`,
+ );
+ }
+ }
+}
+
/**
* Subscribe to an analytics query over SSE and returns its latest result.
* Integration hook between client and analytics plugin.
@@ -120,18 +194,22 @@ export function useAnalyticsQuery<
const [data, setData] = useState(null);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);
+ const [warehouseStatus, setWarehouseStatus] =
+ useState(null);
const abortControllerRef = useRef(null);
+ const publisherId = useId();
+ const {
+ publish: publishWarehouseStatus,
+ unpublish: unpublishWarehouseStatus,
+ } = useAnalyticsWarehousePublisher(publisherId, queryKey);
+
if (!queryKey || queryKey.trim().length === 0) {
throw new Error(
"useAnalyticsQuery: 'queryKey' must be a non-empty string.",
);
}
- // Stabilize the parameters reference across renders. Without this, a fresh
- // object literal at the call site (e.g. `useAnalyticsQuery("k", { limit: 10 })`)
- // would change identity every render, invalidating the `payload` memo and
- // re-running `start` -> infinite refetch loop.
const stableParameters = useStableParams(parameters);
const payload = useMemo(() => {
@@ -160,70 +238,34 @@ export function useAnalyticsQuery<
return;
}
- // Abort previous request if exists
- if (abortControllerRef.current) {
- abortControllerRef.current.abort();
- }
+ abortControllerRef.current?.abort();
setLoading(true);
setError(null);
setData(null);
+ setWarehouseStatus(null);
+ publishWarehouseStatus(null);
const abortController = new AbortController();
abortControllerRef.current = abortController;
+ const sseContext: AnalyticsQuerySseContext = {
+ setLoading,
+ setError,
+ setData,
+ setWarehouseStatus,
+ publishWarehouseStatus,
+ unpublishWarehouseStatus,
+ };
+
connectSSE({
url: urlSuffix,
- payload: payload,
+ payload,
signal: abortController.signal,
onMessage: async (message) => {
try {
- const parsed = JSON.parse(message.data);
-
- // success - JSON format
- if (parsed.type === "result") {
- setLoading(false);
- setData(parsed.data as ResultType);
- return;
- }
-
- // success - Arrow format
- if (parsed.type === "arrow") {
- try {
- const arrowData = await ArrowClient.fetchArrow(
- getArrowStreamUrl(parsed.statement_id),
- );
- const table = await ArrowClient.processArrowBuffer(arrowData);
- setLoading(false);
- // Table is cast to TypedArrowTable with row type from QueryRegistry
- setData(table as ResultType);
- return;
- } catch (error) {
- console.error(
- "[useAnalyticsQuery] Failed to fetch Arrow data",
- error,
- );
- setLoading(false);
- setError("Unable to load data, please try again");
- return;
- }
- }
-
- // error
- if (parsed.type === "error" || parsed.error || parsed.code) {
- const errorMsg =
- parsed.error || parsed.message || "Unable to execute query";
-
- setLoading(false);
- setError(errorMsg);
-
- if (parsed.code) {
- console.error(
- `[useAnalyticsQuery] Code: ${parsed.code}, Message: ${errorMsg}`,
- );
- }
- return;
- }
+ const parsed = JSON.parse(message.data) as Record;
+ await handleAnalyticsSseMessage(parsed, sseContext);
} catch (error) {
console.warn("[useAnalyticsQuery] Malformed message received", error);
}
@@ -231,16 +273,15 @@ export function useAnalyticsQuery<
onError: (error) => {
if (abortController.signal.aborted) return;
setLoading(false);
+ unpublishWarehouseStatus();
- let userMessage = "Unable to load data, please try again";
-
+ let userMessage = GENERIC_LOAD_ERROR;
if (error instanceof Error) {
if (error.name === "AbortError") {
userMessage = "Request timed out, please try again";
} else if (error.message.includes("Failed to fetch")) {
userMessage = "Network error. Please check your connection.";
}
-
console.error("[useAnalyticsQuery] Error", {
queryKey,
error: error.message,
@@ -250,7 +291,13 @@ export function useAnalyticsQuery<
setError(userMessage);
},
});
- }, [queryKey, payload, urlSuffix]);
+ }, [
+ queryKey,
+ payload,
+ urlSuffix,
+ publishWarehouseStatus,
+ unpublishWarehouseStatus,
+ ]);
useEffect(() => {
if (autoStart) {
@@ -259,11 +306,11 @@ export function useAnalyticsQuery<
return () => {
abortControllerRef.current?.abort();
+ unpublishWarehouseStatus();
};
- }, [start, autoStart]);
+ }, [start, autoStart, unpublishWarehouseStatus]);
- // Enable HMR for query updates in dev mode
useQueryHMR(queryKey, start);
- return { data, loading, error };
+ return { data, loading, error, warehouseStatus };
}
diff --git a/packages/appkit-ui/src/react/hooks/use-analytics-warehouse-status.ts b/packages/appkit-ui/src/react/hooks/use-analytics-warehouse-status.ts
new file mode 100644
index 000000000..a45559f9f
--- /dev/null
+++ b/packages/appkit-ui/src/react/hooks/use-analytics-warehouse-status.ts
@@ -0,0 +1,74 @@
+import { useCallback, useRef } from "react";
+import type { WarehouseStatus } from "./types";
+import {
+ type ResourceSeverity,
+ useResourceStatusPublisher,
+} from "./use-resource-status";
+
+const ANALYTICS_WAREHOUSE_RESOURCE_KIND = "warehouse";
+
+/**
+ * - `RUNNING` → `null`; callers `unpublish` instead.
+ * - `STARTING` / `STOPPED` / `STOPPING` → `pending`.
+ * - `DELETED` / `DELETING` → `error` (config change required).
+ */
+function severityForWarehouseState(
+ state: WarehouseStatus["state"],
+): ResourceSeverity | null {
+ switch (state) {
+ case "RUNNING":
+ return null;
+ case "DELETED":
+ case "DELETING":
+ return "error";
+ default:
+ return "pending";
+ }
+}
+
+/**
+ * Internal hook used by `useAnalyticsQuery` to mirror its current warehouse
+ * status into the nearest provider. No-op when no provider is mounted.
+ */
+export function useAnalyticsWarehousePublisher(
+ id: string,
+ queryKey: string,
+): {
+ publish: (status: WarehouseStatus | null) => void;
+ unpublish: () => void;
+} {
+ const { publish: publishGeneric, unpublish } = useResourceStatusPublisher(
+ id,
+ queryKey,
+ { kindHint: ANALYTICS_WAREHOUSE_RESOURCE_KIND },
+ );
+
+ // Anchor `startedAt` to the first non-null status so `elapsedMs`
+ // advances monotonically across successive `warehouse_status` events.
+ const startedAtRef = useRef(null);
+
+ const publish = useCallback(
+ (status: WarehouseStatus | null) => {
+ // null covers "register with no status yet" *and* RUNNING — both
+ // keep the slot registered without contributing to the aggregate.
+ const severity = status && severityForWarehouseState(status.state);
+ if (!status || !severity) {
+ startedAtRef.current = null;
+ publishGeneric(null);
+ return;
+ }
+ if (startedAtRef.current === null) {
+ startedAtRef.current = Date.now() - Math.max(0, status.elapsedMs);
+ }
+ publishGeneric({
+ kind: ANALYTICS_WAREHOUSE_RESOURCE_KIND,
+ state: status.state,
+ severity,
+ startedAt: startedAtRef.current,
+ });
+ },
+ [publishGeneric],
+ );
+
+ return { publish, unpublish };
+}
diff --git a/packages/appkit-ui/src/react/hooks/use-chart-data.ts b/packages/appkit-ui/src/react/hooks/use-chart-data.ts
index a90481a2e..9d858d9b9 100644
--- a/packages/appkit-ui/src/react/hooks/use-chart-data.ts
+++ b/packages/appkit-ui/src/react/hooks/use-chart-data.ts
@@ -1,6 +1,7 @@
import type { Table } from "apache-arrow";
import { useMemo } from "react";
import type { ChartData, DataFormat } from "../charts/types";
+import type { WarehouseStatus } from "./types";
import { useAnalyticsQuery } from "./use-analytics-query";
/** Threshold for auto-selecting Arrow format (row count hint) */
@@ -38,6 +39,13 @@ export interface UseChartDataResult {
error: string | null;
/** Whether the data is empty */
isEmpty: boolean;
+ /**
+ * Latest warehouse readiness status from SSE. Retains the last value
+ * (including `RUNNING`) until the next `start()`; `null` only before
+ * the first event. Use with `loading` to distinguish warehouse warm-up
+ * from in-flight SQL fetch.
+ */
+ warehouseStatus: WarehouseStatus | null;
}
// ============================================================================
@@ -117,6 +125,7 @@ export function useChartData(options: UseChartDataOptions): UseChartDataResult {
data: rawData,
loading,
error,
+ warehouseStatus,
} = useAnalyticsQuery(queryKey, parameters, {
autoStart: true,
format: resolvedFormat,
@@ -179,5 +188,6 @@ export function useChartData(options: UseChartDataOptions): UseChartDataResult {
loading,
error,
isEmpty,
+ warehouseStatus,
};
}
diff --git a/packages/appkit-ui/src/react/hooks/use-resource-status.tsx b/packages/appkit-ui/src/react/hooks/use-resource-status.tsx
new file mode 100644
index 000000000..5f8514c95
--- /dev/null
+++ b/packages/appkit-ui/src/react/hooks/use-resource-status.tsx
@@ -0,0 +1,325 @@
+import {
+ createContext,
+ type ReactNode,
+ useCallback,
+ useContext,
+ useMemo,
+ useRef,
+ useSyncExternalStore,
+} from "react";
+
+const NOOP_SUBSCRIBE: (listener: () => void) => () => void = () => () => {};
+
+/**
+ * Cross-kind severity, ordered worst-first (`error > warning > pending`).
+ * Callers `unpublish` rather than publishing a status for ready resources.
+ */
+export type ResourceSeverity = "pending" | "warning" | "error";
+
+/**
+ * Readiness snapshot for a single resource (SQL warehouse, Lakebase
+ * connection, model-serving endpoint, …). Plugins publish these while a
+ * user-visible cold start / warm-up / unavailability is in flight.
+ */
+export interface ResourceStatus {
+ /** Resource family, conventionally lowercase-kebab (`"warehouse"`, `"lakebase"`). */
+ kind: string;
+ /** Resource-specific raw state, e.g. `"STARTING"`, `"DELETED"`. Opaque to the aggregator. */
+ state: string;
+ severity: ResourceSeverity;
+ /** Human-readable summary forwarded to the indicator UI. */
+ summary?: string;
+ /** Epoch ms when the publisher started waiting; drives `elapsedMs`. */
+ startedAt: number;
+}
+
+/** Aggregate view of every active publisher; returned by {@link useResourceStatus}. */
+export interface AggregatedResourceStatus {
+ /** Highest-severity status across all publishers, or `null` when nothing is pending. */
+ worst: ResourceStatus | null;
+ /** Worst status per `kind`. */
+ byKind: Record;
+ /** De-duped, sorted labels of every publisher with a non-null status. */
+ affectedLabels: string[];
+ /** Total registered publishers (including those whose status is `null`). */
+ activeCount: number;
+ /** Milliseconds since the worst entry's `startedAt`; `0` when nothing is pending. */
+ elapsedMs: number;
+ /** Monotonic counter bumped on every `publish`/`unpublish`. */
+ version: number;
+}
+
+/** Optional filter for {@link useResourceStatus}. */
+export interface ResourceStatusFilter {
+ /** Restrict the aggregate to a single resource kind. */
+ kind?: string;
+}
+
+const SEVERITY_RANK: Record = {
+ error: 0,
+ warning: 1,
+ pending: 2,
+};
+
+/**
+ * Internal registry record. `kindHint` keeps status-less slots associated
+ * with their kind so kind-scoped views can count "registered but not yet
+ * reporting" publishers (e.g. analytics charts before the first SSE event).
+ */
+interface RegistryEntry {
+ label: string;
+ status: ResourceStatus | null;
+ kindHint?: string;
+}
+
+const EMPTY_SNAPSHOT: AggregatedResourceStatus = {
+ worst: null,
+ byKind: {},
+ affectedLabels: [],
+ activeCount: 0,
+ elapsedMs: 0,
+ version: 0,
+};
+
+const GET_EMPTY_SNAPSHOT = (): AggregatedResourceStatus => EMPTY_SNAPSHOT;
+
+/** Flat per-publisher map exposed to React via `useSyncExternalStore`. */
+class ResourceStatusStore {
+ private entries = new Map();
+ private listeners = new Set<() => void>();
+ private snapshot: AggregatedResourceStatus = EMPTY_SNAPSHOT;
+ private version = 0;
+
+ publish(
+ id: string,
+ label: string,
+ status: ResourceStatus | null,
+ kindHint?: string,
+ ): void {
+ this.entries.set(id, { label, status, kindHint });
+ this.bump();
+ }
+
+ unpublish(id: string): void {
+ if (this.entries.delete(id)) this.bump();
+ }
+
+ subscribe(listener: () => void): () => void {
+ this.listeners.add(listener);
+ return () => {
+ this.listeners.delete(listener);
+ };
+ }
+
+ getSnapshot(): AggregatedResourceStatus {
+ return this.snapshot;
+ }
+
+ /** Exposed for the kind-filter path so it can pick up status-less `kindHint` slots. */
+ getEntries(): Map {
+ return this.entries;
+ }
+
+ private bump(): void {
+ this.version += 1;
+ this.snapshot = aggregate(this.entries, this.version);
+ for (const l of this.listeners) l();
+ }
+}
+
+function isWorse(a: ResourceStatus, b: ResourceStatus): boolean {
+ const aRank = SEVERITY_RANK[a.severity];
+ const bRank = SEVERITY_RANK[b.severity];
+ if (aRank !== bRank) return aRank < bRank;
+ // Same severity → longer-pending entry wins.
+ return a.startedAt < b.startedAt;
+}
+
+/** Pure derivation of the snapshot from `entries` at a given `version`. */
+function aggregate(
+ entries: Map,
+ version: number,
+): AggregatedResourceStatus {
+ if (entries.size === 0) return { ...EMPTY_SNAPSHOT, version };
+
+ let worst: ResourceStatus | null = null;
+ const byKind: Record = {};
+ const affectedLabels = new Set();
+
+ for (const entry of entries.values()) {
+ const status = entry.status;
+ if (!status) continue;
+ affectedLabels.add(entry.label);
+ const existing = byKind[status.kind];
+ if (!existing || isWorse(status, existing)) {
+ byKind[status.kind] = status;
+ }
+ if (!worst || isWorse(status, worst)) {
+ worst = status;
+ }
+ }
+
+ return {
+ worst,
+ byKind,
+ affectedLabels: [...affectedLabels].sort(),
+ activeCount: entries.size,
+ elapsedMs: worst ? Math.max(0, Date.now() - worst.startedAt) : 0,
+ version,
+ };
+}
+
+/** Kind-scoped aggregate; walks entries directly to include status-less `kindHint` slots. */
+function aggregateForKind(
+ entries: Map,
+ kind: string,
+ version: number,
+): AggregatedResourceStatus {
+ const affectedLabels = new Set();
+ let activeCount = 0;
+ let worst: ResourceStatus | null = null;
+
+ for (const entry of entries.values()) {
+ const entryKind = entry.status?.kind ?? entry.kindHint;
+ if (entryKind !== kind) continue;
+ activeCount++;
+ const status = entry.status;
+ if (!status) continue;
+ affectedLabels.add(entry.label);
+ if (!worst || isWorse(status, worst)) {
+ worst = status;
+ }
+ }
+
+ if (activeCount === 0) return { ...EMPTY_SNAPSHOT, version };
+
+ const byKind: Record = {};
+ if (worst) byKind[kind] = worst;
+
+ return {
+ worst,
+ byKind,
+ affectedLabels: [...affectedLabels].sort(),
+ activeCount,
+ elapsedMs: worst ? Math.max(0, Date.now() - worst.startedAt) : 0,
+ version,
+ };
+}
+
+interface ResourceStatusContextValue {
+ store: ResourceStatusStore;
+}
+
+const ResourceStatusContext = createContext(
+ null,
+);
+
+function useResourceStatusContext(): ResourceStatusContextValue | null {
+ return useContext(ResourceStatusContext);
+}
+
+export interface ResourceStatusProviderProps {
+ children: ReactNode;
+}
+
+/**
+ * Mount once near the root of your app to enable a global, cross-plugin
+ * readiness aggregate. Plugins publish {@link ResourceStatus} snapshots
+ * while a resource is warming up / unavailable; {@link useResourceStatus}
+ * exposes the worst across all of them.
+ *
+ * Without a provider, `useResourceStatus` and `useResourceStatusPublisher`
+ * fall back to no-ops, so plugins are safe to call them unconditionally.
+ *
+ * @example
+ * ```tsx
+ *
+ *
+ * ```
+ */
+export function ResourceStatusProvider({
+ children,
+}: ResourceStatusProviderProps) {
+ const storeRef = useRef(null);
+ if (storeRef.current === null) storeRef.current = new ResourceStatusStore();
+
+ const value = useMemo(
+ () => ({ store: storeRef.current as ResourceStatusStore }),
+ [],
+ );
+
+ return (
+
+ {children}
+
+ );
+}
+
+/**
+ * Returns the aggregated resource-readiness snapshot across every active
+ * publisher under the nearest {@link ResourceStatusProvider}. Falls back
+ * to the empty/idle aggregate when no provider is mounted.
+ *
+ * @param filter Optional `{ kind }` to scope to a single resource kind.
+ */
+export function useResourceStatus(
+ filter?: ResourceStatusFilter,
+): AggregatedResourceStatus {
+ const ctx = useResourceStatusContext();
+ const store = ctx?.store;
+
+ const subscribe = useMemo(
+ () =>
+ store
+ ? (listener: () => void) => store.subscribe(listener)
+ : NOOP_SUBSCRIBE,
+ [store],
+ );
+ const getSnapshot = useMemo(
+ () => (store ? () => store.getSnapshot() : GET_EMPTY_SNAPSHOT),
+ [store],
+ );
+
+ const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+ return useMemo(() => {
+ if (!filter?.kind) return snapshot;
+ if (!store) return { ...EMPTY_SNAPSHOT, version: snapshot.version };
+ return aggregateForKind(store.getEntries(), filter.kind, snapshot.version);
+ }, [snapshot, store, filter?.kind]);
+}
+
+/**
+ * Register a publisher with the nearest {@link ResourceStatusProvider}.
+ * Safe to call without a provider — `publish`/`unpublish` are no-ops.
+ *
+ * @param id Stable identifier (e.g. a `useId()` value).
+ * @param label Human-readable label surfaced via `affectedLabels`.
+ */
+export function useResourceStatusPublisher(
+ id: string,
+ label: string,
+ options?: { kindHint?: string },
+): {
+ publish: (status: ResourceStatus | null) => void;
+ unpublish: () => void;
+} {
+ const ctx = useResourceStatusContext();
+ const ctxRef = useRef(ctx);
+ ctxRef.current = ctx;
+ const kindHint = options?.kindHint;
+
+ const publish = useCallback(
+ (status: ResourceStatus | null) => {
+ ctxRef.current?.store.publish(id, label, status, kindHint);
+ },
+ [id, label, kindHint],
+ );
+ const unpublish = useCallback(() => {
+ ctxRef.current?.store.unpublish(id);
+ }, [id]);
+
+ return { publish, unpublish };
+}
diff --git a/packages/appkit-ui/src/react/index.ts b/packages/appkit-ui/src/react/index.ts
index 25aea4a44..233089b63 100644
--- a/packages/appkit-ui/src/react/index.ts
+++ b/packages/appkit-ui/src/react/index.ts
@@ -4,5 +4,6 @@ export * from "./genie";
export * from "./hooks";
export * from "./lib/utils";
export * from "./portal-container-context";
+export * from "./resource-status-indicator";
export * from "./table";
export * from "./ui";
diff --git a/packages/appkit-ui/src/react/resource-status-indicator.tsx b/packages/appkit-ui/src/react/resource-status-indicator.tsx
new file mode 100644
index 000000000..3e7d15656
--- /dev/null
+++ b/packages/appkit-ui/src/react/resource-status-indicator.tsx
@@ -0,0 +1,233 @@
+import type { LucideIcon } from "lucide-react";
+import { useEffect, useId, useRef, useState } from "react";
+import { type ToasterProps, toast } from "sonner";
+import {
+ type AggregatedResourceStatus,
+ type ResourceStatus,
+ useResourceStatus,
+} from "./hooks/use-resource-status";
+import { Toaster } from "./ui/sonner";
+
+/** ~1Hz tick driving the elapsed-time display between store events. */
+const ELAPSED_TICK_MS = 1000;
+
+/** Per-kind copy + icon overrides for {@link ResourceStatusIndicator}. */
+export interface ResourceKindRenderer {
+ title: (status: ResourceStatus) => string;
+ description: (
+ status: ResourceStatus,
+ aggregate: AggregatedResourceStatus,
+ ) => string;
+ /** Defaults to sonner's built-in loading/error icon. */
+ icon?: LucideIcon;
+}
+
+/** Options shared by {@link ResourceStatusIndicator} and {@link useResourceStatusToaster}. */
+export interface ResourceStatusToasterOptions {
+ /** Restrict to a single resource kind. Otherwise shows the worst across all kinds. */
+ kind?: string;
+ /** Per-kind copy + icon overrides. */
+ renderers?: Record;
+ /** Class name applied to the toast (not the Toaster wrapper). */
+ toastClassName?: string;
+ /** Full custom render override, rendered inside `toast.custom`. */
+ render?: (aggregate: AggregatedResourceStatus) => React.ReactNode;
+}
+
+const DEFAULT_KIND_RENDERERS: Record = {
+ warehouse: {
+ title: (s) =>
+ s.severity === "error"
+ ? "SQL warehouse unavailable"
+ : "SQL warehouse warming up",
+ description: (s, agg) => {
+ if (s.severity === "error") {
+ return (
+ s.summary ??
+ "The configured SQL warehouse is unavailable. Update DATABRICKS_WAREHOUSE_ID and reload."
+ );
+ }
+ const labels = agg.affectedLabels.length;
+ if (labels === 0) {
+ return `Waiting for the warehouse to reach RUNNING · ${formatElapsed(agg.elapsedMs)}`;
+ }
+ return `${labels} ${labels === 1 ? "query" : "queries"} waiting · ${formatElapsed(agg.elapsedMs)}`;
+ },
+ },
+};
+
+/**
+ * Drives a sticky sonner toast that mirrors the worst pending resource
+ * status. Does not render anything — supply your own `(null);
+
+ // Runs every render: cheap because sonner patches the same id in place.
+ useEffect(() => {
+ if (!worst) {
+ if (liveIdRef.current) {
+ toast.dismiss(liveIdRef.current);
+ liveIdRef.current = null;
+ }
+ return;
+ }
+
+ // Live elapsed; the snapshot only refreshes on store events.
+ const liveAggregate: AggregatedResourceStatus = {
+ ...aggregate,
+ elapsedMs: Math.max(0, Date.now() - worst.startedAt),
+ };
+
+ const nextId = `appkit-resource:${instanceId}:${worst.kind}:${worst.severity}`;
+ if (liveIdRef.current && liveIdRef.current !== nextId) {
+ toast.dismiss(liveIdRef.current);
+ }
+ liveIdRef.current = nextId;
+
+ if (render) {
+ const node = render(liveAggregate);
+ toast.custom(() => <>{node}, {
+ id: nextId,
+ duration: Number.POSITIVE_INFINITY,
+ className: toastClassName,
+ });
+ return;
+ }
+
+ const merged = { ...DEFAULT_KIND_RENDERERS, ...renderers };
+ const renderer = merged[worst.kind];
+ const title = renderer?.title(worst) ?? defaultTitle(worst);
+ const description =
+ renderer?.description(worst, liveAggregate) ?? defaultDescription(worst);
+ const Icon = renderer?.icon;
+ const opts = {
+ id: nextId,
+ description,
+ duration: Number.POSITIVE_INFINITY,
+ className: toastClassName,
+ ...(Icon ? { icon: {
+ /** Class name applied to the Toaster wrapper. */
+ className?: string;
+}
+
+/**
+ * Drop-in indicator that mounts a `
+ *
+ * ```
+ *
+ * @example Custom render
+ * ```tsx
+ * (
+ *
+ * {agg.worst?.kind} {agg.worst?.state.toLowerCase()}
+ *
+ * )}
+ * />
+ * ```
+ */
+export function ResourceStatusIndicator({
+ kind,
+ renderers,
+ toastClassName,
+ render,
+ position = "top-right",
+ ...toasterProps
+}: ResourceStatusIndicatorProps = {}) {
+ useResourceStatusToaster({ kind, renderers, toastClassName, render });
+ return
-
+
);