@cosmicdrift/kumiko-renderer-web 0.130.2 → 0.131.0

package/src/widgets/__tests__/widgets.test.tsx

@@ -0,0 +1,229 @@
+import { describe, expect, mock, test } from "bun:test";
+import { fireEvent, render, screen } from "../../__tests__/test-utils";
+import { StatusBarChart, smoothPath, TimeseriesChart } from "../charts";
+import { CollapsibleSection } from "../collapsible-section";
+import { DetailList } from "../detail-list";
+import { ModeSwitch } from "../mode-switch";
+import { ProgressBar } from "../progress-bar";
+import { SectionCard } from "../section-card";
+import { MiniStat, StatCard } from "../stat";
+import { EmptyState } from "../states";
+import { StatusBadge } from "../status-badge";
+
+describe("StatusBadge", () => {
+  test("rendert Label mit Tone-Klassen", () => {
+    render(
+      <StatusBadge tone="ok" testId="badge">
+        Operational
+      </StatusBadge>,
+    );
+    const badge = screen.getByTestId("badge");
+    expect(badge.textContent).toBe("Operational");
+    expect(badge.className).toContain("text-status-ok");
+  });
+
+  test("muted nutzt die neutralen Theme-Tokens", () => {
+    render(
+      <StatusBadge tone="muted" testId="badge">
+        Resolved
+      </StatusBadge>,
+    );
+    expect(screen.getByTestId("badge").className).toContain("text-muted-foreground");
+  });
+});
+
+describe("ProgressBar", () => {
+  test("clampt value auf 0..1 und setzt aria", () => {
+    render(<ProgressBar value={1.7} testId="bar" />);
+    expect(screen.getByTestId("bar").getAttribute("aria-valuenow")).toBe("100");
+  });
+
+  test("negative Werte werden 0", () => {
+    render(<ProgressBar value={-3} testId="bar" />);
+    expect(screen.getByTestId("bar").getAttribute("aria-valuenow")).toBe("0");
+  });
+});
+
+describe("ModeSwitch", () => {
+  test("markiert aktive Option und feuert onChange", () => {
+    const onChange = mock((_v: string) => {});
+    render(
+      <ModeSwitch
+        value="a"
+        options={[
+          { value: "a", label: "Modus A" },
+          { value: "b", label: "Modus B" },
+        ]}
+        onChange={onChange}
+      />,
+    );
+    const active = screen.getByRole("button", { name: "Modus A" });
+    expect(active.getAttribute("aria-pressed")).toBe("true");
+    fireEvent.click(screen.getByRole("button", { name: "Modus B" }));
+    expect(onChange).toHaveBeenCalledWith("b");
+  });
+});
+
+describe("CollapsibleSection", () => {
+  test("async geflipptes defaultOpen öffnet nachträglich", () => {
+    const { rerender, container } = render(
+      <CollapsibleSection title="Erweitert" defaultOpen={false}>
+        <span>Inhalt</span>
+      </CollapsibleSection>,
+    );
+    const details = container.querySelector("details");
+    expect(details?.open).toBe(false);
+    rerender(
+      <CollapsibleSection title="Erweitert" defaultOpen={true}>
+        <span>Inhalt</span>
+      </CollapsibleSection>,
+    );
+    expect(container.querySelector("details")?.open).toBe(true);
+  });
+});
+
+describe("DetailList", () => {
+  test("rendert Label/Wert-Paare als dl", () => {
+    render(<DetailList rows={[{ label: "Name", value: "Acme" }]} testId="dl" />);
+    expect(screen.getByText("Name").tagName).toBe("DT");
+    expect(screen.getByText("Acme").tagName).toBe("DD");
+  });
+});
+
+describe("SectionCard", () => {
+  test("rendert Titel, Action-Slot und Children über das Card-Primitive", () => {
+    render(
+      <SectionCard title="Verlauf" action={<button type="button">Range</button>}>
+        <span>Body</span>
+      </SectionCard>,
+    );
+    expect(screen.getByText("Verlauf")).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Range" })).toBeTruthy();
+    expect(screen.getByText("Body")).toBeTruthy();
+  });
+});
+
+describe("StatCard", () => {
+  test("rendert Label, Wert, Delta und Sub-Zeile", () => {
+    render(
+      <StatCard
+        label="Restschuld"
+        value="123.456 €"
+        sub="nach 10 Jahren"
+        delta={{ value: "2,1 %", direction: "down" }}
+      />,
+    );
+    expect(screen.getByText("Restschuld")).toBeTruthy();
+    expect(screen.getByText("123.456 €")).toBeTruthy();
+    expect(screen.getByText(/2,1 %/)).toBeTruthy();
+    expect(screen.getByText("nach 10 Jahren")).toBeTruthy();
+  });
+
+  test("accentColor färbt den Icon-Chip inline", () => {
+    const { container } = render(
+      <StatCard
+        icon={<svg aria-hidden="true" />}
+        label="Zins"
+        value="3,1 %"
+        accentColor="#123456"
+      />,
+    );
+    const chip = container.querySelector("span[style]");
+    // happy-dom parst color-mix()-backgroundColor nicht — color reicht als Beleg.
+    expect(chip?.getAttribute("style") ?? "").toContain("#123456");
+  });
+});
+
+describe("MiniStat", () => {
+  test("emphasize hebt die Kachel mit Ring hervor", () => {
+    render(<MiniStat label="Rate" value="890 €" emphasize testId="mini" />);
+    expect(screen.getByTestId("mini").className).toContain("ring-1");
+  });
+});
+
+describe("EmptyState", () => {
+  test("rendert Titel, Beschreibung und CTA", () => {
+    render(
+      <EmptyState
+        title="Noch keine Monitore"
+        description="Lege den ersten an."
+        action={<button type="button">Neu</button>}
+      />,
+    );
+    expect(screen.getByText("Noch keine Monitore")).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Neu" })).toBeTruthy();
+  });
+});
+
+describe("smoothPath", () => {
+  test("leer → leerer Pfad, ein Punkt → Move + Line auf sich selbst", () => {
+    expect(smoothPath([])).toBe("");
+    expect(smoothPath([{ x: 1, y: 2 }])).toBe("M 1.0 2.0 L 1.0 2.0");
+  });
+
+  test("glättet über Quadratic-Midpoints und endet am letzten Punkt", () => {
+    const d = smoothPath([
+      { x: 0, y: 0 },
+      { x: 10, y: 20 },
+      { x: 20, y: 0 },
+    ]);
+    expect(d.startsWith("M 0.0 0.0")).toBe(true);
+    expect(d).toContain("Q 10.0 20.0, 15.0 10.0");
+    expect(d.endsWith("L 20.0 0.0")).toBe(true);
+  });
+});
+
+describe("StatusBarChart", () => {
+  test("rendert einen Bar pro Entry mit aria-Label", () => {
+    const { container } = render(
+      <StatusBarChart
+        ariaLabel="Uptime 90 Tage"
+        entries={[
+          { key: "d1", level: 1, tone: "ok" },
+          { key: "d2", level: 0.5, tone: "bad" },
+        ]}
+        startLabel="90 Tage"
+        endLabel="heute"
+      />,
+    );
+    expect(screen.getByRole("img", { name: "Uptime 90 Tage" })).toBeTruthy();
+    // 2 Entries × (Gradient-Bar + Tick) + 1 Last-Highlight-Stripe = 5 rects
+    expect(container.querySelectorAll("rect").length).toBe(5);
+    expect(screen.getByText("heute")).toBeTruthy();
+  });
+});
+
+describe("TimeseriesChart", () => {
+  test("unter 2 Messwerten rendert emptyContent statt Chart", () => {
+    const { container } = render(
+      <TimeseriesChart
+        points={[{ atMs: 1000, value: 42 }]}
+        windowStartMs={0}
+        windowEndMs={2000}
+        ariaLabel="Antwortzeit"
+        emptyContent={<span>Noch keine Messdaten</span>}
+      />,
+    );
+    expect(screen.getByText("Noch keine Messdaten")).toBeTruthy();
+    expect(container.querySelector("svg")).toBeNull();
+  });
+
+  test("rendert Linie + Fläche + Achsen-Labels", () => {
+    const { container } = render(
+      <TimeseriesChart
+        points={[
+          { atMs: 0, value: 100 },
+          { atMs: 1000, value: 200 },
+          { atMs: 2000, value: null },
+        ]}
+        windowStartMs={0}
+        windowEndMs={2000}
+        ariaLabel="Antwortzeit"
+        axisLabels={{ start: "vor 24h", end: "jetzt" }}
+      />,
+    );
+    expect(screen.getByRole("img", { name: "Antwortzeit" })).toBeTruthy();
+    expect(container.querySelectorAll("path").length).toBe(2);
+    expect(screen.getByText("jetzt")).toBeTruthy();
+  });
+});

package/src/widgets/charts.tsx

@@ -0,0 +1,228 @@
+import { type ReactNode, useId } from "react";
+import { STATUS_TONE_TEXT, type StatusTone } from "./status-badge";
+
+// Inline-SVG-Charts — kein Chart-Dep. Farben ausschließlich über die
+// --color-status-* / --color-foreground Theme-Tokens; Achsen-Labels
+// kommen translated vom Caller (keine Locale-Annahmen im Widget).
+
+const TONE_VAR: Record<StatusTone, string> = {
+  ok: "var(--color-status-ok)",
+  warn: "var(--color-status-warn)",
+  bad: "var(--color-status-bad)",
+  critical: "var(--color-status-critical)",
+  muted: "var(--color-muted-foreground)",
+};
+
+export type StatusBarEntry = {
+  /** Stable key (z.B. ISO-Datum). */
+  readonly key: string;
+  /** Balkenhöhe 0..1 (z.B. operational=1, degraded=0.75, outage=0.25). */
+  readonly level: number;
+  readonly tone: StatusTone;
+  /** Tooltip-Text (<title>) — translated vom Caller. */
+  readonly label?: string;
+};
+
+/** Status-Balkenleiste (z.B. 90-Tage-Uptime): variable-height Bars mit
+ *  Gradient-Fade + Tick-Line am Bar-Top; der letzte Eintrag bekommt einen
+ *  „jetzt"-Accent-Stripe. */
+export function StatusBarChart({
+  entries,
+  ariaLabel,
+  startLabel,
+  endLabel,
+  highlightLast = true,
+  testId,
+}: {
+  readonly entries: readonly StatusBarEntry[];
+  readonly ariaLabel: string;
+  /** Achsen-Beschriftung links/rechts unter dem Chart — translated. */
+  readonly startLabel?: string;
+  readonly endLabel?: string;
+  readonly highlightLast?: boolean;
+  readonly testId?: string;
+}): ReactNode {
+  const gradPrefix = useId();
+  if (entries.length === 0) return <div className="h-9" aria-hidden />;
+
+  const chartHeight = 36;
+  const tickHeight = 1;
+  const barGap = 1;
+  const lastIdx = entries.length - 1;
+
+  return (
+    <div data-testid={testId}>
+      <svg
+        viewBox={`0 0 ${entries.length * (1 + barGap)} ${chartHeight}`}
+        preserveAspectRatio="none"
+        className="block h-9 w-full"
+        role="img"
+        aria-label={ariaLabel}
+      >
+        <title>{ariaLabel}</title>
+        {entries.map((entry, idx) => {
+          const x = idx * (1 + barGap);
+          const level = Math.max(0, Math.min(1, entry.level));
+          const barHeight = (chartHeight - tickHeight) * level;
+          const barY = chartHeight - barHeight;
+          const isLast = highlightLast && idx === lastIdx;
+          const color = TONE_VAR[entry.tone];
+          const gradId = `${gradPrefix}-${idx}`;
+          return (
+            <g key={entry.key}>
+              <defs>
+                <linearGradient id={gradId} x1="0" x2="0" y1="0" y2="1">
+                  <stop offset="0%" stopColor={color} stopOpacity={isLast ? 0.85 : 0.5} />
+                  <stop offset="100%" stopColor={color} stopOpacity={0.05} />
+                </linearGradient>
+              </defs>
+              {isLast && (
+                <rect
+                  x={x - 0.5}
+                  y={0}
+                  width={2}
+                  height={chartHeight}
+                  fill="var(--color-foreground)"
+                  fillOpacity={0.06}
+                />
+              )}
+              <rect x={x} y={barY} width={1} height={barHeight} fill={`url(#${gradId})`}>
+                {entry.label !== undefined && <title>{entry.label}</title>}
+              </rect>
+              <rect
+                x={x}
+                y={barY - tickHeight}
+                width={1}
+                height={tickHeight}
+                fill="var(--color-foreground)"
+                fillOpacity={isLast ? 1.0 : 0.7}
+              />
+            </g>
+          );
+        })}
+      </svg>
+      {(startLabel !== undefined || endLabel !== undefined) && (
+        <div className="mt-0.5 flex justify-between text-[11px] text-muted-foreground">
+          <span>{startLabel}</span>
+          <span>{endLabel}</span>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/** Quadratic-durch-Mittelpunkte-Trick: glättet die Zick-Zack-Linie ohne
+ *  Overshoot (~5 Zeilen statt Catmull-Rom/Bezier-Fit). */
+export function smoothPath(pts: ReadonlyArray<{ readonly x: number; readonly y: number }>): string {
+  const first = pts[0];
+  if (!first) return "";
+  let d = `M ${first.x.toFixed(1)} ${first.y.toFixed(1)}`;
+  for (let i = 1; i < pts.length - 1; i++) {
+    const cur = pts[i];
+    const next = pts[i + 1];
+    if (!cur || !next) break;
+    const midX = (cur.x + next.x) / 2;
+    const midY = (cur.y + next.y) / 2;
+    d += ` Q ${cur.x.toFixed(1)} ${cur.y.toFixed(1)}, ${midX.toFixed(1)} ${midY.toFixed(1)}`;
+  }
+  const last = pts[pts.length - 1];
+  if (!last) return d;
+  return `${d} L ${last.x.toFixed(1)} ${last.y.toFixed(1)}`;
+}
+
+export type TimeseriesPoint = {
+  readonly atMs: number;
+  /** null = Ausfall/kein Wert → fällt auf die Grundlinie (sichtbarer Einbruch). */
+  readonly value: number | null;
+};
+
+/** Zeitreihen-Linien-Chart (geglättete Linie + Flächen-Verlauf). x-Achse =
+ *  ZEIT im Fenster windowStartMs..windowEndMs, nicht Index — 5 Min Daten in
+ *  einem 30-Tage-Fenster ergeben ehrlich einen schmalen Streifen rechts. */
+export function TimeseriesChart({
+  points,
+  windowStartMs,
+  windowEndMs,
+  tone = "ok",
+  ariaLabel,
+  axisLabels,
+  emptyContent,
+  testId,
+}: {
+  readonly points: readonly TimeseriesPoint[];
+  readonly windowStartMs: number;
+  readonly windowEndMs: number;
+  readonly tone?: StatusTone;
+  readonly ariaLabel: string;
+  /** Achsen-Zeile unter dem Chart (translated/formatiert vom Caller). */
+  readonly axisLabels?: { readonly start: string; readonly mid?: string; readonly end: string };
+  /** Rendert statt des Charts wenn <2 Messwerte vorliegen. */
+  readonly emptyContent?: ReactNode;
+  readonly testId?: string;
+}): ReactNode {
+  const gradientId = useId();
+  const chartWidth = 300;
+  const chartHeight = 64;
+
+  const values = points.map((p) => p.value).filter((v): v is number => v !== null);
+  if (values.length < 2) {
+    return (
+      <div className="flex h-16 items-center justify-center text-[13px] text-muted-foreground">
+        {emptyContent}
+      </div>
+    );
+  }
+
+  const maxValue = Math.max(...values, 1);
+  const span = Math.max(1, windowEndMs - windowStartMs);
+  const xOf = (atMs: number) =>
+    Math.max(0, Math.min(1, (atMs - windowStartMs) / span)) * chartWidth;
+  const chartPoints = points.map((p) => ({
+    x: xOf(p.atMs),
+    y: p.value === null ? chartHeight : chartHeight - (p.value / maxValue) * chartHeight,
+  }));
+  const linePath = smoothPath(chartPoints);
+  const firstPoint = chartPoints[0];
+  const lastPoint = chartPoints[chartPoints.length - 1];
+  const areaPath =
+    firstPoint && lastPoint
+      ? `${linePath} L ${lastPoint.x.toFixed(1)} ${chartHeight} L ${firstPoint.x.toFixed(1)} ${chartHeight} Z`
+      : "";
+  const color = TONE_VAR[tone];
+
+  return (
+    <div data-testid={testId} className={STATUS_TONE_TEXT[tone]}>
+      <svg
+        viewBox={`0 0 ${chartWidth} ${chartHeight}`}
+        preserveAspectRatio="none"
+        className="block h-16 w-full"
+        role="img"
+        aria-label={ariaLabel}
+      >
+        <title>{ariaLabel}</title>
+        <defs>
+          <linearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
+            <stop offset="0%" stopColor={color} stopOpacity={0.3} />
+            <stop offset="100%" stopColor={color} stopOpacity={0.02} />
+          </linearGradient>
+        </defs>
+        <path d={areaPath} fill={`url(#${gradientId})`} stroke="none" />
+        <path
+          d={linePath}
+          fill="none"
+          stroke={color}
+          strokeWidth={1.5}
+          strokeLinejoin="round"
+          vectorEffect="non-scaling-stroke"
+        />
+      </svg>
+      {axisLabels !== undefined && (
+        <div className="mt-1 flex justify-between text-[11px] text-muted-foreground">
+          <span>{axisLabels.start}</span>
+          {axisLabels.mid !== undefined && <span>{axisLabels.mid}</span>}
+          <span>{axisLabels.end}</span>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/widgets/collapsible-section.tsx

@@ -0,0 +1,42 @@
+import { ChevronRight } from "lucide-react";
+import { type ReactNode, useEffect, useState } from "react";
+
+/** Aufklappbare Sektion (native <details>, aber React-kontrolliert: sonst
+ *  springt das open-Attribut bei jedem Parent-Re-Render auf den Initialwert
+ *  zurück). Eine Optik für alle „Erweitert"/„Mehr"-Abschnitte. */
+export function CollapsibleSection({
+  title,
+  defaultOpen = false,
+  children,
+  testId,
+}: {
+  readonly title: string;
+  readonly defaultOpen?: boolean;
+  readonly children: ReactNode;
+  readonly testId?: string;
+}): ReactNode {
+  const [open, setOpen] = useState(defaultOpen);
+  // useState(defaultOpen) liest nur den Mount-Wert — ein async hydrierter
+  // Draft flippt `defaultOpen` zu spät für den Lazy-Initializer. Open-only
+  // Effect: kämpft nie gegen ein manuelles Zuklappen des Users.
+  useEffect(() => {
+    if (defaultOpen) setOpen(true);
+  }, [defaultOpen]);
+  return (
+    <details
+      data-testid={testId}
+      className="group rounded-lg border bg-card"
+      open={open}
+      onToggle={(e) => setOpen(e.currentTarget.open)}
+    >
+      <summary className="flex cursor-pointer select-none items-center justify-between gap-2 rounded-lg px-4 py-2.5 text-sm font-medium hover:bg-muted/50 [&::-webkit-details-marker]:hidden">
+        <span>{title}</span>
+        <ChevronRight
+          aria-hidden="true"
+          className="size-4 text-muted-foreground transition-transform group-open:rotate-90"
+        />
+      </summary>
+      <div className="border-t px-4 py-3">{children}</div>
+    </details>
+  );
+}

package/src/widgets/detail-list.tsx

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+
+/** Read-only Schlüssel-Wert-Liste für Detail-Masken (Label links gedimmt,
+ *  Wert rechts). Wert ist ReactNode → Badges/Chips möglich. */
+export function DetailList({
+  rows,
+  testId,
+}: {
+  readonly rows: readonly { readonly label: string; readonly value: ReactNode }[];
+  readonly testId?: string;
+}): ReactNode {
+  return (
+    <dl data-testid={testId} className="flex flex-col divide-y">
+      {rows.map((row) => (
+        <div
+          key={row.label}
+          className="grid grid-cols-1 gap-0.5 py-2.5 sm:grid-cols-[200px_1fr] sm:gap-4"
+        >
+          <dt className="text-sm text-muted-foreground">{row.label}</dt>
+          <dd className="text-sm font-medium">{row.value}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}

package/src/widgets/index.ts

@@ -0,0 +1,21 @@
+// Mid-Level-Widgets — Kompositionen über den Primitives (Card, DataTable,
+// Banner) + Theme-Tokens. Für Custom-Screens: erst hier schauen, dann bauen.
+// Katalog: docs.kumiko.rocks → Guides → Widgets; visueller Überblick im
+// styleguide-Sample.
+
+export {
+  StatusBarChart,
+  type StatusBarEntry,
+  smoothPath,
+  TimeseriesChart,
+  type TimeseriesPoint,
+} from "./charts";
+export { CollapsibleSection } from "./collapsible-section";
+export { DetailList } from "./detail-list";
+export { ModeSwitch } from "./mode-switch";
+export { ProgressBar } from "./progress-bar";
+export { QueryTable, type QueryTableColumn, type QueryTableProps } from "./query-table";
+export { SectionCard } from "./section-card";
+export { MiniStat, Sparkline, StatCard, type StatDelta, type StatTone } from "./stat";
+export { EmptyState, ErrorState, LoadingState } from "./states";
+export { STATUS_TONE_TEXT, StatusBadge, type StatusTone } from "./status-badge";

package/src/widgets/mode-switch.tsx

@@ -0,0 +1,40 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+/** Segmented-Control für sich ausschließende Modi — die prominente
+ *  Alternative zum vergrabenen <select>. */
+export function ModeSwitch<T extends string>({
+  value,
+  options,
+  onChange,
+  testId,
+}: {
+  readonly value: T;
+  readonly options: readonly { readonly value: T; readonly label: string }[];
+  readonly onChange: (value: T) => void;
+  readonly testId?: string;
+}): ReactNode {
+  return (
+    <div data-testid={testId} className="flex flex-wrap gap-1">
+      {options.map((o) => {
+        const active = o.value === value;
+        return (
+          <button
+            key={o.value}
+            type="button"
+            aria-pressed={active}
+            onClick={() => onChange(o.value)}
+            className={cn(
+              "rounded-md border px-3 py-1.5 text-sm transition-colors",
+              active
+                ? "border-transparent bg-secondary font-semibold text-secondary-foreground"
+                : "text-muted-foreground hover:bg-muted",
+            )}
+          >
+            {o.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/widgets/progress-bar.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+/** Fortschrittsbalken, `value` 0..1 (wird geclampt). */
+export function ProgressBar({
+  value,
+  className,
+  testId,
+}: {
+  readonly value: number;
+  readonly className?: string;
+  readonly testId?: string;
+}): ReactNode {
+  const pct = Math.max(0, Math.min(1, value));
+  return (
+    <div
+      data-testid={testId}
+      role="progressbar"
+      aria-valuenow={Math.round(pct * 100)}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      className={cn("h-2 w-full overflow-hidden rounded-full bg-muted", className)}
+    >
+      <div className="h-full rounded-full bg-primary" style={{ width: `${pct * 100}%` }} />
+    </div>
+  );
+}