@kopai/ui 0.0.5 → 0.2.0

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

@@ -0,0 +1,303 @@
+/**
+ * MetricHistogram - Accepts OtelMetricsRow[] and renders histogram bar charts.
+ */
+
+import { useMemo } from "react";
+import {
+  BarChart,
+  Bar,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+  Legend,
+  ResponsiveContainer,
+  Cell,
+} from "recharts";
+import type { denormalizedSignals } from "@kopai/core";
+
+type OtelMetricsRow = denormalizedSignals.OtelMetricsRow;
+
+const COLORS = [
+  "#8884d8",
+  "#82ca9d",
+  "#ffc658",
+  "#ff7300",
+  "#00C49F",
+  "#0088FE",
+];
+
+export interface MetricHistogramProps {
+  rows: OtelMetricsRow[];
+  isLoading?: boolean;
+  error?: Error;
+  height?: number;
+  yAxisLabel?: string;
+  showLegend?: boolean;
+  formatBucketLabel?: (
+    bound: number,
+    index: number,
+    bounds: number[]
+  ) => string;
+  formatValue?: (value: number) => string;
+  labelStyle?: "rotated" | "staggered" | "abbreviated";
+}
+
+interface BucketData {
+  bucket: string;
+  lowerBound: number;
+  upperBound: number;
+  [seriesKey: string]: number | string;
+}
+
+const defaultFormatBucketLabel = (
+  bound: number,
+  index: number,
+  bounds: number[]
+): string => {
+  if (index === 0) return `≤${bound}`;
+  if (index === bounds.length) return `>${bounds[bounds.length - 1]}`;
+  return `${bounds[index - 1]}-${bound}`;
+};
+
+const defaultFormatValue = (value: number): string => {
+  if (value >= 1e6) return `${(value / 1e6).toFixed(1)}M`;
+  if (value >= 1e3) return `${(value / 1e3).toFixed(1)}K`;
+  return value.toFixed(0);
+};
+
+function buildHistogramData(
+  rows: OtelMetricsRow[],
+  formatLabel = defaultFormatBucketLabel
+): { buckets: BucketData[]; seriesKeys: string[] } {
+  const buckets: BucketData[] = [];
+  const seriesKeysSet = new Set<string>();
+
+  for (const row of rows) {
+    if (row.MetricType !== "Histogram") continue;
+    const name = row.MetricName ?? "count";
+    const key = row.Attributes ? JSON.stringify(row.Attributes) : "__default__";
+    const seriesName = key === "__default__" ? name : key;
+    seriesKeysSet.add(seriesName);
+
+    const bounds = row.ExplicitBounds ?? [];
+    const counts = row.BucketCounts ?? [];
+
+    for (let i = 0; i < counts.length; i++) {
+      const count = counts[i] ?? 0;
+      const upperBound = i < bounds.length ? bounds[i]! : Infinity;
+      const bucketLabel = formatLabel(upperBound, i, bounds);
+
+      let bucket = buckets.find((b) => b.bucket === bucketLabel);
+      if (!bucket) {
+        bucket = {
+          bucket: bucketLabel,
+          lowerBound: i === 0 ? 0 : (bounds[i - 1] ?? 0),
+          upperBound: bounds[i] ?? Infinity,
+        };
+        buckets.push(bucket);
+      }
+      bucket[seriesName] = ((bucket[seriesName] as number) ?? 0) + count;
+    }
+  }
+
+  buckets.sort((a, b) => a.lowerBound - b.lowerBound);
+  return { buckets, seriesKeys: Array.from(seriesKeysSet) };
+}
+
+export function MetricHistogram({
+  rows,
+  isLoading = false,
+  error,
+  height = 400,
+  yAxisLabel,
+  showLegend = true,
+  formatBucketLabel,
+  formatValue = defaultFormatValue,
+  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: [] };
+    return buildHistogramData(rows, bucketLabelFormatter);
+  }, [rows, bucketLabelFormatter]);
+
+  if (isLoading) return <HistogramLoadingSkeleton height={height} />;
+
+  if (error) {
+    return (
+      <div
+        className="flex items-center justify-center bg-background rounded-lg border border-red-800"
+        style={{ height }}
+      >
+        <div className="text-center p-4">
+          <p className="text-red-400 font-medium">Error loading histogram</p>
+          <p className="text-gray-500 text-sm mt-1">{error.message}</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (rows.length === 0 || buckets.length === 0) {
+    return (
+      <div
+        className="flex items-center justify-center bg-background rounded-lg border border-gray-800"
+        style={{ height }}
+      >
+        <p className="text-gray-500">No histogram data available</p>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="bg-background rounded-lg p-4"
+      style={{ height }}
+      data-testid="metric-histogram"
+    >
+      <ResponsiveContainer width="100%" height="100%">
+        <BarChart
+          data={buckets}
+          margin={{ top: 5, right: 30, left: 20, bottom: 5 }}
+        >
+          <CartesianGrid strokeDasharray="3 3" stroke="#374151" />
+          <XAxis
+            dataKey="bucket"
+            stroke="#9CA3AF"
+            tick={
+              labelStyle === "staggered"
+                ? (props: {
+                    x?: number;
+                    y?: number;
+                    payload?: { value: string; index: number };
+                  }) => {
+                    if (!props.payload) return <g />;
+                    const yOffset = props.payload.index % 2 === 0 ? 0 : 12;
+                    return (
+                      <g transform={`translate(${props.x},${props.y})`}>
+                        <text
+                          x={0}
+                          y={yOffset}
+                          dy={12}
+                          textAnchor="middle"
+                          fill="#9CA3AF"
+                          fontSize={11}
+                        >
+                          {props.payload.value}
+                        </text>
+                      </g>
+                    );
+                  }
+                : { fill: "#9CA3AF", fontSize: 11 }
+            }
+            angle={labelStyle === "rotated" ? -45 : 0}
+            textAnchor={labelStyle === "rotated" ? "end" : "middle"}
+            height={labelStyle === "staggered" ? 50 : 60}
+            interval={0}
+          />
+          <YAxis
+            tickFormatter={formatValue}
+            stroke="#9CA3AF"
+            tick={{ fill: "#9CA3AF", fontSize: 12 }}
+            label={
+              yAxisLabel
+                ? {
+                    value: yAxisLabel,
+                    angle: -90,
+                    position: "insideLeft",
+                    fill: "#9CA3AF",
+                  }
+                : undefined
+            }
+          />
+          <Tooltip
+            content={<HistogramTooltip formatValue={formatValue} unit={unit} />}
+          />
+          {showLegend && seriesKeys.length > 1 && <Legend />}
+          {seriesKeys.map((key, i) => (
+            <Bar
+              key={key}
+              dataKey={key}
+              fill={COLORS[i % COLORS.length]}
+              radius={[4, 4, 0, 0]}
+            >
+              {buckets.map((_, bi) => (
+                <Cell key={`cell-${bi}`} fill={COLORS[i % COLORS.length]} />
+              ))}
+            </Bar>
+          ))}
+        </BarChart>
+      </ResponsiveContainer>
+    </div>
+  );
+}
+
+function HistogramTooltip({
+  active,
+  payload,
+  formatValue,
+  unit,
+}: {
+  active?: boolean;
+  payload?: Array<{
+    dataKey: string;
+    value: number;
+    color: string;
+    payload: BucketData;
+  }>;
+  formatValue: (val: number) => string;
+  unit?: string;
+}) {
+  if (!active || !payload?.length) return null;
+  const bucket = payload[0]?.payload;
+  if (!bucket) return null;
+  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}` : ""}
+      </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
+        </p>
+      ))}
+    </div>
+  );
+}
+
+function HistogramLoadingSkeleton({ height = 400 }: { height?: number }) {
+  return (
+    <div
+      className="bg-background rounded-lg p-4 animate-pulse"
+      style={{ height }}
+      data-testid="metric-histogram-loading"
+    >
+      <div className="h-full flex flex-col">
+        <div className="flex flex-1 gap-2">
+          <div className="flex flex-col justify-between w-12">
+            {[1, 2, 3, 4].map((i) => (
+              <div key={i} className="h-3 w-8 bg-gray-700 rounded" />
+            ))}
+          </div>
+          <div className="flex-1 flex items-end justify-around gap-2 pb-8">
+            {[30, 50, 80, 65, 45, 25, 15, 8].map((h, i) => (
+              <div
+                key={i}
+                className="w-8 bg-gray-700 rounded-t"
+                style={{ height: `${h}%` }}
+              />
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { MetricStat } from "./index.js";
+import { mockStatRows } from "../__fixtures__/metrics.js";
+
+const meta: Meta<typeof MetricStat> = {
+  title: "Observability/MetricStat",
+  component: MetricStat,
+};
+export default meta;
+type Story = StoryObj<typeof MetricStat>;
+
+export const Default: Story = { args: { rows: mockStatRows } };
+export const WithSparkline: Story = {
+  args: { rows: mockStatRows, showSparkline: true },
+};
+export const WithThresholds: Story = {
+  args: {
+    rows: mockStatRows,
+    thresholds: [
+      { value: 0.5, color: "green" },
+      { value: 0.8, color: "yellow" },
+      { value: 1, color: "red" },
+    ],
+  },
+};
+export const Loading: Story = { args: { rows: [], isLoading: true } };
+export const Error: Story = {
+  args: { rows: [], error: new globalThis.Error("Failed to fetch stat") },
+};
+export const Empty: Story = { args: { rows: [] } };

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

@@ -0,0 +1,281 @@
+/**
+ * MetricStat - Accepts OtelMetricsRow[] and renders stat cards with optional sparklines.
+ */
+
+import { useMemo } from "react";
+import { AreaChart, Area, ResponsiveContainer, YAxis } from "recharts";
+import type { denormalizedSignals } from "@kopai/core";
+import type { MetricDataPoint } from "../types.js";
+
+type OtelMetricsRow = denormalizedSignals.OtelMetricsRow;
+
+export interface ThresholdConfig {
+  value: number;
+  color: "green" | "yellow" | "red" | string;
+}
+
+export interface MetricStatProps {
+  rows: OtelMetricsRow[];
+  isLoading?: boolean;
+  error?: Error;
+  label?: string;
+  formatValue?: (value: number, unit: string) => string;
+  showTimestamp?: boolean;
+  trend?: "up" | "down" | "neutral";
+  trendValue?: number;
+  className?: string;
+  showSparkline?: boolean;
+  sparklinePoints?: number;
+  sparklineHeight?: number;
+  thresholds?: ThresholdConfig[];
+  colorBackground?: boolean;
+  colorValue?: boolean;
+}
+
+const THRESHOLD_COLORS: Record<
+  string,
+  { bg: string; border: string; text: string; stroke: string; fill: string }
+> = {
+  green: {
+    bg: "bg-green-900/20",
+    border: "border-green-700",
+    text: "text-green-400",
+    stroke: "#4ade80",
+    fill: "#22c55e",
+  },
+  yellow: {
+    bg: "bg-yellow-900/20",
+    border: "border-yellow-700",
+    text: "text-yellow-400",
+    stroke: "#facc15",
+    fill: "#eab308",
+  },
+  red: {
+    bg: "bg-red-900/20",
+    border: "border-red-700",
+    text: "text-red-400",
+    stroke: "#f87171",
+    fill: "#ef4444",
+  },
+  gray: {
+    bg: "bg-background",
+    border: "border-gray-800",
+    text: "text-gray-400",
+    stroke: "#9ca3af",
+    fill: "#6b7280",
+  },
+};
+
+function getColorConfig(color: string) {
+  return (
+    THRESHOLD_COLORS[color] ?? {
+      bg: "bg-background",
+      border: "border-gray-800",
+      text: "text-gray-400",
+      stroke: color,
+      fill: color,
+    }
+  );
+}
+
+function getThresholdColor(
+  value: number,
+  thresholds: ThresholdConfig[]
+): string {
+  const sorted = [...thresholds].sort((a, b) => a.value - b.value);
+  for (const t of sorted) if (value < t.value) return t.color;
+  return sorted[sorted.length - 1]?.color ?? "gray";
+}
+
+const defaultFormatValue = (value: number, unit: string): string => {
+  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 unit ? `${formatted} ${unit}` : formatted;
+};
+
+function buildStatData(rows: OtelMetricsRow[]): {
+  latestValue: number | null;
+  unit: string;
+  timestamp: number;
+  dataPoints: MetricDataPoint[];
+  metricName: string;
+} {
+  let latestTimestamp = 0;
+  let latestValue: number | null = null;
+  let unit = "";
+  let metricName = "Metric";
+  const dataPoints: MetricDataPoint[] = [];
+
+  for (const row of rows) {
+    if (
+      row.MetricType === "Histogram" ||
+      row.MetricType === "ExponentialHistogram" ||
+      row.MetricType === "Summary"
+    )
+      continue;
+    const timestamp = parseInt(row.TimeUnix, 10) / 1e6;
+    const value = "Value" in row ? row.Value : 0;
+    if (!unit && row.MetricUnit) unit = row.MetricUnit;
+    if (!metricName || metricName === "Metric")
+      metricName = row.MetricName ?? "Metric";
+    dataPoints.push({ timestamp, value });
+    if (timestamp > latestTimestamp) {
+      latestTimestamp = timestamp;
+      latestValue = value;
+    }
+  }
+
+  dataPoints.sort((a, b) => a.timestamp - b.timestamp);
+  return {
+    latestValue,
+    unit,
+    timestamp: latestTimestamp,
+    dataPoints,
+    metricName,
+  };
+}
+
+export function MetricStat({
+  rows,
+  isLoading = false,
+  error,
+  label,
+  formatValue = defaultFormatValue,
+  showTimestamp = false,
+  trend,
+  trendValue,
+  className = "",
+  showSparkline = false,
+  sparklinePoints = 20,
+  sparklineHeight = 40,
+  thresholds,
+  colorBackground,
+  colorValue = false,
+}: MetricStatProps) {
+  const { latestValue, unit, timestamp, dataPoints, metricName } = useMemo(
+    () => buildStatData(rows),
+    [rows]
+  );
+
+  const sparklineData = useMemo(() => {
+    if (!showSparkline || dataPoints.length === 0) return [];
+    return dataPoints
+      .slice(-sparklinePoints)
+      .map((dp) => ({ value: dp.value }));
+  }, [dataPoints, showSparkline, sparklinePoints]);
+
+  const thresholdColor = useMemo(() => {
+    if (!thresholds || latestValue === null) return "gray";
+    return getThresholdColor(latestValue, thresholds);
+  }, [thresholds, latestValue]);
+
+  const colorConfig = getColorConfig(thresholdColor);
+  const shouldColorBackground = colorBackground ?? thresholds !== undefined;
+  const displayLabel = label ?? metricName;
+  const bgClass = shouldColorBackground ? colorConfig.bg : "bg-background";
+  const borderClass = shouldColorBackground
+    ? `border ${colorConfig.border}`
+    : "";
+  const valueClass = colorValue ? colorConfig.text : "text-white";
+
+  if (isLoading) {
+    return (
+      <div
+        className={`bg-background rounded-lg p-4 animate-pulse ${className}`}
+        data-testid="metric-stat-loading"
+      >
+        <div className="h-4 w-24 bg-gray-700 rounded mb-2" />
+        <div className="h-10 w-32 bg-gray-700 rounded" />
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div
+        className={`bg-background rounded-lg p-4 border border-red-800 ${className}`}
+        data-testid="metric-stat-error"
+      >
+        <p className="text-red-400 text-sm">{error.message}</p>
+      </div>
+    );
+  }
+
+  if (latestValue === null) {
+    return (
+      <div
+        className={`bg-background rounded-lg p-4 border border-gray-800 ${className}`}
+        data-testid="metric-stat-empty"
+      >
+        <p className="text-gray-500 text-sm">{displayLabel}</p>
+        <p className="text-gray-600 text-2xl font-semibold">--</p>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={`${bgClass} ${borderClass} rounded-lg p-4 ${className}`}
+      data-testid="metric-stat"
+    >
+      <div className="flex items-center justify-between mb-1">
+        <p className="text-gray-400 text-sm font-medium">{displayLabel}</p>
+        {trend && <TrendIndicator direction={trend} value={trendValue} />}
+      </div>
+      <p className={`${valueClass} text-3xl font-bold`}>
+        {formatValue(latestValue, unit)}
+      </p>
+      {showTimestamp && (
+        <p className="text-gray-500 text-xs mt-1">
+          {new Date(timestamp).toLocaleTimeString()}
+        </p>
+      )}
+      {showSparkline && sparklineData.length > 0 && (
+        <div className="mt-2" style={{ height: sparklineHeight }}>
+          <ResponsiveContainer width="100%" height="100%">
+            <AreaChart
+              data={sparklineData}
+              margin={{ top: 0, right: 0, left: 0, bottom: 0 }}
+            >
+              <YAxis domain={["dataMin", "dataMax"]} hide />
+              <Area
+                type="monotone"
+                dataKey="value"
+                stroke={colorConfig.stroke}
+                fill={colorConfig.fill}
+                fillOpacity={0.3}
+                strokeWidth={1.5}
+                isAnimationActive={false}
+              />
+            </AreaChart>
+          </ResponsiveContainer>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function TrendIndicator({
+  direction,
+  value,
+}: {
+  direction: "up" | "down" | "neutral";
+  value?: number;
+}) {
+  const colorClass =
+    direction === "up"
+      ? "text-green-400"
+      : direction === "down"
+        ? "text-red-400"
+        : "text-gray-400";
+  const arrow = direction === "up" ? "↑" : direction === "down" ? "↓" : "→";
+  return (
+    <span className={`text-sm font-medium ${colorClass}`}>
+      {arrow}
+      {value !== undefined && ` ${Math.abs(value).toFixed(1)}%`}
+    </span>
+  );
+}

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

@@ -0,0 +1,20 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { MetricTable } from "./index.js";
+import { mockGaugeRows } from "../__fixtures__/metrics.js";
+
+const meta: Meta<typeof MetricTable> = {
+  title: "Observability/MetricTable",
+  component: MetricTable,
+};
+export default meta;
+type Story = StoryObj<typeof MetricTable>;
+
+export const Default: Story = { args: { rows: mockGaugeRows } };
+export const CustomColumns: Story = {
+  args: { rows: mockGaugeRows, columns: ["metric", "value"] },
+};
+export const Loading: Story = { args: { rows: [], isLoading: true } };
+export const Error: Story = {
+  args: { rows: [], error: new globalThis.Error("Failed to fetch metrics") },
+};
+export const Empty: Story = { args: { rows: [] } };