CapaKraken/plan.md

Dashboard Widget Filter System — Plan

Anforderungsanalyse

Was: Einheitliches Filter-System fuer alle Dashboard-Widgets. Filter-Logik soll geteilt werden statt pro Widget dupliziert.

Anforderungen pro Widget:

Widget	Filter benoetigt
Project Health	Projektname (Suche), Client
Budget Forecast	Projektname (Suche), Client
Chargeability Overview	Country, Role/Chapter
Skill Gap	(optional: Skill-Suche)
Resource Table	Hat bereits: Chapter-Filter
Project Table	Hat bereits: Suche + Status-Filter
Peak Times	Hat bereits: Granularity + GroupBy

Design-Prinzip: Ein shared <WidgetFilterBar> Komponente die verschiedene Filter-Typen als deklarative Config akzeptiert. Filter-State wird via onConfigChange im Widget-Config persistiert (bereits vorhanden).

---

Architektur

Shared Filter Component

// Deklarative Filter-Konfiguration pro Widget
const filters: WidgetFilter[] = [
  { type: "search", key: "search", placeholder: "Filter projects..." },
  { type: "select", key: "clientId", label: "Client", options: clients },
  { type: "select", key: "countryId", label: "Country", options: countries },
  { type: "select", key: "roleId", label: "Role", options: roles },
];

<WidgetFilterBar
  filters={filters}
  values={config}                    // Aktueller Filter-State aus Widget-Config
  onChange={onConfigChange}          // Persistiert in localStorage via Dashboard-Layout
/>

Filter-Typen

Typ	UI-Element	Use Cases
search	Text-Input mit Lupe	Projektname, Ressourcenname
select	Dropdown	Client, Country, Role, Status
toggle	Checkbox	Include Proposed, Show Inactive

Daten-Flow

Widget Config (localStorage)
    ↓ values
WidgetFilterBar → onChange → onConfigChange → persistiert
    ↓ values
Widget Query (tRPC) → gefilterte Daten

---

Betroffene Pakete & Dateien

Paket	Dateien	Art der Aenderung
apps/web	src/components/dashboard/WidgetFilterBar.tsx	create — Shared Filter-Komponente
apps/web	src/hooks/useWidgetFilterOptions.ts	create — Hook fuer gemeinsame Filter-Optionen (clients, countries, roles)
apps/web	src/components/dashboard/widgets/ProjectHealthWidget.tsx	edit — Filter integrieren
apps/web	src/components/dashboard/widgets/BudgetForecastWidget.tsx	edit — Filter integrieren
apps/web	src/components/dashboard/widgets/ChargeabilityWidget.tsx	edit — Filter integrieren
apps/web	src/components/dashboard/widgets/SkillGapWidget.tsx	edit — Optional: Skill-Suche
apps/web	src/components/dashboard/widgets/DemandWidget.tsx	edit — Optional: Client/Chapter Filter
apps/web	src/components/dashboard/widgets/TopValueWidget.tsx	edit — Optional: Chapter Filter

---

Task-Liste

Phase 1: Shared Infrastructure

• Task 1: useWidgetFilterOptions Hook erstellen → src/hooks/useWidgetFilterOptions.ts

  • Cached Queries fuer Clients, Countries, Roles (alle mit staleTime: 300_000)
  • Gibt { clients, countries, roles, chapters } als { value: string, label: string }[] zurueck
  • Chapters extrahiert aus Resource-Daten oder als dedizierte Query
  • Nur einmal pro Dashboard geladen, von allen Widgets geteilt

• Task 2: WidgetFilterBar Komponente erstellen → src/components/dashboard/WidgetFilterBar.tsx

  interface WidgetFilter {
    type: "search" | "select" | "toggle";
    key: string;             // Config-Schluessel (z.B. "clientId")
    label?: string;          // Display-Label
    placeholder?: string;    // Fuer search/select
    options?: { value: string; label: string }[];  // Fuer select
  }
  
  interface WidgetFilterBarProps {
    filters: WidgetFilter[];
    values: Record<string, unknown>;
    onChange: (update: Record<string, unknown>) => void;
  }
  

  • Kompaktes Layout: horizontal, passt in Widget-Header-Bereich
  • Kleine Inputs (text-xs, py-1) damit sie nicht zu viel Platz nehmen
  • "Reset" Button wenn Filter aktiv
  • Dark-Theme Support

Phase 2: Widget Integration (parallel)

• Task 3: ProjectHealthWidget + Filter → ProjectHealthWidget.tsx

  • Filter: search (Projektname), select (Client)
  • Client-Daten laden via useWidgetFilterOptions
  • Filtern: rows.filter(r => matchesSearch && matchesClient)
  • Filter-State via config.search, config.clientId

• Task 4: BudgetForecastWidget + Filter → BudgetForecastWidget.tsx

  • Gleiche Filter wie ProjectHealth: search + clientId
  • Gleiche Logik, gleiche WidgetFilterBar Config

• Task 5: ChargeabilityWidget + Filter → ChargeabilityWidget.tsx

  • Filter: select (Country), select (Role/Chapter)
  • Country/Role-Daten via useWidgetFilterOptions
  • Filtern ueber die Resource-Daten in der Chargeability-Antwort
  • toggle (Include Proposed) — bereits vorhanden, in WidgetFilterBar integrieren

• Task 6: SkillGapWidget + Filter → SkillGapWidget.tsx

  • Filter: search (Skill-Name)
  • Einfache client-seitige Filterung der Skill-Liste

• Task 7: TopValueWidget + Filter → TopValueWidget.tsx

  • Filter: select (Chapter) — bereits sortierbar, Chapter-Filter hinzufuegen

---

Abhaengigkeiten

Task 1 (Hook) + Task 2 (WidgetFilterBar) → koennen parallel
Task 1+2 → Tasks 3-7 (alle parallel, verschiedene Dateien)

• Tasks 3-7 sind vollstaendig parallel (verschiedene Widget-Dateien)
• Tasks 1+2 muessen zuerst (shared Infrastructure)

---

Akzeptanzkriterien

• pnpm --filter @planarchy/web exec tsc --noEmit — keine neuen Errors
• ProjectHealth filterbar nach Projektname + Client
• BudgetForecast filterbar nach Projektname + Client
• Chargeability filterbar nach Country + Role
• SkillGap filterbar nach Skill-Name
• TopValue filterbar nach Chapter
• Filter-State wird in Widget-Config persistiert (bleibt nach Reload)
• Reset-Button setzt alle Filter zurueck
• Dark-Theme funktioniert fuer alle Filter
• Filter-Optionen werden gecacht (nicht pro Widget neu geladen)

---

Risiken & offene Fragen

Risiken

• Widget-Groesse: Filter-Bar braucht Platz — bei kleinen Widgets koennte es eng werden → Mitigation: Kompakte Inputs (xs), collapsible Filter-Bar mit Funnel-Icon
• Performance: Zusaetzliche tRPC-Queries fuer Client/Country/Role Listen → Mitigation: Ein shared Hook mit 5-Minuten staleTime, von allen Widgets geteilt

Offene Fragen

1. Server-side vs Client-side Filtering? → Empfehlung: Client-seitig, da Widget-Daten bereits komplett geladen sind (max 30-50 Rows)
2. Soll der Filter-Bar im Widget-Header oder darunter angezeigt werden? → Empfehlung: Direkt unter dem Titel, ueber der Tabelle — kompakt mit kleinen Inputs
3. Sollen Filter-Optionen leer sein wenn keine Daten vorhanden? → Ja, leere Dropdowns zeigen "(All)" als Default