feat(dashboard): Analytics-Dashboard als Gestaltungsvorlage zur Übergabe

UI/UX-Prototyp der Analytics-Dashboards in HiveGrid, fachlich auf einen
SHK-/Handwerksbetrieb zugeschnitten. Ziel ist die Übergabe an die Entwicklung,
nicht der Produktivbetrieb.

Inhalt: sechs Seiten (Übersicht, Finanzen, Aufträge, Kunden, Team, Komponenten),
26 KPIs, neun Chart-Bausteine, Filtersystem mit seitenabhängiger Relevanz und ein
deterministischer Demo-Datensatz (420 Kunden, 1.900 Aufträge, Stichtag 30.07.2026).

Drei Quellen sind zusammengeführt: die fachliche Planung mit dem Branchenpartner
(Januar 2026), die Subframe-Komponentenbibliothek aus dem HiveGrid-Pitch und
IBM Carbon Data Visualization für die Diagrammregeln. Herkunft und bewusste
Abweichungen stehen in docs/HERKUNFT.md.

Dokumentation: README, HANDOVER (was echte Logik braucht), docs/DESIGN-SYSTEM,
KPI-KATALOG, DATENMODELL, NAVIGATION, HERKUNFT, ZIELSYSTEM (Einbauort in
HiveGrid Cloud) und LEITPLANKEN (welche Cloud-Screens als Vorbild taugen).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QPeZNwSeU7qG3RRCwaxEZX
This commit is contained in:
dejanandClaude Opus 5 committed 2026-08-29 17:25:20 +02:00
commit b8bf987d0e
250 files changed
+33153

No files matched your search

@@ -0,0 +1,107 @@
"use client";
import React from "react";
import {
FeatherAlertTriangle,
FeatherArrowRight,
FeatherCheckCircle,
FeatherInfo,
} from "@subframe/core";
import { STATUS_FARBEN } from "../../utils/chartTheme";
import { formatEuro } from "../../utils/formatters";
import { useToast } from "../../context/ToastContext";
import type { AlertEintrag } from "../../data/calculations";
/**
* Handlungsbedarf-Liste (COMP-08).
*
* Jede Zeile nennt drei Dinge: was los ist, um wie viel Geld es geht und was
* zu tun ist. Ohne den Betrag lassen sich die Zeilen nicht gegeneinander
* abwägen, ohne die Handlung ist die Liste ein Bericht statt einer Arbeitsliste.
* Der Absprung in die jeweilige Arbeitsliste ist im Prototyp eine Attrappe.
*/
export function AlertList({
eintraege,
leerText = "Keine offenen Punkte",
/** Zwei Spalten, wenn die Karte über die volle Seitenbreite läuft. */
spalten = 1,
}: {
eintraege: AlertEintrag[];
leerText?: string;
spalten?: 1 | 2;
}) {
const { zeigeToast } = useToast();
const rang = { kritisch: 0, warnung: 1, hinweis: 2 } as const;
const sortiert = [...eintraege].sort((a, b) => rang[a.art] - rang[b.art]);
if (!sortiert.length) {
return (
<div className="flex h-full min-h-[180px] flex-col items-center justify-center gap-2 text-center">
<FeatherCheckCircle className="text-[22px]" style={{ color: STATUS_FARBEN.positiv }} />
<span className="text-[13px] text-text-neutral-tertiary">{leerText}</span>
</div>
);
}
return (
// Container-Query statt Viewport: dieselbe Liste steht mal über die volle
// Seitenbreite und mal in einer Drittelkarte. Der Viewport weiß davon nichts.
<ul
className={`@container ${
spalten === 2 ? "grid grid-cols-1 gap-x-8 xl:grid-cols-2" : "flex flex-col"
}`}
>
{sortiert.map((eintrag) => {
const farbe =
eintrag.art === "kritisch"
? STATUS_FARBEN.negativ
: eintrag.art === "warnung"
? STATUS_FARBEN.warnung
: STATUS_FARBEN.info;
return (
<li key={eintrag.id}>
<button
onClick={() =>
zeigeToast(eintrag.aktion, `${eintrag.text} — Absprung folgt in der Umsetzung`)
}
className="group flex w-full items-center gap-3 border-b border-solid border-border-default py-3 text-left last:border-b-0 hover:bg-neutral-50"
>
<span className="flex-none" style={{ color: farbe }}>
{eintrag.art === "hinweis" ? (
<FeatherInfo className="text-[16px]" />
) : (
<FeatherAlertTriangle className="text-[16px]" />
)}
</span>
<span className="flex min-w-0 grow flex-col">
<span className="text-[13px] font-medium leading-snug text-text-neutral-primary">
{eintrag.text}
</span>
<span className="text-[12px] leading-snug text-text-neutral-tertiary">
{eintrag.detail}
</span>
</span>
{eintrag.betrag !== undefined ? (
<span className="flex-none whitespace-nowrap text-[14px] font-semibold tabular-nums text-text-neutral-primary">
{formatEuro(eintrag.betrag)}
</span>
) : null}
{/* Schmale Karte: nur der Pfeil, die Handlung steht im Tooltip. */}
<span
title={eintrag.aktion}
className="flex flex-none items-center justify-end gap-1 whitespace-nowrap text-[12px] font-medium text-text-neutral-tertiary group-hover:text-text-neutral-primary @md:w-[150px]"
>
<span className="hidden @md:inline">{eintrag.aktion}</span>
<FeatherArrowRight className="text-[13px]" />
</span>
</button>
</li>
);
})}
</ul>
);
}
@@ -0,0 +1,144 @@
"use client";
import React from "react";
import {
FeatherDownload,
FeatherEyeOff,
FeatherInfo,
FeatherMoreHorizontal,
} from "@subframe/core";
import { useWidgets } from "../../context/WidgetContext";
import { useToast } from "../../context/ToastContext";
/**
* Rahmen für jede Visualisierung (COMP-09).
*
* Enthält die einzige "echte" Interaktionslogik des Prototyps:
* Über das ⋯-Menü lässt sich die Karte ausblenden; sie taucht dann in der
* Filterleiste zum Wiedereinblenden auf. Der Zustand ist persistiert.
*/
export function ChartCard({
id,
titel,
untertitel,
hinweis,
aktion,
legende,
children,
className = "",
}: {
/** Stabile ID — Schlüssel für Ausblenden/Einblenden. */
id: string;
titel: string;
untertitel?: string;
/** Erklärt die Kennzahl; erscheint als Tooltip am (i). */
hinweis?: string;
aktion?: React.ReactNode;
legende?: React.ReactNode;
children: React.ReactNode;
className?: string;
}) {
const { istSichtbar, verstecke } = useWidgets();
const { zeigeToast } = useToast();
const [menuOffen, setMenuOffen] = React.useState(false);
const menu = React.useRef<HTMLDivElement>(null);
const ausloeser = React.useRef<HTMLButtonElement>(null);
React.useEffect(() => {
if (!menuOffen) return;
const schliesse = (event: MouseEvent) => {
if (!menu.current?.contains(event.target as Node)) setMenuOffen(false);
};
// Escape schliesst und gibt den Fokus an den Ausloeser zurueck — sonst
// landet die Tastaturbedienung nach dem Schliessen am Seitenanfang.
const taste = (event: KeyboardEvent) => {
if (event.key === "Escape") {
setMenuOffen(false);
ausloeser.current?.focus();
}
};
document.addEventListener("mousedown", schliesse);
document.addEventListener("keydown", taste);
return () => {
document.removeEventListener("mousedown", schliesse);
document.removeEventListener("keydown", taste);
};
}, [menuOffen]);
if (!istSichtbar(id)) return null;
return (
<section
className={`flex flex-col overflow-hidden rounded-lg border border-solid border-border-default bg-white shadow-sm ${className}`}
>
<header className="flex flex-none items-start justify-between gap-3 px-4 pb-3 pt-4">
<div className="flex min-w-0 flex-col">
<div className="flex items-center gap-1.5">
<h2 className="truncate text-[14px] font-semibold leading-tight text-text-neutral-primary">
{titel}
</h2>
{hinweis ? (
<span
title={hinweis}
className="flex h-4 w-4 flex-none cursor-help items-center justify-center text-text-neutral-subtle hover:text-text-neutral-secondary"
>
<FeatherInfo className="text-[13px]" />
</span>
) : null}
</div>
{untertitel ? (
<p className="line-clamp-2 text-[12px] leading-snug text-text-neutral-tertiary">
{untertitel}
</p>
) : null}
</div>
<div className="dv-no-print relative flex flex-none items-center gap-1" ref={menu}>
{aktion}
<button
ref={ausloeser}
onClick={() => setMenuOffen((wert) => !wert)}
aria-label={`Optionen für ${titel}`}
aria-haspopup="menu"
aria-expanded={menuOffen}
className="flex h-8 w-8 items-center justify-center rounded-md text-text-neutral-tertiary hover:bg-neutral-100 hover:text-text-neutral-primary"
>
<FeatherMoreHorizontal className="text-[16px]" />
</button>
{menuOffen ? (
<div
role="menu"
className="absolute right-0 top-9 z-40 flex w-52 flex-col rounded-lg border border-solid border-border-default bg-white py-1 shadow-lg"
>
<button
onClick={() => {
verstecke(id, titel);
setMenuOffen(false);
}}
className="flex items-center gap-2 px-3 py-2 text-left text-[13px] text-text-neutral-primary hover:bg-neutral-50"
>
<FeatherEyeOff className="text-[14px] text-text-neutral-tertiary" />
Widget ausblenden
</button>
<button
onClick={() => {
zeigeToast("Als Bild vorgemerkt", `${titel} — Export folgt in der Umsetzung`);
setMenuOffen(false);
}}
className="flex items-center gap-2 px-3 py-2 text-left text-[13px] text-text-neutral-primary hover:bg-neutral-50"
>
<FeatherDownload className="text-[14px] text-text-neutral-tertiary" />
Als Bild exportieren
</button>
</div>
) : null}
</div>
</header>
{legende ? <div className="flex-none px-4 pb-2">{legende}</div> : null}
<div className="min-h-0 grow px-4 pb-4">{children}</div>
</section>
);
}
@@ -0,0 +1,139 @@
"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",
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;
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">
<span className="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">
<span className="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">
{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>
);
}
@@ -0,0 +1,38 @@
import React from "react";
/**
* Kompakte Zusatzkennzahlen unter einem Chart —
* beantwortet "und was heißt das jetzt?" ohne eigene Karte.
*/
export function StatZeile({
eintraege,
/**
* Spalten auf breiten Schirmen. In einer Drittelkarte brechen vier Spalten
* mitten im Betrag um ("1,22 Mio." / "€") — dort gehoeren zwei hin.
*/
spalten = 4,
}: {
eintraege: { label: string; wert: string; hinweis?: string }[];
spalten?: 2 | 3 | 4;
}) {
const raster = { 2: "md:grid-cols-2", 3: "md:grid-cols-3", 4: "md:grid-cols-4" }[spalten];
return (
<div
className={`grid grid-cols-2 gap-x-6 gap-y-3 border-t border-solid border-border-default pt-3 ${raster}`}
>
{eintraege.map((eintrag) => (
<div key={eintrag.label} className="flex flex-col gap-0.5">
<span className="text-[11px] uppercase tracking-[0.06em] text-text-neutral-tertiary">
{eintrag.label}
</span>
<span className="text-[14px] font-semibold tabular-nums text-text-neutral-primary">
{eintrag.wert}
</span>
{eintrag.hinweis ? (
<span className="text-[11px] text-text-neutral-tertiary">{eintrag.hinweis}</span>
) : null}
</div>
))}
</div>
);
}