@kopai/ui 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kopai/ui",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "license": "Apache-2.0",
   "author": "Vladimir Adamic",
   "repository": {
@@ -19,7 +19,8 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
-    "./globals.css": "./src/styles/globals.css"
+    "./globals.css": "./src/styles/globals.css",
+    "./package.json": "./package.json"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -30,30 +31,30 @@
   ],
   "dependencies": {
     "@tanstack/react-query": "^5",
-    "@tanstack/react-virtual": "^3.11.2",
+    "@tanstack/react-virtual": "^3.13.19",
     "recharts": "^3.7.0",
-    "@kopai/core": "0.6.0",
-    "@kopai/sdk": "0.3.1"
+    "@kopai/core": "0.7.0",
+    "@kopai/sdk": "0.4.0"
   },
   "peerDependencies": {
     "react": "^19.2.4",
     "react-dom": "^19.2.4"
   },
   "devDependencies": {
-    "@storybook/addon-docs": "^10.2.8",
-    "@storybook/react": "^10.2.8",
-    "@storybook/react-vite": "^10.2.8",
+    "@storybook/addon-docs": "^10.2.13",
+    "@storybook/react": "^10.2.13",
+    "@storybook/react-vite": "^10.2.13",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.1.0",
     "@vitejs/plugin-react": "^5.1.4",
-    "@tailwindcss/postcss": "^4.1.18",
-    "jsdom": "^28.0.0",
+    "@tailwindcss/postcss": "^4.2.1",
+    "jsdom": "^28.1.0",
     "postcss": "^8.5.3",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "storybook": "^10.2.8",
-    "tailwindcss": "^4.1.18",
+    "storybook": "^10.2.13",
+    "tailwindcss": "^4.2.1",
     "tsdown": "^0.20.3",
     "vite": "^7.3.1",
     "@kopai/tsconfig": "0.2.0"

package/src/components/observability/DynamicDashboard/DynamicDashboard.test.tsx

@@ -0,0 +1,234 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createElement } from "react";
+import { render, waitFor } from "@testing-library/react";
+import { DynamicDashboard, type UITree } from "./index.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({}),
+  };
+}
+
+/**
+ * UITree containing every component from the observability catalog.
+ *
+ * Structure:
+ *   Stack (root)
+ *   ├── Heading
+ *   ├── Text
+ *   ├── Badge
+ *   ├── Divider
+ *   ├── Empty
+ *   ├── Card
+ *   │   └── Grid
+ *   │       ├── MetricTimeSeries  (dataSource: searchMetricsPage)
+ *   │       ├── MetricHistogram   (dataSource: searchMetricsPage)
+ *   │       ├── MetricStat        (dataSource: searchMetricsPage)
+ *   │       └── MetricTable       (dataSource: searchMetricsPage)
+ *   ├── LogTimeline               (dataSource: searchLogsPage)
+ *   ├── TraceDetail               (dataSource: searchTracesPage)
+ *   └── MetricDiscovery           (dataSource: discoverMetrics)
+ */
+const ALL_ELEMENTS_TREE = {
+  root: "root",
+  elements: {
+    root: {
+      key: "root",
+      type: "Stack" as const,
+      children: [
+        "heading",
+        "text",
+        "badge",
+        "divider",
+        "empty",
+        "card",
+        "log-timeline",
+        "trace-detail",
+        "metric-discovery",
+      ],
+      parentKey: "",
+      props: {
+        direction: "vertical" as const,
+        gap: "md" as const,
+        align: null,
+      },
+    },
+    heading: {
+      key: "heading",
+      type: "Heading" as const,
+      children: [],
+      parentKey: "root",
+      props: { text: "Dashboard", level: "h1" as const },
+    },
+    text: {
+      key: "text",
+      type: "Text" as const,
+      children: [],
+      parentKey: "root",
+      props: { content: "Overview", variant: null, color: null },
+    },
+    badge: {
+      key: "badge",
+      type: "Badge" as const,
+      children: [],
+      parentKey: "root",
+      props: { text: "Active", variant: "success" as const },
+    },
+    divider: {
+      key: "divider",
+      type: "Divider" as const,
+      children: [],
+      parentKey: "root",
+      props: { label: null },
+    },
+    empty: {
+      key: "empty",
+      type: "Empty" as const,
+      children: [],
+      parentKey: "root",
+      props: {
+        title: "No data",
+        description: null,
+        action: null,
+        actionLabel: null,
+      },
+    },
+    card: {
+      key: "card",
+      type: "Card" as const,
+      children: ["grid"],
+      parentKey: "root",
+      props: { title: "Metrics", description: null, padding: "md" as const },
+    },
+    grid: {
+      key: "grid",
+      type: "Grid" as const,
+      children: [
+        "metric-time-series",
+        "metric-histogram",
+        "metric-stat",
+        "metric-table",
+      ],
+      parentKey: "card",
+      props: { columns: 2, gap: "md" as const },
+    },
+    "metric-time-series": {
+      key: "metric-time-series",
+      type: "MetricTimeSeries" as const,
+      children: [],
+      parentKey: "grid",
+      props: { height: 300, showBrush: null },
+      dataSource: {
+        method: "searchMetricsPage" as const,
+        params: { metricType: "Gauge" as const },
+      },
+    },
+    "metric-histogram": {
+      key: "metric-histogram",
+      type: "MetricHistogram" as const,
+      children: [],
+      parentKey: "grid",
+      props: { height: 300 },
+      dataSource: {
+        method: "searchMetricsPage" as const,
+        params: { metricType: "Gauge" as const },
+      },
+    },
+    "metric-stat": {
+      key: "metric-stat",
+      type: "MetricStat" as const,
+      children: [],
+      parentKey: "grid",
+      props: { label: "Requests", showSparkline: true },
+      dataSource: {
+        method: "searchMetricsPage" as const,
+        params: { metricType: "Gauge" as const },
+      },
+    },
+    "metric-table": {
+      key: "metric-table",
+      type: "MetricTable" as const,
+      children: [],
+      parentKey: "grid",
+      props: { maxRows: 50 },
+      dataSource: {
+        method: "searchMetricsPage" as const,
+        params: { metricType: "Gauge" as const },
+      },
+    },
+    "log-timeline": {
+      key: "log-timeline",
+      type: "LogTimeline" as const,
+      children: [],
+      parentKey: "root",
+      props: { height: 400 },
+      dataSource: { method: "searchLogsPage" as const, params: {} },
+    },
+    "trace-detail": {
+      key: "trace-detail",
+      type: "TraceDetail" as const,
+      children: [],
+      parentKey: "root",
+      props: { height: 400 },
+      dataSource: { method: "searchTracesPage" as const, params: {} },
+    },
+    "metric-discovery": {
+      key: "metric-discovery",
+      type: "MetricDiscovery" as const,
+      children: [],
+      parentKey: "root",
+      props: {},
+      dataSource: { method: "discoverMetrics" as const, params: {} },
+    },
+  },
+} satisfies UITree;
+
+describe("DynamicDashboard", () => {
+  let mockClient: MockClient;
+
+  beforeEach(() => {
+    mockClient = createMockClient();
+    queryClient.clear();
+    vi.clearAllMocks();
+  });
+
+  it("renders a UITree containing all catalog components", async () => {
+    const { container } = render(
+      createElement(DynamicDashboard, {
+        kopaiClient: mockClient as unknown as KopaiClient,
+        uiTree: ALL_ELEMENTS_TREE,
+      })
+    );
+
+    // Wait for async data fetches to settle
+    await waitFor(() => {
+      expect(mockClient.searchMetricsPage).toHaveBeenCalled();
+      expect(mockClient.searchLogsPage).toHaveBeenCalled();
+      expect(mockClient.searchTracesPage).toHaveBeenCalled();
+      expect(mockClient.discoverMetrics).toHaveBeenCalled();
+    });
+
+    // Verify static content rendered
+    expect(container.textContent).toContain("Dashboard");
+    expect(container.textContent).toContain("Overview");
+    expect(container.textContent).toContain("Active");
+    expect(container.textContent).toContain("No data");
+  });
+});

package/src/components/observability/DynamicDashboard/index.tsx

@@ -0,0 +1,64 @@
+import {
+  createRendererFromCatalog,
+  type UITree,
+} from "../../../lib/renderer.js";
+import {
+  KopaiSDKProvider,
+  type KopaiClient,
+} from "../../../providers/kopai-provider.js";
+import { observabilityCatalog } from "../../../lib/observability-catalog.js";
+import {
+  Heading,
+  Text,
+  Card,
+  Stack,
+  Grid,
+  Badge,
+  Divider,
+  Empty,
+} from "../../dashboard/index.js";
+import {
+  OtelLogTimeline,
+  OtelMetricDiscovery,
+  OtelMetricHistogram,
+  OtelMetricStat,
+  OtelMetricTable,
+  OtelMetricTimeSeries,
+  OtelTraceDetail,
+} from "../renderers/index.js";
+
+const MetricsRenderer = createRendererFromCatalog(observabilityCatalog, {
+  Card,
+  Grid,
+  Stack,
+  Heading,
+  Text,
+  Badge,
+  Divider,
+  Empty,
+  LogTimeline: OtelLogTimeline,
+  TraceDetail: OtelTraceDetail,
+  MetricTimeSeries: OtelMetricTimeSeries,
+  MetricHistogram: OtelMetricHistogram,
+  MetricStat: OtelMetricStat,
+  MetricTable: OtelMetricTable,
+  MetricDiscovery: OtelMetricDiscovery,
+});
+
+export { type UITree };
+
+export interface DynamicDashboardProps {
+  kopaiClient: KopaiClient;
+  uiTree: UITree;
+}
+
+export function DynamicDashboard({
+  kopaiClient,
+  uiTree,
+}: DynamicDashboardProps) {
+  return (
+    <KopaiSDKProvider client={kopaiClient}>
+      <MetricsRenderer tree={uiTree} />
+    </KopaiSDKProvider>
+  );
+}

package/src/components/observability/MetricHistogram/MetricHistogram.stories.tsx

@@ -1,6 +1,9 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { MetricHistogram } from "./index.js";
-import { mockHistogramRows } from "../__fixtures__/metrics.js";
+import {
+  mockHistogramRows,
+  mockNoAttributeHistogramRows,
+} from "../__fixtures__/metrics.js";
 
 const meta: Meta<typeof MetricHistogram> = {
   title: "Observability/MetricHistogram",
@@ -18,3 +21,9 @@ export const Error: Story = {
   },
 };
 export const Empty: Story = { args: { rows: [] } };
+export const NoAttributes: Story = {
+  args: { rows: mockNoAttributeHistogramRows },
+};
+export const WithUnit: Story = {
+  args: { rows: mockHistogramRows, unit: "ms" },
+};

package/src/components/observability/MetricHistogram/index.tsx

@@ -15,6 +15,12 @@ import {
   Cell,
 } from "recharts";
 import type { denormalizedSignals } from "@kopai/core";
+import { formatSeriesLabel } from "../utils/attributes.js";
+import {
+  resolveUnitScale,
+  formatDisplayValue,
+  type ResolvedScale,
+} from "../utils/units.js";
 
 type OtelMetricsRow = denormalizedSignals.OtelMetricsRow;
 
@@ -32,6 +38,7 @@ export interface MetricHistogramProps {
   isLoading?: boolean;
   error?: Error;
   height?: number;
+  unit?: string;
   yAxisLabel?: string;
   showLegend?: boolean;
   formatBucketLabel?: (
@@ -69,17 +76,38 @@ const defaultFormatValue = (value: number): string => {
 function buildHistogramData(
   rows: OtelMetricsRow[],
   formatLabel = defaultFormatBucketLabel
-): { buckets: BucketData[]; seriesKeys: string[] } {
+): {
+  buckets: BucketData[];
+  seriesKeys: string[];
+  displayLabelMap: Map<string, string>;
+  unit: string;
+} {
   const buckets: BucketData[] = [];
   const seriesKeysSet = new Set<string>();
+  const displayLabelMap = new Map<string, string>();
+  let unit = "";
 
   for (const row of rows) {
     if (row.MetricType !== "Histogram") continue;
+    if (!unit && row.MetricUnit) unit = row.MetricUnit;
     const name = row.MetricName ?? "count";
     const key = row.Attributes ? JSON.stringify(row.Attributes) : "__default__";
     const seriesName = key === "__default__" ? name : key;
     seriesKeysSet.add(seriesName);
 
+    if (!displayLabelMap.has(seriesName)) {
+      if (key === "__default__") {
+        displayLabelMap.set(seriesName, name);
+      } else {
+        const labels: Record<string, string> = {};
+        if (row.Attributes) {
+          for (const [k, v] of Object.entries(row.Attributes))
+            labels[k] = String(v);
+        }
+        displayLabelMap.set(seriesName, formatSeriesLabel(labels) || name);
+      }
+    }
+
     const bounds = row.ExplicitBounds ?? [];
     const counts = row.BucketCounts ?? [];
 
@@ -102,7 +130,12 @@ function buildHistogramData(
   }
 
   buckets.sort((a, b) => a.lowerBound - b.lowerBound);
-  return { buckets, seriesKeys: Array.from(seriesKeysSet) };
+  return {
+    buckets,
+    seriesKeys: Array.from(seriesKeysSet),
+    displayLabelMap,
+    unit,
+  };
 }
 
 export function MetricHistogram({
@@ -110,6 +143,7 @@ export function MetricHistogram({
   isLoading = false,
   error,
   height = 400,
+  unit: unitProp,
   yAxisLabel,
   showLegend = true,
   formatBucketLabel,
@@ -117,17 +151,30 @@ export function MetricHistogram({
   labelStyle = "staggered",
 }: MetricHistogramProps) {
   const bucketLabelFormatter = formatBucketLabel ?? defaultFormatBucketLabel;
-  const unit = useMemo(() => {
-    for (const r of rows)
-      if (r.MetricType === "Histogram" && r.MetricUnit) return r.MetricUnit;
-    return "";
-  }, [rows]);
 
-  const { buckets, seriesKeys } = useMemo(() => {
-    if (rows.length === 0) return { buckets: [], seriesKeys: [] };
+  const { buckets, seriesKeys, displayLabelMap, unit } = useMemo(() => {
+    if (rows.length === 0)
+      return {
+        buckets: [],
+        seriesKeys: [],
+        displayLabelMap: new Map(),
+        unit: "",
+      };
     return buildHistogramData(rows, bucketLabelFormatter);
   }, [rows, bucketLabelFormatter]);
 
+  const effectiveUnit = unitProp ?? unit;
+
+  const boundsScale = useMemo(() => {
+    if (!effectiveUnit || buckets.length === 0) return null;
+    // Buckets are sorted by lowerBound — walk backwards to find last finite upperBound
+    for (let i = buckets.length - 1; i >= 0; i--) {
+      if (buckets[i]!.upperBound !== Infinity)
+        return resolveUnitScale(effectiveUnit, buckets[i]!.upperBound);
+    }
+    return null;
+  }, [effectiveUnit, buckets]);
+
   if (isLoading) return <HistogramLoadingSkeleton height={height} />;
 
   if (error) {
@@ -217,9 +264,20 @@ export function MetricHistogram({
             }
           />
           <Tooltip
-            content={<HistogramTooltip formatValue={formatValue} unit={unit} />}
+            content={(props) => (
+              <HistogramTooltip
+                {...props}
+                formatValue={formatValue}
+                boundsScale={boundsScale}
+                displayLabelMap={displayLabelMap}
+              />
+            )}
           />
-          {showLegend && seriesKeys.length > 1 && <Legend />}
+          {showLegend && seriesKeys.length > 1 && (
+            <Legend
+              formatter={(value: string) => displayLabelMap.get(value) ?? value}
+            />
+          )}
           {seriesKeys.map((key, i) => (
             <Bar
               key={key}
@@ -242,31 +300,39 @@ function HistogramTooltip({
   active,
   payload,
   formatValue,
-  unit,
+  boundsScale,
+  displayLabelMap,
 }: {
   active?: boolean;
-  payload?: Array<{
+  payload?: readonly {
     dataKey: string;
     value: number;
     color: string;
     payload: BucketData;
-  }>;
+  }[];
   formatValue: (val: number) => string;
-  unit?: string;
+  boundsScale: ResolvedScale | null;
+  displayLabelMap: Map<string, string>;
 }) {
   if (!active || !payload?.length) return null;
   const bucket = payload[0]?.payload;
   if (!bucket) return null;
+
+  const boundsLabel = boundsScale
+    ? `${formatDisplayValue(bucket.lowerBound, boundsScale)} – ${bucket.upperBound === Infinity ? "∞" : formatDisplayValue(bucket.upperBound, boundsScale)}`
+    : bucket.bucket;
+
   return (
     <div className="bg-background border border-gray-700 rounded-lg p-3 shadow-lg">
       <p className="text-gray-300 text-sm font-medium mb-2">
-        Bucket: {bucket.bucket}
-        {unit ? ` ${unit}` : ""}
+        Bucket: {boundsLabel}
       </p>
       {payload.map((entry, i) => (
         <p key={i} className="text-sm" style={{ color: entry.color }}>
-          <span className="font-medium">{entry.dataKey}:</span>{" "}
-          {formatValue(entry.value)} requests
+          <span className="font-medium">
+            {displayLabelMap.get(entry.dataKey) ?? entry.dataKey}:
+          </span>{" "}
+          {formatValue(entry.value)}
         </p>
       ))}
     </div>

package/src/components/observability/MetricStat/MetricStat.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { MetricStat } from "./index.js";
-import { mockStatRows } from "../__fixtures__/metrics.js";
+import { mockStatRows, mockNoAttributeRows } from "../__fixtures__/metrics.js";
 
 const meta: Meta<typeof MetricStat> = {
   title: "Observability/MetricStat",
@@ -28,3 +28,4 @@ export const Error: Story = {
   args: { rows: [], error: new globalThis.Error("Failed to fetch stat") },
 };
 export const Empty: Story = { args: { rows: [] } };
+export const NoAttributes: Story = { args: { rows: mockNoAttributeRows } };

package/src/components/observability/MetricTimeSeries/MetricTimeSeries.stories.tsx

@@ -1,6 +1,13 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { MetricTimeSeries } from "./index.js";
-import { mockGaugeRows, mockSumRows } from "../__fixtures__/metrics.js";
+import {
+  mockGaugeRows,
+  mockSumRows,
+  mockNoAttributeRows,
+  mockMultiAttributeRows,
+  mockStatRows,
+  mockLargeByteRows,
+} from "../__fixtures__/metrics.js";
 
 const meta: Meta<typeof MetricTimeSeries> = {
   title: "Observability/MetricTimeSeries",
@@ -26,3 +33,18 @@ export const Error: Story = {
   args: { rows: [], error: new globalThis.Error("Failed to fetch metrics") },
 };
 export const Empty: Story = { args: { rows: [] } };
+export const NoAttributes: Story = {
+  args: { rows: mockNoAttributeRows },
+};
+export const MultiAttributes: Story = {
+  args: { rows: mockMultiAttributeRows },
+};
+export const BytesUnit: Story = {
+  args: { rows: mockNoAttributeRows, unit: "By" },
+};
+export const PercentUnit: Story = {
+  args: { rows: mockStatRows, unit: "1" },
+};
+export const GigabyteScale: Story = {
+  args: { rows: mockLargeByteRows, unit: "By" },
+};