Files
Dashboard/features/dashboard/components/cards/KPICard.tsx
T
dejanandClaude Opus 5 831a6ec9ad Dashboard als Widget-Flaeche bauen, Platzhalter ersetzen
Das Dashboard ist ein eigenes Feature neben Analytics: der
Begruessungsbildschirm, nicht ein zweiter Analysebereich. Es zeigt heute nur
Auswertungen, ist aber so gebaut, dass die spaeteren Bereiche als weitere
Kacheln dazukommen und nicht als Umbau.

Aufbau: Begruessung, vier Kennzahlen (je ein Link in die Analyse),
Handlungsbedarf, vier Diagramme, drei reservierte Plaetze.

Drei Entscheidungen, die dabei getroffen wurden:

- Kein seitenweiter Filter. Jede Kachel traegt ihren eigenen Zeitraum und
  schreibt ihn in den Kopf. Das ist das Bedienmodell der Software (P11) und
  war die unbequemere Variante; eine Filterleiste haette beim Einbau alle
  Kacheln wieder auseinandergenommen.

- Das Raster ist aus DashboardPage.tsx der Software uebernommen, nicht
  erfunden: dieselben Klassen, dieselbe Ableitung aus size.w und position.x.
  Der Software fehlt dafuer eine Zeile (position.x === 9); vermerkt in
  WidgetRaster.tsx.

- Die reservierten Plaetze zeigen keine erfundenen Zahlen. "2 neue Antraege"
  aus dem Nichts liest sich in einer Abnahme wie eine fertige Funktion.

Absichtliche Doppelung: Der Handlungsbedarf steht jetzt auf dem Dashboard und
weiterhin auf der Analytics-Uebersicht. Ihn dort zu entfernen haette die
offene Frage 5.1 mitentschieden. Dokumentiert in Abschnitt 3a des
Scope-Papiers, aufzuloesen vor dem Port.

Nebenbei zwei Fehler behoben, die auch Analytics betrafen:

- Die Beschriftungen der Zeitachse liefen in schmalen Karten ineinander
  (fuenf Kalenderwochen brauchen 200px, eine halbe Kachel bei 768px hat 150).
  Recharts duennt sie jetzt selbst aus und haelt Anfang und Ende.

- Das Zeitraum-Etikett im Kachelkopf schaltete per Viewport-Breakpoint, die
  Kachelbreite haengt aber am Raster. Bei 1024px blieben dem Untertitel 77px,
  und er lief ins Diagramm. Jetzt Container-Query.

Die Wurzel leitet auf /dashboard statt /analytics — wie in der Software, wo
nach der Anmeldung der Begruessungsbildschirm steht.

tsc, lint, build, verify:carbon und verify:layout (7 Seiten x 9 Breiten)
laufen sauber.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QPeZNwSeU7qG3RRCwaxEZX
2026-08-31 16:51:09 +02:00

157 lines
5.9 KiB
TypeScript

"use client";
import React from "react";
import { FeatherArrowDownRight, FeatherArrowUpRight, FeatherMinus } from "@subframe/core";
import { FeatherIcon } from "../layout/FeatherIcon";
import { Sparkline } from "../charts/Sparkline";
import { CHART, STATUS_FARBEN } from "../../utils/chartTheme";
/** Zeitbezug einer Kennzahl — siehe docs/KPI-KATALOG.md. */
export type Bezug = "zeitraum" | "stichtag" | "gesamt";
const BEZUG_LABEL: Record<Bezug, string> = {
zeitraum: "im gewählten Zeitraum",
stichtag: "zum Stichtag",
gesamt: "über alle Zeiträume",
};
/**
* KPI-Karte nach UI_UX_GUIDELINES.md, Abschnitt 4:
* Label oben links · Icon oben rechts · Wert · Zusatz · Fußzeile.
*
* Alle Karten einer Reihe haben dieselbe Anatomie — auch die ohne Trend.
* Wo kein Vorperiodenvergleich möglich ist (stichtagsbezogene Kennzahlen),
* trägt die Fußzeile den Zeitbezug. Ohne das steht in einer Reihe eine
* Karte mit Trendzeile neben vier Karten mit leerem Fuß, und das Auge
* sucht eine Regel, die es nicht gibt.
*
* Der Trend vergleicht immer mit der gleich langen Vorperiode
* (30 Tage gegen die 30 Tage davor) — nicht mit dem Vorjahr.
*/
export function KPICard({
label,
wert,
zusatz,
trend,
trendLabel = "Vorperiode",
bezug = "zeitraum",
/**
* Überschreibt die Fußzeile. Analytics hat einen seitenweiten Filter, deshalb
* heißt es dort "im gewählten Zeitraum". Auf dem Dashboard gibt es den nicht
* — jede Kachel trägt ihren eigenen Zeitraum und muss ihn benennen können.
*/
bezugText,
icon,
verlauf,
akzent = "neutral",
/** Bei "positiv" ist ein steigender Wert gut, bei "negativ" schlecht. */
richtungGut = "positiv",
}: {
label: string;
wert: string;
zusatz?: string;
trend?: { wert: number; richtung: "up" | "down" | "flat" };
trendLabel?: string;
bezug?: Bezug;
bezugText?: string;
icon: string;
verlauf?: number[];
/**
* Färbt das Icon. Nur setzen, wenn die Farbe aus einem Schwellenvergleich
* kommt — ein dekorativ grünes Icon behauptet "gut", ohne es zu belegen
* (docs/DESIGN-SYSTEM.md §1: Statusfarben nur für Aussagen).
*/
akzent?: "neutral" | "positiv" | "warnung" | "negativ" | "info";
richtungGut?: "positiv" | "negativ";
}) {
const gut =
trend?.richtung === "flat"
? null
: richtungGut === "positiv"
? trend?.richtung === "up"
: trend?.richtung === "down";
const trendFarbe =
gut === null ? STATUS_FARBEN.neutral : gut ? STATUS_FARBEN.positiv : STATUS_FARBEN.negativ;
const akzentFarbe = {
neutral: CHART.textSekundaer,
positiv: STATUS_FARBEN.positiv,
warnung: STATUS_FARBEN.warnung,
negativ: STATUS_FARBEN.negativ,
info: STATUS_FARBEN.info,
}[akzent];
return (
<article className="flex min-h-[136px] flex-col rounded-lg border border-solid border-border-default bg-white p-4 shadow-sm transition-shadow duration-200 hover:shadow-md">
<div className="flex items-start justify-between gap-2">
{/* min-w-0 + break-words: Ohne das schiebt ein langes Label wie
„Umsatz (Zahlungseingang)" das Icon aus der Karte und laeuft selbst
ueber den Rand. Die Karte wird dadurch eine Zeile hoeher — das ist
der Preis dafuer, dass die Beschriftung vollstaendig lesbar bleibt
(docs/DESIGN-SYSTEM.md §9). */}
<span className="min-w-0 break-words text-[12px] font-medium leading-tight text-text-neutral-tertiary">
{label}
</span>
<span
className="flex h-8 w-8 flex-none items-center justify-center rounded-md bg-neutral-50"
style={{ color: akzentFarbe }}
>
<FeatherIcon name={icon} className="text-[15px]" />
</span>
</div>
<div className="mt-3 flex flex-col gap-1">
{/* "277.460 €" und "34,2 Tage" tragen ihre Einheit als eigenes Wort.
Ohne nowrap bricht die schmale Karte zwischen Betrag und Einheit um:
Die Zahl liest sich dann einen Augenblick lang als Wert ohne Einheit,
und die Karte wächst um eine Zeile, wodurch die Reihe ihre gemeinsame
Grundlinie verliert. */}
<span className="whitespace-nowrap text-[28px] font-semibold leading-none tracking-[-0.02em] text-text-neutral-primary">
{wert}
</span>
{zusatz ? (
<span className="text-[12px] leading-snug text-text-neutral-tertiary">{zusatz}</span>
) : null}
</div>
{/* Fußzeile: immer vorhanden, damit die Reihe eine gemeinsame Grundlinie hat. */}
<div className="mt-auto flex items-end justify-between gap-3 pt-3">
{trend ? (
<span
className="flex min-w-0 items-center gap-1 whitespace-nowrap text-[12px] font-medium"
style={{ color: trendFarbe }}
>
{trend.richtung === "up" ? (
<FeatherArrowUpRight className="text-[13px] flex-none" />
) : trend.richtung === "down" ? (
<FeatherArrowDownRight className="text-[13px] flex-none" />
) : (
<FeatherMinus className="text-[13px] flex-none" />
)}
{trend.richtung === "flat"
? "unverändert"
: `${trend.wert.toFixed(1).replace(".", ",")} %`}
<span className="hidden truncate font-normal text-text-neutral-tertiary xl:inline">
{trendLabel}
</span>
</span>
) : (
<span className="text-[11px] leading-tight text-text-neutral-tertiary">
{bezugText ?? BEZUG_LABEL[bezug]}
</span>
)}
{verlauf && verlauf.length > 1 ? (
<span className="h-8 w-16 flex-none">
{/* Die Kurve trägt dieselbe Aussage wie der Pfeil daneben und
deshalb auch dieselbe Farbe — sonst zeigt die Karte zwei
widersprüchliche Signale. */}
<Sparkline werte={verlauf} farbe={trend ? trendFarbe : CHART.achse} />
</span>
) : null}
</div>
</article>
);
}