@databricks/appkit-ui 0.38.1 → 0.40.0

package/docs/development/type-generation.md

@@ -73,6 +73,19 @@ npx @databricks/appkit generate-types [rootDir] [outFile] [warehouseId]
 
   ```
 
+### Warehouse readiness and the `--wait` flag[​](#warehouse-readiness-and-the---wait-flag "Direct link to warehouse-readiness-and-the---wait-flag")
+
+By default, `generate-types` is **non-blocking**: it never waits on — or fails because of — your SQL warehouse. It writes the best types it can immediately (reusing cached types where the query is unchanged, otherwise `result: unknown`) and then spawns a detached background worker that refreshes the real types once the warehouse is ready. This keeps `npm install` (postinstall) and `npm run dev` (predev) fast and resilient to a cold or briefly-unreachable warehouse. The dev Vite plugin behaves the same way: types appear instantly and refresh in place once the warehouse is live.
+
+Pass `--wait` for CI and production builds, where accurate types must be present before the build proceeds:
+
+```bash
+npx @databricks/appkit generate-types --wait
+
+```
+
+In blocking mode the generator starts a stopped warehouse, waits (bounded) for it to reach `RUNNING`, and then describes your queries. It fails only when the configured warehouse no longer exists (deleted/deleting), so a transient outage or a cold warehouse degrades gracefully rather than breaking the build. The app template wires this up for you: `postinstall` and `predev` run the non-blocking default, while `prebuild` runs `--wait`.
+
 ## How it works[​](#how-it-works "Direct link to How it works")
 
 The type generator:

package/docs/plugins/analytics.md

@@ -97,6 +97,7 @@ const { data, loading, error } = useAnalyticsQuery(queryKey, parameters, options
   data: T | null;      // query result (typed array for JSON, TypedArrowTable for ARROW)
   loading: boolean;    // true while the query is executing
   error: string | null; // error message, or null on success
+  warehouseStatus: WarehouseStatus | null; // see "Warehouse readiness" below
 }
 
 ```
@@ -109,6 +110,161 @@ const { data, loading, error } = useAnalyticsQuery(queryKey, parameters, options
 | `maxParametersSize` | `number`            | `102400` | Max serialized parameters size in bytes |
 | `autoStart`         | `boolean`           | `true`   | Start query on mount                    |
 
+### Warehouse readiness[​](#warehouse-readiness "Direct link to Warehouse readiness")
+
+If the configured SQL warehouse is `STOPPED` or `STARTING` when a query is requested, the analytics plugin will:
+
+1. Auto-start the warehouse (when `STOPPED`).
+2. Poll the warehouse state and stream `warehouse_status` events over SSE until it reaches `RUNNING`.
+3. Execute the SQL statement.
+
+This means a cold start no longer freezes the UI on a stalled spinner. Render the new `warehouseStatus` field to give users feedback:
+
+```tsx
+import { useAnalyticsQuery } from "@databricks/appkit-ui/react";
+
+function SpendTable() {
+  const { data, loading, error, warehouseStatus } =
+    useAnalyticsQuery("spend_summary", params);
+
+  if (warehouseStatus && warehouseStatus.state !== "RUNNING") {
+    return <div>Warehouse is {warehouseStatus.state.toLowerCase()}…</div>;
+  }
+  if (loading) return <div>Loading…</div>;
+  if (error) return <div>{error}</div>;
+  return <table>{/* render data */}</table>;
+}
+
+```
+
+`warehouseStatus` is `null` until the first status event arrives. After the server has observed the warehouse `RUNNING` once, subsequent requests within \~30s skip the readiness check entirely and `warehouseStatus` stays `null`, so the steady-state hot path isn't taxed any extra round-trips.
+
+If the warehouse is `DELETED`/`DELETING` or fails to reach `RUNNING` within the configured timeout, the route emits an `error` event (surfaced via the `error` field).
+
+#### Global readiness indicator[​](#global-readiness-indicator "Direct link to Global readiness indicator")
+
+For dashboards with many charts a per-component spinner isn't enough — wiring the same "warehouse warming up" UI into every skeleton is repetitive. AppKit ships a small generic context (`ResourceStatusProvider`) + drop-in indicator (`ResourceStatusIndicator`) that any plugin can publish into; analytics warehouses are wired up automatically.
+
+The indicator surfaces the worst pending status as a [sonner](https://sonner.emilkowal.ski/) toast, so it inherits sonner's animations, theming, and stacking. The component mounts its own `<Toaster />` (top-right by default) and forwards its props (`position`, `theme`, `richColors`, …):
+
+```tsx
+import {
+  ResourceStatusIndicator,
+  ResourceStatusProvider,
+} from "@databricks/appkit-ui/react";
+
+export function AppShell({ children }) {
+  return (
+    <ResourceStatusProvider>
+      <ResourceStatusIndicator />
+      {children}
+    </ResourceStatusProvider>
+  );
+}
+
+```
+
+`useAnalyticsQuery` registers itself with the nearest provider, so no per-chart wiring is needed. The indicator renders only the `<Toaster />` mount point while every resource is healthy; it pops a single sticky toast — `toast.loading` for cold starts, `toast.error` for unrecoverable states — keyed by the worst kind, and dismisses it when they all settle. Because the same provider is shared across resource kinds (warehouse, lakebase, model serving, …), a single indicator covers every plugin.
+
+If you already render your own `<Toaster />` for unrelated app toasts, drop the indicator and call `useResourceStatusToaster()` instead so resource-status toasts share that single Toaster:
+
+```tsx
+import {
+  useResourceStatusToaster,
+  Toaster,
+} from "@databricks/appkit-ui/react";
+
+function App() {
+  useResourceStatusToaster();
+  return (
+    <>
+      <Toaster position="top-right" />
+      <Routes />
+    </>
+  );
+}
+
+```
+
+For a fully custom toast body, pass `render` (rendered through `toast.custom`):
+
+```tsx
+<ResourceStatusIndicator
+  render={(agg) => (
+    <div className="rounded-lg border bg-background p-3 shadow">
+      {agg.worst?.kind} {agg.worst?.state.toLowerCase()} ({agg.activeCount} waiting)
+    </div>
+  )}
+/>
+
+```
+
+To override copy for a specific kind without rewriting the whole UI, pass `renderers`:
+
+```tsx
+<ResourceStatusIndicator
+  renderers={{
+    warehouse: {
+      title: () => "Spinning up your data",
+      description: (_s, agg) =>
+        `${agg.affectedLabels.length} chart(s) waiting`,
+    },
+  }}
+/>
+
+```
+
+Or build your own UI from the aggregate with `useResourceStatus()`:
+
+```ts
+import { useResourceStatus } from "@databricks/appkit-ui/react";
+
+// Worst across all kinds
+const aggregate = useResourceStatus();
+// Just warehouses
+const warehouseOnly = useResourceStatus({ kind: "warehouse" });
+// { worst, byKind, affectedLabels, activeCount, elapsedMs }
+
+```
+
+The provider is optional. Apps that don't mount it still get the per-hook `warehouseStatus` field and the hook works exactly as before.
+
+##### Publishing your own resource status[​](#publishing-your-own-resource-status "Direct link to Publishing your own resource status")
+
+Plugins (or your own code) can hook into the same provider for non-analytics resources — e.g. a Lakebase Postgres connection warming up, a model-serving endpoint cold-starting:
+
+```ts
+import { useResourceStatusPublisher } from "@databricks/appkit-ui/react";
+import { useEffect, useId } from "react";
+
+function useLakebaseReadiness() {
+  const id = useId();
+  const { publish, unpublish } = useResourceStatusPublisher(
+    id,
+    "lakebase",
+    { kindHint: "lakebase" },
+  );
+
+  useEffect(() => {
+    publish({
+      kind: "lakebase",
+      state: "STARTING",
+      severity: "pending",
+      startedAt: Date.now(),
+    });
+    return () => unpublish();
+  }, [publish, unpublish]);
+}
+
+```
+
+**Server config (in `analytics({...})`):**
+
+| Option                      | Type      | Default          | Description                                                                                                                                                                                                                                               |
+| --------------------------- | --------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `warehouseStartupTimeoutMs` | `number`  | `300000` (5 min) | Maximum time to wait for the warehouse to reach `RUNNING` before failing the request                                                                                                                                                                      |
+| `autoStartWarehouse`        | `boolean` | `true`           | When `true`, a `STOPPED` warehouse is auto-started on the first request. Set to `false` for cost-controlled deployments where billable warehouse starts must not be triggered by user requests; in that case `STOPPED` surfaces as a `ConfigurationError` |
+
 **Example with loading/error/empty handling:**
 
 ```tsx

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit-ui",
   "type": "module",
-  "version": "0.38.1",
+  "version": "0.40.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",