Dashboard/docs/NAVIGATION.md

# Navigation und Seitenaufbau

## Struktur

Die Seitenleiste zeigt **nur unsere beiden Features**. Kontakte, Leads,
Pipelines, Postfach, Termine und Einstellungen stehen bereits in der
Seitenleiste der Software und werden hier nicht verdoppelt — der Prototyp zeigt,
was dazukommt, nicht was schon da ist.

```
HIVEGRID
├── Dashboard          eigenes Feature, nicht Teil dieses Prototyps
└── Analytics          ◄── der Prototyp lebt hier   /analytics
├─────────────────────
└── Komponenten        Bausteingalerie des Prototyps   /komponenten
```

Gerendert wird mit derselben Komponente wie in der Software
(`ui/components/SidebarWithSections`, aus der Cloud-Fassung portiert) und
derselben Schrift (Instrument Sans, selbst gehostet aus denselben Dateien).

**Analytics ist ein einzelner Menüpunkt**, kein aufklappbarer Bereich. Die fünf
Analyse-Seiten sind darin über eine **innere Leiste** erreichbar:

```
/analytics            Übersicht
/analytics/finanzen   Finanzen
/analytics/auftraege  Aufträge
/analytics/kunden     Kunden
/analytics/team       Team
```

Zwei Navigationsebenen für dieselbe Sache — Unterpunkte in der Seitenleiste
*und* eine innere Leiste — würden nur konkurrieren.

### Warum innere Leiste und nicht Reiter

Beides gibt es im Zielsystem, aber für verschiedene Aufgaben:

| | innere Leiste (`SidebarIconsLayout`) | Reiter (`Tabs`) |
|---|---|---|
| Wofür | Arbeitsbereich mit **Geschwisterseiten** | Abschnitte **innerhalb einer Seite** |
| Beispiele | Leads, Termine, HR, Einstellungen — 17 Aufrufstellen | Formular-Editor, Chat-Dateien, Projekt-Teilbereiche, Übergabe-Dialog |

Analytics mit fünf Analyse-Seiten ist der erste Fall — strukturell dasselbe wie
Leads mit seinen acht. Drei Gründe geben den Ausschlag:

1. **Kohärenz.** Wer in der Software von Leads nach Analytics wechselt, findet
   dieselbe Bedienung an derselben Stelle.
2. **Der Platzeinwand trägt nicht.** Die Leiste ist standardmäßig eine 32 px
   schmale Icon-Spalte und klappt erst bei Zeigerkontakt oder Tastaturfokus auf
   Beschriftungen aus (verzögert, damit sie beim Überstreichen nicht
   aufspringt). Sie kostet also kaum Breite — und die brauchen die
   Analyse-Seiten mit ihren fünfspaltigen Kennzahlenreihen und breiten Tabellen.
3. **Reiter sind dort der Rückfall, nicht die Wahl.** `SidebarIconsLayout`
   zeigt unterhalb `sm` selbst eine Reiterleiste. Auf dem Schreibtisch Reiter zu
   verwenden hieße, die Handy-Notlösung zur Hauptform zu machen. Unser Nachbau
   übernimmt diesen Rückfall mit.

Ein weiterer Vorteil: Die Leiste wächst. Käme eine sechste Analyse-Seite dazu,
ist das eine Zeile mehr — ein Reiterband würde eng.

„Dashboard" führt hier nirgendwohin und meldet das beim Klick — es ist ein
eigenes Feature, siehe [SCOPE-ANALYTICS-DASHBOARD.md](SCOPE-ANALYTICS-DASHBOARD.md).

---

## Aufbau jeder Analyse-Seite

```
┌──────────────────────────────────────────────────────────────┐
│ Kopfzeile: Breadcrumb · Suche · Benachrichtigungen · Profil  │  fest
├──────────────────────────────────────────────────────────────┤
│ Seitenkopf: Titel · Einordnung        Aktualisieren Export ⇗ │
├──────────────────────────────────────────────────────────────┤
│ Filterleiste: Zeitraum │ Dimensionen │ zurücksetzen          │  klebt oben
│ Aktive Filter als entfernbare Chips                          │
│ Ausgeblendete Widgets (nur wenn welche versteckt sind)       │
├──────────────────────────────────────────────────────────────┤
│ KPI-Reihe (5 Karten, gleiche Höhe)                           │
│ [nur Übersicht] Handlungsbedarf über volle Breite            │
│ Hauptdiagramm (2/3)              │ Nebendiagramm (1/3)       │
│ Detaildiagramme (2–3, oben bündig)                           │
│ Arbeitsliste (Tabelle)                                       │
└──────────────────────────────────────────────────────────────┘
```

Die Reihenfolge folgt der Lesefrage: **Wie steht es? → Was ist zu tun? → Wie hat
es sich entwickelt? → Woran liegt es?**

Auf der **Übersicht** steht der Handlungsbedarf direkt unter der KPI-Reihe und
über die volle Breite. Sie ist die Seite der Geschäftsführung; dort ist „was ist
zu tun" die zweite Frage, nicht die letzte. Jede Zeile trägt Betrag und Handlung
(„Mahnlauf starten", „Nachfassen") — eine Liste ohne Verb ist ein Bericht.

Auf den vier Detailseiten bleibt die Arbeitsliste unten: Dort ist sie die
Konsequenz aus dem, was darüber steht.

**Gleiche Kartenhöhe nur bei gleicher Struktur.** Die KPI-Reihe wird gestreckt,
damit die fünf Karten als ein Objekt lesbar sind. Gemischte Reihen (Diagramm
mit fester Höhe neben Tabelle) stehen auf `items-start` — Strecken erzeugt dort
nur Weißraum.

---

## Interaktionen

| Element | Verhalten |
|---|---|
| **Zeitraum** | Heute · 7 Tage · 30 Tage · Quartal · Jahr · Gesamt. Rechnet alle zeitraumbezogenen Kennzahlen und Charts neu, inklusive Vorperiodenvergleich |
| **Dimensionsfilter** | Mehrfachauswahl mit Suche; wirkt sofort. Nur Filter, die auf der Seite etwas bewirken, werden angeboten |
| **Filter-Chips** | Jede Einschränkung erscheint als Chip und lässt sich einzeln entfernen |
| **Widget ausblenden** | ⋯-Menü an jeder Karte. Ausgeblendete Karten erscheinen in der Filterleiste und lassen sich einzeln oder gesammelt zurückholen |
| **Hover** | Balken, Ringsegmente und Trichterstufen heben sich hervor, die übrigen treten zurück; Verläufe zeigen einen Tooltip mit allen Reihen des Datenpunkts |
| **Handlungsbedarf** | Jede Zeile ist ein Absprung in die zugehörige Arbeitsliste (im Prototyp Attrappe mit Hinweis) |
| **Tastatur** | Fokus ist auf allen interaktiven Elementen sichtbar; Filter-Dropdown und Karten-Menü schließen mit Escape und geben den Fokus zurück |
| **Ringlegende** | Klick hebt ein Segment dauerhaft hervor, erneuter Klick löst es wieder |
| **Tabellen** | Spaltenkopf sortiert, Suchfeld filtert, Blättern über Pfeile |
| **Seitenleiste** | Einklappbar; die Auswahl bleibt beim Seitenwechsel erhalten |

Filterauswahl und ausgeblendete Widgets überleben einen Reload
(`localStorage`, Schlüssel `hivegrid.analytics.*`).

---

## Seitenabhängige Filterrelevanz

Definiert in `features/dashboard/data/filtering.ts`:

| Seite | Zeitraum | Gewerk | Auftragsstatus | Kundenquelle | Region | Mitarbeiter |
|---|:--:|:--:|:--:|:--:|:--:|:--:|
| Übersicht | ✓ | ✓ | | | ✓ | |
| Finanzen | ✓ | ✓ | | ✓ | ✓ | |
| Aufträge | ✓ | ✓ | ✓ | | ✓ | ✓ |
| Kunden | ✓ | ✓ | | ✓ | ✓ | |
| Team | ✓ | ✓ | | | | ✓ |

Ein Filter, der sichtbar ist aber nichts bewirkt, kostet Vertrauen in die
Zahlen. Deshalb werden irrelevante Filter gar nicht erst angeboten — die
Auswahl bleibt aber im Hintergrund erhalten und wirkt beim Seitenwechsel wieder.