@kopai/ui 0.0.4 → 0.1.0

package/src/components/observability/index.ts

@@ -0,0 +1,66 @@
+// Components
+export { TabBar } from "./TabBar/index.js";
+export type { TabBarProps, Tab } from "./TabBar/index.js";
+
+export { ServiceList } from "./ServiceList/index.js";
+export type { ServiceListProps, ServiceEntry } from "./ServiceList/index.js";
+
+export { TraceSearch } from "./TraceSearch/index.js";
+export type {
+  TraceSearchProps,
+  TraceSearchFilters,
+  TraceSummary,
+} from "./TraceSearch/index.js";
+
+export { TraceDetail } from "./TraceDetail/index.js";
+export type { TraceDetailProps } from "./TraceDetail/index.js";
+
+export { TraceTimeline } from "./TraceTimeline/index.js";
+export type { TraceTimelineProps } from "./TraceTimeline/index.js";
+
+export { LogTimeline } from "./LogTimeline/index.js";
+export type { LogTimelineProps } from "./LogTimeline/index.js";
+
+export { LogFilter } from "./LogTimeline/LogFilter.js";
+export type { LogFilterProps } from "./LogTimeline/LogFilter.js";
+
+export { MetricTimeSeries } from "./MetricTimeSeries/index.js";
+export type {
+  MetricTimeSeriesProps,
+  ThresholdLine,
+} from "./MetricTimeSeries/index.js";
+
+export { MetricHistogram } from "./MetricHistogram/index.js";
+export type { MetricHistogramProps } from "./MetricHistogram/index.js";
+
+export { MetricStat } from "./MetricStat/index.js";
+export type { MetricStatProps, ThresholdConfig } from "./MetricStat/index.js";
+
+export { MetricTable } from "./MetricTable/index.js";
+export type { MetricTableProps } from "./MetricTable/index.js";
+
+export { RawDataTable } from "./RawDataTable/index.js";
+export type { RawDataTableProps } from "./RawDataTable/index.js";
+
+export { KeyboardShortcutsProvider } from "../KeyboardShortcuts/index.js";
+export { ShortcutsHelpDialog } from "../KeyboardShortcuts/index.js";
+export { useRegisterShortcuts } from "../KeyboardShortcuts/index.js";
+export type {
+  KeyboardShortcut,
+  ShortcutGroup,
+  ShortcutsRegistry,
+} from "../KeyboardShortcuts/index.js";
+
+// Types
+export type {
+  SpanNode,
+  SpanEvent,
+  SpanLink,
+  ParsedTrace,
+  LogEntry,
+  MetricDataPoint,
+  MetricSeries,
+  ParsedMetricGroup,
+  RawTableData,
+  RechartsDataPoint,
+} from "./types.js";

package/src/components/observability/renderers/OtelMetricDiscovery.tsx

@@ -0,0 +1,77 @@
+import { useMemo } from "react";
+import { observabilityCatalog } from "../../../lib/observability-catalog.js";
+import type { RendererComponentProps } from "../../../lib/renderer.js";
+import type { MetricsDiscoveryResult } from "@kopai/sdk";
+
+type Props = RendererComponentProps<
+  typeof observabilityCatalog.components.MetricDiscovery
+>;
+
+const TYPE_ORDER: Record<string, number> = {
+  Gauge: 0,
+  Sum: 1,
+  Histogram: 2,
+  ExponentialHistogram: 3,
+  Summary: 4,
+};
+
+export function OtelMetricDiscovery(props: Props) {
+  const data = props.hasData
+    ? (props.data as MetricsDiscoveryResult | null)
+    : null;
+  const loading = props.hasData ? props.loading : false;
+  const error = props.hasData ? props.error : null;
+
+  const sorted = useMemo(() => {
+    if (!data?.metrics) return [];
+    return [...data.metrics].sort(
+      (a, b) =>
+        a.name.localeCompare(b.name) ||
+        (TYPE_ORDER[a.type] ?? 99) - (TYPE_ORDER[b.type] ?? 99)
+    );
+  }, [data]);
+
+  if (loading && !sorted.length) {
+    return <p className="text-muted-foreground py-4">Loading metrics…</p>;
+  }
+  if (error) {
+    return <p className="text-red-400 py-4">Error: {error.message}</p>;
+  }
+  if (!sorted.length) {
+    return <p className="text-muted-foreground py-4">No metrics discovered.</p>;
+  }
+
+  return (
+    <div className="overflow-x-auto">
+      <table className="w-full text-sm text-left text-foreground border-collapse">
+        <thead className="text-xs uppercase text-muted-foreground border-b border-border">
+          <tr>
+            <th className="px-3 py-2">Name</th>
+            <th className="px-3 py-2">Type</th>
+            <th className="px-3 py-2">Unit</th>
+            <th className="px-3 py-2">Description</th>
+          </tr>
+        </thead>
+        <tbody>
+          {sorted.map((m) => (
+            <tr
+              key={`${m.name}-${m.type}`}
+              className="border-b border-border/50 hover:bg-muted/40"
+            >
+              <td className="px-3 py-2 font-mono whitespace-nowrap">
+                {m.name}
+              </td>
+              <td className="px-3 py-2 text-muted-foreground">{m.type}</td>
+              <td className="px-3 py-2 text-muted-foreground">
+                {m.unit || "–"}
+              </td>
+              <td className="px-3 py-2 text-muted-foreground">
+                {m.description || "–"}
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/src/components/observability/renderers/OtelMetricHistogram.tsx

@@ -0,0 +1,29 @@
+import { observabilityCatalog } from "../../../lib/observability-catalog.js";
+import type { RendererComponentProps } from "../../../lib/renderer.js";
+import { MetricHistogram } from "../index.js";
+import type { denormalizedSignals } from "@kopai/core";
+
+type OtelMetricsRow = denormalizedSignals.OtelMetricsRow;
+
+type Props = RendererComponentProps<
+  typeof observabilityCatalog.components.MetricHistogram
+>;
+
+export function OtelMetricHistogram(props: Props) {
+  if (!props.hasData) {
+    return (
+      <div style={{ padding: 24, color: "var(--muted)" }}>No data source</div>
+    );
+  }
+
+  const response = props.data as { data?: OtelMetricsRow[] } | null;
+
+  return (
+    <MetricHistogram
+      rows={response?.data ?? []}
+      isLoading={props.loading}
+      error={props.error ?? undefined}
+      height={props.element.props.height ?? 400}
+    />
+  );
+}

package/src/components/observability/renderers/OtelMetricStat.tsx

@@ -0,0 +1,44 @@
+import { observabilityCatalog } from "../../../lib/observability-catalog.js";
+import type { RendererComponentProps } from "../../../lib/renderer.js";
+import { MetricStat } from "../index.js";
+import type { denormalizedSignals } from "@kopai/core";
+
+type OtelMetricsRow = denormalizedSignals.OtelMetricsRow;
+
+type Props = RendererComponentProps<
+  typeof observabilityCatalog.components.MetricStat
+>;
+
+function formatOtelValue(value: number, unit: string): string {
+  // OTel unit "1" = dimensionless ratio → show as percentage
+  if (unit === "1") return `${(value * 100).toFixed(1)}%`;
+  // OTel curly-brace units like "{request}" → strip braces
+  const cleanUnit = unit.replace(/^\{|\}$/g, "");
+  let formatted: string;
+  if (Math.abs(value) >= 1e6) formatted = `${(value / 1e6).toFixed(1)}M`;
+  else if (Math.abs(value) >= 1e3) formatted = `${(value / 1e3).toFixed(1)}K`;
+  else if (Number.isInteger(value)) formatted = value.toString();
+  else formatted = value.toFixed(2);
+  return cleanUnit ? `${formatted} ${cleanUnit}` : formatted;
+}
+
+export function OtelMetricStat(props: Props) {
+  if (!props.hasData) {
+    return (
+      <div style={{ padding: 24, color: "var(--muted)" }}>No data source</div>
+    );
+  }
+
+  const response = props.data as { data?: OtelMetricsRow[] } | null;
+
+  return (
+    <MetricStat
+      rows={response?.data ?? []}
+      isLoading={props.loading}
+      error={props.error ?? undefined}
+      label={props.element.props.label ?? undefined}
+      showSparkline={props.element.props.showSparkline ?? false}
+      formatValue={formatOtelValue}
+    />
+  );
+}

package/src/components/observability/renderers/OtelMetricTable.tsx

@@ -0,0 +1,29 @@
+import { observabilityCatalog } from "../../../lib/observability-catalog.js";
+import type { RendererComponentProps } from "../../../lib/renderer.js";
+import { MetricTable } from "../index.js";
+import type { denormalizedSignals } from "@kopai/core";
+
+type OtelMetricsRow = denormalizedSignals.OtelMetricsRow;
+
+type Props = RendererComponentProps<
+  typeof observabilityCatalog.components.MetricTable
+>;
+
+export function OtelMetricTable(props: Props) {
+  if (!props.hasData) {
+    return (
+      <div style={{ padding: 24, color: "var(--muted)" }}>No data source</div>
+    );
+  }
+
+  const response = props.data as { data?: OtelMetricsRow[] } | null;
+
+  return (
+    <MetricTable
+      rows={response?.data ?? []}
+      isLoading={props.loading}
+      error={props.error ?? undefined}
+      maxRows={props.element.props.maxRows ?? 100}
+    />
+  );
+}

package/src/components/observability/renderers/OtelMetricTimeSeries.tsx

@@ -0,0 +1,30 @@
+import { observabilityCatalog } from "../../../lib/observability-catalog.js";
+import type { RendererComponentProps } from "../../../lib/renderer.js";
+import { MetricTimeSeries } from "../index.js";
+import type { denormalizedSignals } from "@kopai/core";
+
+type OtelMetricsRow = denormalizedSignals.OtelMetricsRow;
+
+type Props = RendererComponentProps<
+  typeof observabilityCatalog.components.MetricTimeSeries
+>;
+
+export function OtelMetricTimeSeries(props: Props) {
+  if (!props.hasData) {
+    return (
+      <div style={{ padding: 24, color: "var(--muted)" }}>No data source</div>
+    );
+  }
+
+  const response = props.data as { data?: OtelMetricsRow[] } | null;
+
+  return (
+    <MetricTimeSeries
+      rows={response?.data ?? []}
+      isLoading={props.loading}
+      error={props.error ?? undefined}
+      height={props.element.props.height ?? 400}
+      showBrush={props.element.props.showBrush ?? true}
+    />
+  );
+}

package/src/components/observability/renderers/index.ts

@@ -0,0 +1,5 @@
+export { OtelMetricDiscovery } from "./OtelMetricDiscovery.js";
+export { OtelMetricHistogram } from "./OtelMetricHistogram.js";
+export { OtelMetricStat } from "./OtelMetricStat.js";
+export { OtelMetricTable } from "./OtelMetricTable.js";
+export { OtelMetricTimeSeries } from "./OtelMetricTimeSeries.js";

package/src/components/observability/shared/LoadingSkeleton.tsx

@@ -0,0 +1,43 @@
+export function LoadingSkeleton() {
+  return (
+    <div className="flex flex-col h-full bg-background animate-pulse">
+      <div className="border-b border-border p-4">
+        <div className="h-4 bg-muted rounded w-1/4 mb-3"></div>
+        <div className="flex gap-4">
+          <div className="h-3 bg-muted rounded w-32"></div>
+          <div className="h-3 bg-muted rounded w-24"></div>
+          <div className="h-3 bg-muted rounded w-20"></div>
+        </div>
+      </div>
+      <div className="flex-1 p-4 space-y-2">
+        {Array.from({ length: 15 }).map((_, i) => (
+          <div key={i} className="flex items-start gap-3">
+            <div className="h-4 bg-muted rounded w-32"></div>
+            <div
+              className="h-4 rounded w-16"
+              style={{
+                backgroundColor:
+                  i % 4 === 0
+                    ? "#ef4444"
+                    : i % 4 === 1
+                      ? "#f97316"
+                      : i % 4 === 2
+                        ? "#3b82f6"
+                        : "#6b7280",
+                opacity: 0.3,
+              }}
+            ></div>
+            <div
+              className="h-4 bg-muted rounded"
+              style={{ width: `${80 + ((i * 7) % 40)}px` }}
+            ></div>
+            <div
+              className="h-4 bg-muted/80 rounded flex-1"
+              style={{ maxWidth: `${300 + ((i * 13) % 200)}px` }}
+            ></div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/components/observability/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Internal types for observability components.
+ * Components accept denormalized rows (OtelTracesRow, OtelLogsRow, OtelMetricsRow)
+ * from @kopai/core and transform to these internal types in useMemo.
+ */
+
+// ── Trace types ──
+
+export interface SpanNode {
+  spanId: string;
+  parentSpanId?: string;
+  traceId: string;
+  name: string;
+  startTimeUnixMs: number;
+  endTimeUnixMs: number;
+  durationMs: number;
+  kind: string;
+  status: string; // "UNSET" | "OK" | "ERROR"
+  statusMessage?: string;
+  serviceName: string;
+  attributes: Record<string, unknown>;
+  resourceAttributes: Record<string, unknown>;
+  events: SpanEvent[];
+  links: SpanLink[];
+  children: SpanNode[];
+}
+
+export interface SpanEvent {
+  timeUnixMs: number;
+  name: string;
+  attributes: Record<string, unknown>;
+}
+
+export interface SpanLink {
+  traceId: string;
+  spanId: string;
+  attributes: Record<string, unknown>;
+}
+
+export interface ParsedTrace {
+  traceId: string;
+  rootSpans: SpanNode[];
+  minTimeMs: number;
+  maxTimeMs: number;
+  totalSpanCount: number;
+}
+
+// ── Log types ──
+
+export interface LogEntry {
+  logId: string;
+  timeUnixMs: number;
+  body: string;
+  severityText: string;
+  severityNumber: number;
+  serviceName: string;
+  traceId?: string;
+  spanId?: string;
+  attributes: Record<string, unknown>;
+  resourceAttributes: Record<string, unknown>;
+  scopeName?: string;
+}
+
+// ── Metric types ──
+
+export type MetricType =
+  | "Gauge"
+  | "Sum"
+  | "Histogram"
+  | "ExponentialHistogram"
+  | "Summary";
+
+export interface MetricSeries {
+  key: string;
+  labels: Record<string, string>;
+  dataPoints: MetricDataPoint[];
+}
+
+export interface MetricDataPoint {
+  timestamp: number;
+  value: number;
+  // Histogram-specific
+  count?: number;
+  sum?: number;
+  bucketCounts?: number[];
+  explicitBounds?: number[];
+  min?: number;
+  max?: number;
+}
+
+export interface ParsedMetricGroup {
+  name: string;
+  description: string;
+  unit: string;
+  type: MetricType;
+  series: MetricSeries[];
+  serviceName: string;
+}
+
+// ── RawDataTable types ──
+
+export interface RawTableData {
+  columns: string[];
+  types: string[];
+  rows: unknown[][];
+}
+
+// ── Recharts types ──
+
+export interface RechartsDataPoint {
+  timestamp: number;
+  [seriesKey: string]: number;
+}

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

@@ -0,0 +1,17 @@
+export function formatAttributeValue(value: unknown): string {
+  if (value === null || value === undefined) return "null";
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean" || typeof value === "number")
+    return String(value);
+  if (Array.isArray(value) || typeof value === "object")
+    return JSON.stringify(value, null, 2);
+  return String(value);
+}
+
+export function isComplexValue(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (Array.isArray(value) || Object.keys(value).length > 0)
+  );
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Color palette utilities for trace visualization
+ * Generates consistent colors for service names using HSL color space
+ */
+
+function hashString(str: string): number {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash << 5) + hash + str.charCodeAt(i);
+  }
+  return Math.abs(hash);
+}
+
+export function getServiceColor(serviceName: string): string {
+  const hash = hashString(serviceName);
+  const hue = hash % 360;
+  const saturation = 70;
+  const lightness = 50;
+  return `hsl(${hue}, ${saturation}%, ${lightness}%)`;
+}
+
+export const ERROR_COLOR = "#ef4444";
+
+export function getSpanBarColor(serviceName: string, isError: boolean): string {
+  if (isError) {
+    return ERROR_COLOR;
+  }
+  return getServiceColor(serviceName);
+}

package/src/components/observability/utils/flatten-tree.ts

@@ -0,0 +1,53 @@
+/**
+ * Tree flattening utilities for virtual scrolling
+ */
+
+import type { SpanNode } from "../types.js";
+
+export interface FlattenedSpan {
+  span: SpanNode;
+  level: number;
+}
+
+export function flattenTree(
+  rootSpans: SpanNode[],
+  collapsedIds: Set<string>
+): FlattenedSpan[] {
+  const result: FlattenedSpan[] = [];
+
+  function traverse(span: SpanNode, level: number) {
+    result.push({ span, level });
+    if (!collapsedIds.has(span.spanId)) {
+      span.children.forEach((child) => traverse(child, level + 1));
+    }
+  }
+
+  rootSpans.forEach((root) => traverse(root, 0));
+  return result;
+}
+
+export function getAllDescendantIds(span: SpanNode): string[] {
+  const ids: string[] = [span.spanId];
+
+  function traverse(s: SpanNode) {
+    s.children.forEach((child) => {
+      ids.push(child.spanId);
+      traverse(child);
+    });
+  }
+
+  traverse(span);
+  return ids;
+}
+
+export function getAllSpanIds(rootSpans: SpanNode[]): string[] {
+  const ids: string[] = [];
+
+  function traverse(span: SpanNode) {
+    ids.push(span.spanId);
+    span.children.forEach((child) => traverse(child));
+  }
+
+  rootSpans.forEach((root) => traverse(root));
+  return ids;
+}

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

@@ -0,0 +1,121 @@
+/**
+ * Largest Triangle Three Buckets (LTTB) downsampling algorithm
+ */
+
+export interface LTTBPoint {
+  x: number;
+  y: number;
+}
+
+function triangleArea(p1: LTTBPoint, p2: LTTBPoint, p3: LTTBPoint): number {
+  return (
+    Math.abs((p1.x - p3.x) * (p2.y - p1.y) - (p1.x - p2.x) * (p3.y - p1.y)) / 2
+  );
+}
+
+export function downsampleLTTB(
+  data: LTTBPoint[],
+  targetPoints: number
+): LTTBPoint[] {
+  if (data.length <= 2 || targetPoints >= data.length) {
+    return data.slice();
+  }
+  if (targetPoints <= 2) {
+    return [data[0]!, data[data.length - 1]!];
+  }
+
+  const sampled: LTTBPoint[] = [];
+  const bucketSize = (data.length - 2) / (targetPoints - 2);
+
+  const firstPoint = data[0];
+  if (!firstPoint) return data;
+  sampled.push(firstPoint);
+
+  let prevSelectedIndex = 0;
+
+  for (let i = 0; i < targetPoints - 2; i++) {
+    const bucketStart = Math.floor((i + 0) * bucketSize) + 1;
+    const bucketEnd = Math.min(
+      Math.floor((i + 1) * bucketSize) + 1,
+      data.length - 1
+    );
+
+    const nextBucketStart = Math.floor((i + 1) * bucketSize) + 1;
+    const nextBucketEnd = Math.min(
+      Math.floor((i + 2) * bucketSize) + 1,
+      data.length - 1
+    );
+
+    let avgX = 0;
+    let avgY = 0;
+    let nextBucketCount = 0;
+
+    for (let j = nextBucketStart; j < nextBucketEnd; j++) {
+      const point = data[j];
+      if (point) {
+        avgX += point.x;
+        avgY += point.y;
+        nextBucketCount++;
+      }
+    }
+
+    if (nextBucketCount > 0) {
+      avgX /= nextBucketCount;
+      avgY /= nextBucketCount;
+    } else {
+      const lastPoint = data[data.length - 1];
+      if (lastPoint) {
+        avgX = lastPoint.x;
+        avgY = lastPoint.y;
+      }
+    }
+
+    const avgPoint: LTTBPoint = { x: avgX, y: avgY };
+
+    let maxArea = -1;
+    let maxAreaIndex = bucketStart;
+
+    const prevPoint = data[prevSelectedIndex];
+    if (!prevPoint) continue;
+
+    for (let j = bucketStart; j < bucketEnd; j++) {
+      const currentPoint = data[j];
+      if (!currentPoint) continue;
+      const area = triangleArea(prevPoint, currentPoint, avgPoint);
+      if (area > maxArea) {
+        maxArea = area;
+        maxAreaIndex = j;
+      }
+    }
+
+    const selectedPoint = data[maxAreaIndex];
+    if (selectedPoint) {
+      sampled.push(selectedPoint);
+    }
+    prevSelectedIndex = maxAreaIndex;
+  }
+
+  const lastPoint = data[data.length - 1];
+  if (lastPoint) {
+    sampled.push(lastPoint);
+  }
+
+  return sampled;
+}
+
+export function downsampleTimeSeries<
+  T extends { timestamp: number; value: number },
+>(data: T[], targetPoints: number): T[] {
+  if (targetPoints >= data.length) {
+    return data;
+  }
+
+  const points: LTTBPoint[] = data.map((d) => ({
+    x: d.timestamp,
+    y: d.value,
+  }));
+
+  const sampled = downsampleLTTB(points, targetPoints);
+  const sampledTimestamps = new Set(sampled.map((p) => p.x));
+  return data.filter((d) => sampledTimestamps.has(d.timestamp));
+}