"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 = { 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 (
{/* 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). */} {label}
{/* "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. */} {wert} {zusatz ? ( {zusatz} ) : null}
{/* Fußzeile: immer vorhanden, damit die Reihe eine gemeinsame Grundlinie hat. */}
{trend ? ( {trend.richtung === "up" ? ( ) : trend.richtung === "down" ? ( ) : ( )} {trend.richtung === "flat" ? "unverändert" : `${trend.wert.toFixed(1).replace(".", ",")} %`} {trendLabel} ) : ( {bezugText ?? BEZUG_LABEL[bezug]} )} {verlauf && verlauf.length > 1 ? ( {/* Die Kurve trägt dieselbe Aussage wie der Pfeil daneben und deshalb auch dieselbe Farbe — sonst zeigt die Karte zwei widersprüchliche Signale. */} ) : null}
); }