@cosmicdrift/kumiko-renderer-web 1.0.0 → 2.0.0

package/src/widgets/ai-text-field.tsx

@@ -0,0 +1,370 @@
+// AiTextField / AiTextArea — Drop-in replacement for TextField/TextareaField
+// with AI-augmented actions (ai-text-primitive plan doc, Phase 3).
+//
+// Built on raw <input>/<textarea> (not the generic Input primitive) because
+// ghost-text needs a keydown handler (Tab/Esc) and an overlay that the
+// discriminated-union Input contract doesn't expose. Same pattern as
+// MoneyInput — a hand-built control wrapped in Field.
+//
+// Graceful degradation: `useAiTextAction`/`useCompletion` surface
+// "unavailable" when the server feature isn't mounted (`feature_disabled`)
+// — the toolbar hides and the field behaves like a plain text field, no
+// error shown to the end-user.
+//
+// Ghost-text simplification: the overlay only ever appends after the
+// current value (no mid-text ghost) — matches the server prompt design
+// (ai-text's `complete` mode only ever continues forward from the given
+// text). Two-layer overlay trick: an aria-hidden div behind the real
+// input renders `value` (invisible, same font/box so it reserves space)
+// followed by the suggestion in muted color; the real input sits on top
+// with a transparent background so the suggestion shows through past the
+// typed text. Both elements MUST share identical typography/box classes
+// or the suggestion won't align with the caret.
+
+import type { AiTextRewriteStyle } from "@cosmicdrift/kumiko-renderer";
+import {
+  useAiTextAction,
+  useCompletion,
+  usePrimitives,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import { Check, Languages, Wand2 } from "lucide-react";
+import { type KeyboardEvent, type ReactNode, useLayoutEffect, useRef, useState } from "react";
+import { cn } from "../lib/cn";
+import { ModeSwitch } from "./mode-switch";
+
+type AiTextAction = "correct" | "translate" | "rewrite";
+
+interface AiTextFieldBaseProps {
+  readonly label: string;
+  readonly id: string;
+  readonly name: string;
+  readonly value: string;
+  readonly onChange: (v: string) => void;
+  readonly required?: boolean;
+  readonly disabled?: boolean;
+  readonly placeholder?: string;
+  readonly testId?: string;
+  /** Ghost-text completion on/off. Default true. */
+  readonly completion?: boolean;
+  /** Debounce for ghost-text requests, ms. Default 500 — kept low in
+   *  tests, tuned for real typing in production. */
+  readonly completionDebounceMs?: number;
+  /** Toolbar actions to expose. Default all three. */
+  readonly actions?: readonly AiTextAction[];
+  /** Target languages the translate action offers. First is preselected.
+   *  Default `["en", "de", "fr", "es"]`. */
+  readonly translateLanguages?: readonly string[];
+}
+
+export interface AiTextFieldProps extends AiTextFieldBaseProps {}
+export interface AiTextAreaProps extends AiTextFieldBaseProps {
+  readonly rows?: number;
+}
+
+const DEFAULT_LANGUAGES: readonly string[] = ["en", "de", "fr", "es"];
+const DEFAULT_ACTIONS: readonly AiTextAction[] = ["correct", "translate", "rewrite"];
+const REWRITE_STYLES: readonly AiTextRewriteStyle[] = ["formal", "casual", "concise", "expand"];
+
+const sharedTextClass =
+  "w-full rounded-md border border-input px-3 py-2 text-sm shadow-sm leading-6 " +
+  "placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 " +
+  "focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50";
+
+// Overlay and real control must share identical wrap/overflow behavior or the
+// ghost suggestion drifts from the caret: <input> never wraps and scrolls
+// horizontally, <textarea> soft-wraps and scrolls vertically.
+const singleLineWrapClass = "whitespace-pre overflow-hidden";
+const multilineWrapClass = "whitespace-pre-wrap break-words overflow-hidden";
+
+function AiTextCore({
+  multiline,
+  label,
+  id,
+  name,
+  value,
+  onChange,
+  required,
+  disabled,
+  placeholder,
+  testId,
+  rows,
+  completion = true,
+  completionDebounceMs = 500,
+  actions = DEFAULT_ACTIONS,
+  translateLanguages = DEFAULT_LANGUAGES,
+}: AiTextFieldBaseProps & { readonly multiline: boolean; readonly rows?: number }): ReactNode {
+  const { Field, Button, Dialog, Text } = usePrimitives();
+  const t = useTranslation();
+
+  const {
+    suggestion,
+    state: completionState,
+    requestCompletion,
+    clear: clearCompletion,
+  } = useCompletion(completionDebounceMs);
+  const {
+    run: runAction,
+    state: actionState,
+    result: actionResult,
+    reset: resetAction,
+  } = useAiTextAction();
+
+  const [dialogMode, setDialogMode] = useState<AiTextAction | null>(null);
+  const [targetLanguage, setTargetLanguage] = useState(translateLanguages[0] ?? "en");
+  const [rewriteStyle, setRewriteStyle] = useState<AiTextRewriteStyle>("concise");
+  const overlayRef = useRef<HTMLDivElement>(null);
+  const controlRef = useRef<HTMLTextAreaElement | HTMLInputElement>(null);
+
+  const unavailable = completionState === "unavailable" || actionState === "unavailable";
+  const capExceeded = completionState === "cap-exceeded" || actionState === "cap-exceeded";
+  const showToolbar = !unavailable && actions.length > 0;
+  const showGhost = completion && !unavailable && suggestion !== null && suggestion.length > 0;
+
+  // ponytail: a manually `resize-y`-shrunk textarea can end up a few px
+  // shorter than the overlay div (which has no resize handle), so the
+  // synced scrollTop clamps slightly early — sub-line drift, invisible at
+  // normal line-height. Upgrade if it ever becomes visually noticeable.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: value/suggestion are trigger-only, effect reads refs not props
+  useLayoutEffect(() => {
+    if (overlayRef.current === null || controlRef.current === null) return;
+    overlayRef.current.scrollLeft = controlRef.current.scrollLeft;
+    overlayRef.current.scrollTop = controlRef.current.scrollTop;
+  }, [value, suggestion]);
+
+  function handleChange(next: string): void {
+    onChange(next);
+    if (completion && !unavailable) {
+      requestCompletion(next);
+    }
+  }
+
+  function handleKeyDown(e: KeyboardEvent<HTMLTextAreaElement | HTMLInputElement>): void {
+    if (suggestion === null) return;
+    if (e.key === "Tab" && e.currentTarget.selectionStart === value.length) {
+      e.preventDefault();
+      onChange(value + suggestion);
+      clearCompletion();
+    } else if (e.key === "Escape") {
+      e.preventDefault();
+      clearCompletion();
+    }
+  }
+
+  function openDialog(mode: AiTextAction): void {
+    resetAction();
+    setDialogMode(mode);
+    if (mode === "correct") {
+      void runAction({ mode: "correct", text: value });
+    }
+  }
+
+  function closeDialog(): void {
+    setDialogMode(null);
+    resetAction();
+  }
+
+  function runConfiguredAction(): void {
+    if (dialogMode === "translate") {
+      void runAction({ mode: "translate", text: value, targetLanguage });
+    } else if (dialogMode === "rewrite") {
+      void runAction({ mode: "rewrite", text: value, style: rewriteStyle });
+    }
+  }
+
+  function applyResult(): void {
+    if (actionResult?.type === "text") onChange(actionResult.text);
+  }
+
+  const needsConfig =
+    (dialogMode === "translate" || dialogMode === "rewrite") &&
+    actionState !== "loading" &&
+    actionState !== "success";
+
+  return (
+    <>
+      <Field id={id} label={label} required={required} testId={testId}>
+        <div className="relative w-full">
+          {showGhost && (
+            <div
+              ref={overlayRef}
+              aria-hidden="true"
+              className={cn(
+                sharedTextClass,
+                multiline ? multilineWrapClass : singleLineWrapClass,
+                "pointer-events-none absolute inset-0 select-none border-transparent shadow-none",
+              )}
+            >
+              <span className="invisible">{value}</span>
+              <span className="text-muted-foreground">{suggestion}</span>
+            </div>
+          )}
+          {multiline ? (
+            <textarea
+              ref={(el) => {
+                controlRef.current = el;
+              }}
+              id={id}
+              name={name}
+              value={value}
+              required={required}
+              disabled={disabled === true || unavailable}
+              placeholder={placeholder}
+              rows={rows ?? 4}
+              onChange={(e) => handleChange(e.target.value)}
+              onKeyDown={handleKeyDown}
+              onBlur={clearCompletion}
+              onScroll={(e) => {
+                if (overlayRef.current) overlayRef.current.scrollTop = e.currentTarget.scrollTop;
+              }}
+              className={cn(
+                sharedTextClass,
+                multilineWrapClass,
+                "relative resize-y bg-transparent",
+              )}
+              data-testid={testId !== undefined ? `${testId}-input` : undefined}
+            />
+          ) : (
+            <input
+              ref={(el) => {
+                controlRef.current = el;
+              }}
+              id={id}
+              name={name}
+              type="text"
+              value={value}
+              required={required}
+              disabled={disabled === true || unavailable}
+              placeholder={placeholder}
+              onChange={(e) => handleChange(e.target.value)}
+              onKeyDown={handleKeyDown}
+              onBlur={clearCompletion}
+              onScroll={(e) => {
+                if (overlayRef.current) overlayRef.current.scrollLeft = e.currentTarget.scrollLeft;
+              }}
+              className={cn(sharedTextClass, singleLineWrapClass, "relative bg-transparent")}
+              data-testid={testId !== undefined ? `${testId}-input` : undefined}
+            />
+          )}
+        </div>
+
+        {showGhost && <Text variant="muted">{t("kumiko.aiText.acceptHint")}</Text>}
+        {capExceeded && <Text variant="muted">{t("kumiko.aiText.capExceeded")}</Text>}
+
+        {showToolbar && (
+          <div className="mt-1 flex gap-1">
+            {actions.includes("correct") && (
+              <Button
+                variant="secondary"
+                size="sm"
+                disabled={value.length === 0}
+                ariaLabel={t("kumiko.aiText.correct")}
+                onClick={() => openDialog("correct")}
+              >
+                <Check className="size-3.5" aria-hidden="true" />
+              </Button>
+            )}
+            {actions.includes("translate") && (
+              <Button
+                variant="secondary"
+                size="sm"
+                disabled={value.length === 0}
+                ariaLabel={t("kumiko.aiText.translate")}
+                onClick={() => openDialog("translate")}
+              >
+                <Languages className="size-3.5" aria-hidden="true" />
+              </Button>
+            )}
+            {actions.includes("rewrite") && (
+              <Button
+                variant="secondary"
+                size="sm"
+                disabled={value.length === 0}
+                ariaLabel={t("kumiko.aiText.rewrite")}
+                onClick={() => openDialog("rewrite")}
+              >
+                <Wand2 className="size-3.5" aria-hidden="true" />
+              </Button>
+            )}
+          </div>
+        )}
+      </Field>
+
+      {/* ponytail: Dialog's built-in Confirm button is always live, even
+          while needsConfig is still showing the language/style picker —
+          applyResult() no-ops until actionResult exists, so an early click
+          just closes the dialog with nothing applied. Gating it needs a
+          confirmDisabled prop on the shared Dialog primitive (other
+          callers too); not worth widening that contract for one caller.
+          Upgrade if this trips users up in practice. */}
+      <Dialog
+        open={dialogMode !== null}
+        onOpenChange={(open) => {
+          if (!open) closeDialog();
+        }}
+        title={dialogMode !== null ? t(`kumiko.aiText.${dialogMode}`) : ""}
+        onConfirm={applyResult}
+        testId={testId !== undefined ? `${testId}-dialog` : undefined}
+      >
+        {dialogMode === "translate" && needsConfig && (
+          <div className="mb-3 flex flex-col gap-2">
+            <ModeSwitch
+              value={targetLanguage}
+              options={translateLanguages.map((l) => ({ value: l, label: l.toUpperCase() }))}
+              onChange={setTargetLanguage}
+            />
+            <Button variant="primary" size="sm" onClick={runConfiguredAction}>
+              {t(`kumiko.aiText.${dialogMode}`)}
+            </Button>
+          </div>
+        )}
+        {dialogMode === "rewrite" && needsConfig && (
+          <div className="mb-3 flex flex-col gap-2">
+            <ModeSwitch
+              value={rewriteStyle}
+              options={REWRITE_STYLES.map((s) => ({
+                value: s,
+                label: t(`kumiko.aiText.style.${s}`),
+              }))}
+              onChange={setRewriteStyle}
+            />
+            <Button variant="primary" size="sm" onClick={runConfiguredAction}>
+              {t(`kumiko.aiText.${dialogMode}`)}
+            </Button>
+          </div>
+        )}
+        {actionState === "loading" && (
+          <Text variant="muted">{t("kumiko.aiText.diff.generating")}</Text>
+        )}
+        {actionState === "success" && actionResult?.type === "text" && (
+          <div className="flex flex-col gap-3">
+            <div>
+              <Text variant="small">{t("kumiko.aiText.diff.before")}</Text>
+              <p className="whitespace-pre-wrap rounded-md border border-input bg-muted/40 p-2 text-sm">
+                {value}
+              </p>
+            </div>
+            <div>
+              <Text variant="small">{t("kumiko.aiText.diff.after")}</Text>
+              <p className="whitespace-pre-wrap rounded-md border border-input p-2 text-sm">
+                {actionResult.text}
+              </p>
+            </div>
+          </div>
+        )}
+      </Dialog>
+    </>
+  );
+}
+
+/** Single-line AI text field — ghost-text completion + correct/translate/
+ *  rewrite toolbar. Degrades to a plain text field when `ai-text` isn't
+ *  mounted server-side. */
+export function AiTextField(props: AiTextFieldProps): ReactNode {
+  return <AiTextCore {...props} multiline={false} />;
+}
+
+/** Multi-line variant of {@link AiTextField}. */
+export function AiTextArea(props: AiTextAreaProps): ReactNode {
+  return <AiTextCore {...props} multiline={true} />;
+}

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,43 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+/** Read-only Schlüssel-Wert-Liste für Detail-Masken (Label links gedimmt,
+ *  Wert rechts). Wert ist ReactNode → Badges/Chips möglich. `emphasize` hebt
+ *  eine Zeile hervor (z.B. das Endergebnis in einem Rechner). */
+export function DetailList({
+  rows,
+  testId,
+}: {
+  readonly rows: readonly {
+    /** Optional stable key -- falls back to the label when omitted (fine as
+     *  long as labels are unique; set id when they can repeat). */
+    readonly id?: string;
+    readonly label: string;
+    readonly value: ReactNode;
+    readonly emphasize?: boolean;
+  }[];
+  readonly testId?: string;
+}): ReactNode {
+  return (
+    <dl data-testid={testId} className="flex flex-col divide-y">
+      {rows.map((row) => (
+        <div
+          key={row.id ?? row.label}
+          className="grid grid-cols-1 gap-0.5 py-2.5 sm:grid-cols-[200px_1fr] sm:gap-4"
+        >
+          <dt
+            className={cn(
+              "text-sm text-muted-foreground",
+              row.emphasize === true && "font-semibold text-foreground",
+            )}
+          >
+            {row.label}
+          </dt>
+          <dd className={cn("text-sm font-medium", row.emphasize === true && "font-semibold")}>
+            {row.value}
+          </dd>
+        </div>
+      ))}
+    </dl>
+  );
+}