@kopai/ui 0.4.0 → 0.6.0

package/src/components/observability/utils/units.ts

@@ -0,0 +1,132 @@
+export interface ResolvedScale {
+  divisor: number;
+  suffix: string;
+  label: string;
+  isPercent: boolean;
+}
+
+interface ScaleEntry {
+  threshold: number;
+  divisor: number;
+  suffix: string;
+}
+
+const BYTE_SCALES: ScaleEntry[] = [
+  { threshold: 1e12, divisor: 1e12, suffix: "TB" },
+  { threshold: 1e9, divisor: 1e9, suffix: "GB" },
+  { threshold: 1e6, divisor: 1e6, suffix: "MB" },
+  { threshold: 1e3, divisor: 1e3, suffix: "KB" },
+  { threshold: 0, divisor: 1, suffix: "B" },
+];
+
+const SECOND_SCALES: ScaleEntry[] = [
+  { threshold: 3600, divisor: 3600, suffix: "h" },
+  { threshold: 60, divisor: 60, suffix: "min" },
+  { threshold: 1, divisor: 1, suffix: "s" },
+  { threshold: 0, divisor: 0.001, suffix: "ms" },
+];
+
+const MS_SCALES: ScaleEntry[] = [
+  { threshold: 1000, divisor: 1000, suffix: "s" },
+  { threshold: 0, divisor: 1, suffix: "ms" },
+];
+
+const US_SCALES: ScaleEntry[] = [
+  { threshold: 1e6, divisor: 1e6, suffix: "s" },
+  { threshold: 1000, divisor: 1000, suffix: "ms" },
+  { threshold: 0, divisor: 1, suffix: "\u03BCs" },
+];
+
+const GENERIC_SCALES: ScaleEntry[] = [
+  { threshold: 1e9, divisor: 1e9, suffix: "B" },
+  { threshold: 1e6, divisor: 1e6, suffix: "M" },
+  { threshold: 1e3, divisor: 1e3, suffix: "K" },
+  { threshold: 0, divisor: 1, suffix: "" },
+];
+
+const BRACE_UNIT_PATTERN = /^\{(.+)\}$/;
+
+const UNIT_SCALE_MAP: Record<string, ScaleEntry[]> = {
+  By: BYTE_SCALES,
+  s: SECOND_SCALES,
+  ms: MS_SCALES,
+  us: US_SCALES,
+};
+
+function pickScale(scales: ScaleEntry[], maxValue: number): ScaleEntry {
+  const abs = Math.abs(maxValue);
+  for (const s of scales) {
+    if (abs >= s.threshold && s.threshold > 0) return s;
+  }
+  return scales[scales.length - 1]!;
+}
+
+export function resolveUnitScale(
+  unit: string | null | undefined,
+  maxValue: number
+): ResolvedScale {
+  if (!unit) {
+    const s = pickScale(GENERIC_SCALES, maxValue);
+    return {
+      divisor: s.divisor,
+      suffix: s.suffix,
+      label: "",
+      isPercent: false,
+    };
+  }
+
+  // Dimensionless ratio → percent
+  if (unit === "1") {
+    return { divisor: 0.01, suffix: "%", label: "Percent", isPercent: true };
+  }
+
+  // Known unit families
+  const scales = UNIT_SCALE_MAP[unit];
+  if (scales) {
+    const s = pickScale(scales, maxValue);
+    return {
+      divisor: s.divisor,
+      suffix: s.suffix,
+      label: s.suffix,
+      isPercent: false,
+    };
+  }
+
+  // Curly-brace units like {requests}
+  const braceMatch = BRACE_UNIT_PATTERN.exec(unit);
+  if (braceMatch) {
+    const cleaned = braceMatch[1]!;
+    const s = pickScale(GENERIC_SCALES, maxValue);
+    const suffix = s.suffix ? `${s.suffix} ${cleaned}` : cleaned;
+    return { divisor: s.divisor, suffix, label: cleaned, isPercent: false };
+  }
+
+  // Unknown unit — generic scaling + append unit
+  const s = pickScale(GENERIC_SCALES, maxValue);
+  const suffix = s.suffix ? `${s.suffix} ${unit}` : unit;
+  return { divisor: s.divisor, suffix, label: unit, isPercent: false };
+}
+
+export function formatTickValue(value: number, scale: ResolvedScale): string {
+  const scaled = value / scale.divisor;
+  if (scale.isPercent) return `${scaled.toFixed(1)}`;
+  if (Number.isInteger(scaled) && Math.abs(scaled) < 1e4)
+    return scaled.toString();
+  return scaled.toFixed(1);
+}
+
+export function formatDisplayValue(
+  value: number,
+  scale: ResolvedScale
+): string {
+  const tick = formatTickValue(value, scale);
+  if (!scale.suffix) return tick;
+  if (scale.isPercent) return `${tick}${scale.suffix}`;
+  return `${tick} ${scale.suffix}`;
+}
+
+/** Convenience: resolve + format in one call (for MetricStat) */
+export function formatOtelValue(value: number, unit: string): string {
+  const scale = resolveUnitScale(unit, Math.abs(value));
+  return formatDisplayValue(value, scale);
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export { default as ObservabilityPage } from "./pages/observability.js";
 export { createCatalog } from "./lib/component-catalog.js";
+export { observabilityCatalog } from "./lib/observability-catalog.js";
 export { generatePromptInstructions } from "./lib/generate-prompt-instructions.js";
 export {
   Renderer,

package/src/lib/__snapshots__/generate-prompt-instructions.test.ts.snap

@@ -1,7 +1,13 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`generatePromptInstructions > generates full prompt instructions 1`] = `
-"## Available Components
+"## UI Tree Version
+
+Use uiTreeVersion: "0.5.0" when creating dashboards.
+
+---
+
+## Available Components
 
 ### Card
 A card container

package/src/lib/generate-prompt-instructions.test.ts

@@ -21,7 +21,7 @@ describe("generatePromptInstructions", () => {
       },
     });
 
-    const prompt = generatePromptInstructions(catalog);
+    const prompt = generatePromptInstructions(catalog, "0.5.0");
     expect(prompt).toMatchSnapshot();
   });
 });

package/src/lib/generate-prompt-instructions.ts

@@ -74,16 +74,19 @@ function buildExampleElements(
   for (const name of otherNames) {
     const key = `${String(name).toLowerCase()}-1`;
     childKeys.push(key);
-    elements[key] = {
+    const element: Record<string, unknown> = {
       key,
       type: String(name),
       props: {},
       parentKey: containerKey,
-      dataSource: {
+    };
+    if (!components[name]?.hasChildren) {
+      element.dataSource = {
         method: "searchTracesPage",
         params: { limit: 10 },
-      },
-    };
+      };
+    }
+    elements[key] = element;
   }
 
   return { root: containerKey, elements };
@@ -140,7 +143,10 @@ function buildUnifiedSchema(treeSchema: z.ZodTypeAny): object {
  * const prompt = `Build a dashboard UI.\n\n${instructions}`;
  * ```
  */
-export function generatePromptInstructions(catalog: Catalog): string {
+export function generatePromptInstructions(
+  catalog: Catalog,
+  uiTreeVersion: string
+): string {
   const componentNames = Object.keys(catalog.components);
 
   const componentSections = componentNames
@@ -167,7 +173,13 @@ ${roleLine}`;
     catalog.components
   );
 
-  return `## Available Components
+  return `## UI Tree Version
+
+Use uiTreeVersion: "${uiTreeVersion}" when creating dashboards.
+
+---
+
+## Available Components
 
 ${componentSections}
 

package/src/lib/observability-catalog.ts

@@ -106,13 +106,19 @@ export const observabilityCatalog = createCatalog({
       props: z.object({
         height: z.number().nullable(),
         showBrush: z.boolean().nullable(),
+        yAxisLabel: z.string().nullable(),
+        unit: z.string().nullable(),
       }),
       hasChildren: false,
       description: "Time series line chart for Gauge/Sum metrics",
     },
 
     MetricHistogram: {
-      props: z.object({ height: z.number().nullable() }),
+      props: z.object({
+        height: z.number().nullable(),
+        yAxisLabel: z.string().nullable(),
+        unit: z.string().nullable(),
+      }),
       hasChildren: false,
       description: "Histogram bar chart for distribution metrics",
     },

package/src/lib/renderer.tsx

@@ -24,7 +24,7 @@ type RegistryFromCatalog<
 
 type Catalog = ReturnType<typeof createCatalog>;
 
-type UITree = z.infer<Catalog["uiTreeSchema"]>;
+export type UITree = z.infer<Catalog["uiTreeSchema"]>;
 
 type UIElement = UITree["elements"][string];
 

package/src/pages/observability.test.tsx

@@ -0,0 +1,124 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createElement } from "react";
+import { render, screen, waitFor } from "@testing-library/react";
+import ObservabilityPage from "./observability.js";
+import { queryClient } from "../providers/kopai-provider.js";
+import type { KopaiClient } from "@kopai/sdk";
+
+type MockClient = {
+  [K in keyof KopaiClient]: ReturnType<typeof vi.fn>;
+};
+
+function createMockClient(): MockClient {
+  return {
+    searchTracesPage: vi.fn().mockResolvedValue({ data: [] }),
+    searchLogsPage: vi.fn().mockResolvedValue({ data: [] }),
+    searchMetricsPage: vi.fn().mockResolvedValue({ data: [] }),
+    getTrace: vi.fn().mockResolvedValue({ data: [] }),
+    discoverMetrics: vi.fn().mockResolvedValue({ data: [] }),
+    searchTraces: vi.fn().mockResolvedValue({ data: [] }),
+    searchLogs: vi.fn().mockResolvedValue({ data: [] }),
+    searchMetrics: vi.fn().mockResolvedValue({ data: [] }),
+    createDashboard: vi.fn().mockResolvedValue({}),
+  };
+}
+
+const VALID_TREE = {
+  root: "root",
+  elements: {
+    root: {
+      key: "root",
+      type: "Stack",
+      children: ["heading"],
+      parentKey: "",
+      props: { direction: "vertical", gap: "md", align: null },
+    },
+    heading: {
+      key: "heading",
+      type: "Heading",
+      children: [],
+      parentKey: "root",
+      props: { text: "Test Dashboard", level: "h2" },
+    },
+  },
+};
+
+describe("useDashboardTree validation", () => {
+  let mockClient: MockClient;
+  let originalLocation: string;
+
+  beforeEach(() => {
+    mockClient = createMockClient();
+    queryClient.clear();
+    vi.clearAllMocks();
+    originalLocation = window.location.search;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    window.history.replaceState(
+      null,
+      "",
+      window.location.pathname + originalLocation
+    );
+  });
+
+  function setURL(params: string) {
+    window.history.replaceState(null, "", window.location.pathname + params);
+    window.dispatchEvent(new PopStateEvent("popstate"));
+  }
+
+  it("renders DynamicDashboard when API returns a valid uiTree", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+      new Response(JSON.stringify({ uiTree: VALID_TREE }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      })
+    );
+
+    setURL("?tab=metrics&dashboardId=abc");
+
+    render(
+      createElement(ObservabilityPage, {
+        client: mockClient as unknown as KopaiClient,
+      })
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText("Test Dashboard")).toBeTruthy();
+    });
+
+    expect(screen.queryByText(/invalid layout/i)).toBeNull();
+  });
+
+  it("shows error when API returns an invalid uiTree", async () => {
+    const invalidTree = {
+      root: "x",
+      elements: {
+        x: { type: "Bogus", key: "x", children: [], parentKey: "" },
+      },
+    };
+
+    vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+      new Response(JSON.stringify({ uiTree: invalidTree }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      })
+    );
+
+    setURL("?tab=metrics&dashboardId=def");
+
+    render(
+      createElement(ObservabilityPage, {
+        client: mockClient as unknown as KopaiClient,
+      })
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText(/invalid layout/i)).toBeTruthy();
+    });
+  });
+});

package/src/pages/observability.tsx

@@ -7,14 +7,13 @@ import {
   useRef,
 } from "react";
 import { KopaiSDKProvider, useKopaiSDK } from "../providers/kopai-provider.js";
+import { useQuery } from "@tanstack/react-query";
 import { KopaiClient } from "@kopai/sdk";
 import { useKopaiData } from "../hooks/use-kopai-data.js";
 import { useLiveLogs } from "../hooks/use-live-logs.js";
 import type { denormalizedSignals, dataFilterSchemas } from "@kopai/core";
 import type { DataSource } from "../lib/component-catalog.js";
 import { observabilityCatalog } from "../lib/observability-catalog.js";
-import { createRendererFromCatalog } from "../lib/renderer.js";
-
 // Observability components
 import {
   LogTimeline,
@@ -25,24 +24,15 @@ import {
   TraceDetail,
   KeyboardShortcutsProvider,
   useRegisterShortcuts,
+  DynamicDashboard,
 } from "../components/observability/index.js";
+import type { UITree } from "../components/observability/DynamicDashboard/index.js";
 import type {
   TraceSummary,
   TraceSearchFilters,
 } from "../components/observability/index.js";
 
 import { SERVICES_SHORTCUTS } from "../components/observability/ServiceList/shortcuts.js";
-import { OtelMetricDiscovery } from "../components/observability/renderers/index.js";
-import {
-  Heading,
-  Text,
-  Card,
-  Stack,
-  Grid,
-  Badge,
-  Divider,
-  Empty,
-} from "../components/dashboard/index.js";
 
 type OtelTracesRow = denormalizedSignals.OtelTracesRow;
 
@@ -67,6 +57,7 @@ interface URLState {
   service: string | null;
   trace: string | null;
   span: string | null;
+  dashboardId: string | null;
 }
 
 function readURLState(): URLState {
@@ -74,13 +65,14 @@ function readURLState(): URLState {
   const service = params.get("service");
   const trace = params.get("trace");
   const span = params.get("span");
+  const dashboardId = params.get("dashboardId");
   const rawTab = params.get("tab");
   const tab = service
     ? "services"
     : rawTab === "logs" || rawTab === "metrics"
       ? rawTab
       : "services";
-  return { tab, service, trace, span };
+  return { tab, service, trace, span, dashboardId };
 }
 
 function pushURLState(
@@ -89,6 +81,7 @@ function pushURLState(
     service?: string | null;
     trace?: string | null;
     span?: string | null;
+    dashboardId?: string | null;
   },
   { replace = false }: { replace?: boolean } = {}
 ) {
@@ -97,6 +90,12 @@ function pushURLState(
   if (state.service) params.set("service", state.service);
   if (state.trace) params.set("trace", state.trace);
   if (state.span) params.set("span", state.span);
+  // Preserve dashboardId from current URL if not explicitly provided
+  const dashboardId =
+    state.dashboardId !== undefined
+      ? state.dashboardId
+      : new URLSearchParams(window.location.search).get("dashboardId");
+  if (dashboardId) params.set("dashboardId", dashboardId);
   const qs = params.toString();
   const url = `${window.location.pathname}${qs ? `?${qs}` : ""}`;
   if (replace) {
@@ -118,6 +117,7 @@ let _cachedState: URLState = {
   service: null,
   trace: null,
   span: null,
+  dashboardId: null,
 };
 
 function getURLSnapshot(): URLState {
@@ -660,26 +660,10 @@ function ServicesTab({
 }
 
 // ---------------------------------------------------------------------------
-// Metrics tab — renderer + catalog
+// Metrics tab — DynamicDashboard
 // ---------------------------------------------------------------------------
 
-const MetricsRenderer = createRendererFromCatalog(observabilityCatalog, {
-  Card,
-  Grid,
-  Stack,
-  Heading,
-  Text,
-  Badge,
-  Divider,
-  Empty,
-  LogTimeline: () => null,
-  TraceDetail: () => null,
-  MetricTimeSeries: () => null,
-  MetricHistogram: () => null,
-  MetricStat: () => null,
-  MetricTable: () => null,
-  MetricDiscovery: OtelMetricDiscovery,
-});
+const DASHBOARDS_API_BASE = "/dashboards";
 
 const METRICS_TREE = {
   root: "root",
@@ -731,17 +715,68 @@ const METRICS_TREE = {
   },
 };
 
+function useDashboardTree(dashboardId: string | null) {
+  const { data, isFetching, error } = useQuery<UITree, Error>({
+    queryKey: ["dashboard-tree", dashboardId],
+    queryFn: async ({ signal }) => {
+      const res = await fetch(`${DASHBOARDS_API_BASE}/${dashboardId}`, {
+        signal,
+      });
+      if (!res.ok) throw new Error(`Failed to load dashboard: ${res.status}`);
+      const json = await res.json();
+      const parsed = observabilityCatalog.uiTreeSchema.safeParse(json.uiTree);
+      if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const path = issue?.path.length ? issue.path.join(".") + ": " : "";
+        throw new Error(
+          `Dashboard has an invalid layout: ${path}${issue?.message}`
+        );
+      }
+      return parsed.data;
+    },
+    enabled: !!dashboardId,
+  });
+
+  return {
+    loading: isFetching,
+    error: error?.message ?? null,
+    tree: data ?? null,
+  };
+}
+
 function MetricsTab() {
-  return <MetricsRenderer tree={METRICS_TREE} />;
+  const kopaiClient = useKopaiSDK();
+  const { dashboardId } = useURLState();
+  const { loading, error, tree } = useDashboardTree(dashboardId);
+
+  if (loading)
+    return (
+      <p className="text-muted-foreground text-sm">Loading dashboard...</p>
+    );
+  if (error)
+    return <p className="text-muted-foreground text-sm">Error: {error}</p>;
+
+  return (
+    <DynamicDashboard kopaiClient={kopaiClient} uiTree={tree ?? METRICS_TREE} />
+  );
 }
 
 // ---------------------------------------------------------------------------
 // Page
 // ---------------------------------------------------------------------------
 
-const client = new KopaiClient({ baseUrl: "/signals" });
+let _defaultClient: KopaiClient | undefined;
+function getDefaultClient() {
+  _defaultClient ??= new KopaiClient({ baseUrl: "" });
+  return _defaultClient;
+}
+
+interface ObservabilityPageProps {
+  client?: KopaiClient;
+}
 
-export default function ObservabilityPage() {
+export default function ObservabilityPage({ client }: ObservabilityPageProps) {
+  const activeClient = client ?? getDefaultClient();
   const {
     tab: activeTab,
     service: selectedService,
@@ -792,7 +827,7 @@ export default function ObservabilityPage() {
   }, [selectedService]);
 
   return (
-    <KopaiSDKProvider client={client}>
+    <KopaiSDKProvider client={activeClient}>
       <KeyboardShortcutsProvider
         onNavigateServices={() => pushURLState({ tab: "services" })}
         onNavigateLogs={() => pushURLState({ tab: "logs" })}

package/src/lib/dashboard-datasource.ts

@@ -1,76 +0,0 @@
-import { observabilityCatalog } from "./observability-catalog.js";
-import { z } from "zod";
-
-type UiTree = z.infer<typeof observabilityCatalog.uiTreeSchema>;
-
-export type DashboardId = string;
-export type UiTreeId = string;
-export type OwnerId = string;
-
-export interface DashboardMeta {
-  dashboardId: DashboardId;
-  uiTreeId: UiTreeId;
-  name: string;
-  ownerId: OwnerId;
-  pinned: boolean;
-  createdAt: string;
-  updatedAt: string;
-}
-
-export interface VersionMeta {
-  uiTreeId: UiTreeId;
-  createdAt: string;
-}
-
-export interface DashboardWriteDatasource {
-  createDashboard(
-    uiTree: UiTree,
-    name: string,
-    ownerId: OwnerId
-  ): Promise<DashboardMeta>;
-
-  // uiTrees are immutable, creates new one with ref to previous
-  updateDashboard(
-    dashboardId: DashboardId,
-    uiTree: UiTree,
-    pinned?: boolean
-  ): Promise<DashboardMeta>;
-
-  deleteDashboard(dashboardId: DashboardId): Promise<void>;
-
-  // Creates new uiTree copying content from specified version
-  restoreVersion(
-    dashboardId: DashboardId,
-    uiTreeId: UiTreeId
-  ): Promise<DashboardMeta>;
-}
-
-export interface DashboardReadDatasource {
-  searchDashboards(params: {
-    limit: number;
-    cursor?: string;
-    pinned?: boolean;
-    ownerId?: OwnerId;
-  }): Promise<{
-    dashboards: (DashboardMeta & { uiTree: UiTree })[];
-    nextCursor?: string;
-  }>;
-
-  getDashboard(
-    dashboardId: DashboardId
-  ): Promise<DashboardMeta & { uiTree: UiTree }>;
-
-  listVersions(params: {
-    dashboardId: DashboardId;
-    limit: number;
-    cursor?: string;
-  }): Promise<{
-    versions: VersionMeta[];
-    nextCursor?: string;
-  }>;
-
-  getDashboardAtVersion(uiTreeId: UiTreeId): Promise<{
-    uiTree: UiTree;
-    createdAt: string;
-  }>;
-}