"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 ( /* h-full: Die Karte füllt ihre Rasterzelle. Ohne das ist die Karte mit Trendzeile und Verlaufskurve höher als ihre Nachbarn, und eine Reihe gleichartiger Kennzahlen bekommt eine ungleiche Unterkante: auf dem Dashboard sichtbar, weil dort ein Link zwischen Zelle und Karte steht und die Streckung des Rasters nicht mehr durchreicht. */
{/* 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}
); }