Dashboard/features/dashboard/components/cards/KPICard.tsx

"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 (
    /* 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. */
    <article className="flex h-full 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>
  );
}