Dashboard Refactor (#5)

# Dashboard Refactor

## Overview

This merge request performs a major cleanup and architectural refactor of the dashboard component system.

The primary goals were:

* Consolidate dashboard state handling
* Standardize component contracts
* Remove duplicated transaction aggregation logic
* Simplify theming
* Eliminate unnecessary wrapper/view layers
* Improve maintainability and type safety

---

# Major Changes

## Dashboard Architecture Refactor

### Consolidated State API

Introduced a centralized `DashboardStateSetters` interface:

```ts
export interface DashboardStateSetters {
  setSelectedPeriodId: (id: DashboardSelectedPeriodId) => void;
  setSelectedGroupKey: (groupKey: GroupKey | null) => void;
  toggleFlow: () => void;
  togglePeriodType: () => void;
  toggleComparison: () => void;
}
```

This removes scattered prop drilling and standardizes dashboard interaction handling.

---

### Introduced Shared `ComponentProps`

All dashboard widgets now consume a unified contract:

```ts
export interface ComponentProps extends DashboardSection {
  reportData: ReportData;

  state: DashboardState;
  stateSetters: DashboardStateSetters;
  isFetching: boolean;

  colorScheme: {
    primary: string;
    light: string;
    text: string;
  };
}
```

Benefits:

* Consistent widget APIs
* Reduced repetitive prop definitions
* Easier extensibility
* Cleaner component composition

---

### Removed `Dashboard.view.tsx`

The view/container split was removed.

Dashboard rendering now lives directly inside:

```ts
Dashboard.tsx
```

Benefits:

* Reduced indirection
* Easier navigation
* Lower cognitive overhead
* Simpler state flow

---

## Dashboard Config Cleanup

Removed legacy `style.size` configuration from dashboard sections.

Before:

```ts
style: {
  size: 12,
}
```

Now:

```ts
{
  id: "items",
  title: "Recent Transactions",
  component: LatestItems,
}
```

This simplifies section configuration and removes unnecessary abstraction.

---

# Shared Transaction Utilities

## Added `extractFilteredTransactions`

Created a reusable transaction extraction helper:

```ts
extractFilteredTransactions(
  reportData,
  selectedPeriodId,
  selectedGroupKey
)
```

This centralizes:

* Period resolution
* Group filtering
* Tag filtering
* Payee filtering

Previously duplicated across:

* LatestItems
* TopTags
* TopPayees

---

## Added `aggregateTransactions`

Created a reusable aggregation utility:

```ts
aggregateTransactions(
  transactions,
  keyExtractor,
  limit
)
```

Benefits:

* Removes repeated Map aggregation logic
* Standardizes sorting and totals
* Simplifies adapters significantly

---

# HistoryChart Refactor

## Split Models vs Props

Separated:

* data models
* component props
* view props

into dedicated files.

New:

```txt
HistoryChart.models.ts
HistoryChart.props.ts
```

Benefits:

* Cleaner typing boundaries
* Better maintainability
* Reduced coupling

---

## Migrated to Shared Dashboard State

HistoryChart now consumes:

```ts
state
stateSetters
```

instead of individual props.

This aligns it with the new dashboard architecture.

---

# LatestItems Refactor

## Simplified Component Contract

Removed duplicated props:

* flow
* header
* accentColor
* selectedPeriodId
* selectedGroupKey

Now inherited from shared `ComponentProps`.

---

## Added Auto Reset on Flow Change

```ts
React.useEffect(() => {
  setVisibleCount(5);
}, [flow]);
```

Improves UX when switching inflow/outflow views.

---

# ProgressCard Refactor

## Removed `ProgressCard.tsx`

Deleted unnecessary wrapper component.

Rendering logic now lives directly in:

```txt
ProgressCard.view.tsx
```

---

## Introduced `ProgressCard.props.ts`

Separated props into dedicated interfaces:

```ts
ProgressCardProps
ProgressCardViewProps
```

---

## Reworked Styling System

Removed dependency on:

```ts
colorTheme
```

Now fully driven by:

```ts
colorScheme
```

Benefits:

* Consistent dashboard-wide theming
* Better dark mode behavior
* Reduced MUI palette coupling

---

## Improved Visual Consistency

Updated:

* borders
* shadows
* progress bar styling
* dark mode surfaces
* selection state styling

to use standardized dashboard colors.

---

# TopTags & TopPayees Refactor

## Removed Duplicated Aggregation Logic

Both adapters now use:

```ts
extractFilteredTransactions()
aggregateTransactions()
```

instead of maintaining separate filtering/aggregation implementations.

Benefits:

* Less code duplication
* Consistent behavior
* Easier future maintenance

---

## Migrated to Shared Component Props

Both components now consume:

```ts
ComponentProps
```

via:

```ts
ProgressCardProps
```

This aligns all dashboard widgets under the same architecture.

---

# Theme System Cleanup

## Consolidated AppTheme

Moved to:

```txt
src/shared-theme/AppTheme.tsx
```

and removed unused duplicate implementations.

---

## Added Explicit Color Mode Context

Introduced:

```ts
ColorModeContext
```

with:

* `mode`
* `setMode`
* `toggleColorMode`

This provides a cleaner foundation for future theme controls.

---

## Simplified Theme Creation

Replaced older MUI experimental color scheme setup with:

```ts
getDesignTokens(mode)
```

Benefits:

* Easier to reason about
* Cleaner light/dark handling
* Less framework complexity

---

## Added Global CssBaseline

```tsx
<CssBaseline />
```

is now applied centrally inside `AppTheme`.

---

# Type Safety Improvements

## Removed Optional Fields Where Invalid

Several previously optional fields are now required:

```ts
title: string
background: string
text: string
isFetching: boolean
style.palette
```

Benefits:

* Stronger guarantees
* Fewer runtime fallbacks
* Simpler rendering logic

---

# Cleanup Summary

## Removed

* `Dashboard.view.tsx`
* `ProgressCard.tsx`
* legacy prop duplication
* repeated transaction extraction logic
* repeated aggregation logic
* unused style configuration
* legacy theme configuration complexity

---

## Added

* centralized dashboard state setters
* reusable transaction helpers
* reusable aggregation helper
* unified component props
* dedicated prop definition files
* explicit color mode context
* consolidated theme provider

---

# Result

The dashboard system is now:

* significantly more maintainable
* easier to extend
* more type-safe
* less repetitive
* more consistent across widgets
* cleaner in terms of state ownership
* simpler to theme and customize

Reviewed-on: #5
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>

src/components/LatestItems/LatestItems.adapter.ts

@@ -1,67 +1,19 @@
-import { ReportData, Transaction, GroupKey } from "../../features/report";
+import { ReportData, GroupKey } from "../../features/report";
 import {
-  mergeBucketPeriods,
-  periodIdToKey,
   formatCurrency,
-  filterBuckets,
+  extractFilteredTransactions,
 } from "../report.helpers";
 import { LatestItem } from "./LatestItems.models";
 
-// ─── Transaction extraction ─────────────────────────────────
-
-function extractTransactions(
-  reportData: ReportData,
-  selectedPeriodId: string | null,
-  selectedGroupKey: GroupKey | null,
-): Transaction[] {
-  // 1. Get raw transactions
-  let rawTxns: Transaction[] = [];
-
-  if (selectedPeriodId) {
-    const key = periodIdToKey(selectedPeriodId);
-    const periods = mergeBucketPeriods(reportData.buckets, key);
-    const selected = periods.find((p) => p.id === selectedPeriodId);
-    rawTxns = selected?.metric.transactions || [];
-  } else {
-    const periods = mergeBucketPeriods(reportData.buckets, "all");
-    if (periods.length > 0) {
-      rawTxns = periods[0].metric.transactions || [];
-    }
-  }
-
-  // 2. Filter by group key
-  if (selectedGroupKey) {
-    rawTxns = rawTxns.filter(txn => {
-      let match = true;
-      if (selectedGroupKey.tags && selectedGroupKey.tags.length > 0) {
-        if (!txn.tags) match = false;
-        else {
-          const txnTags = txn.tags.map(t => typeof t === "string" ? t : t.name);
-          if (!selectedGroupKey.tags.every(selectedTag => txnTags.includes(selectedTag))) match = false;
-        }
-      }
-      if (match && selectedGroupKey.payee && selectedGroupKey.payee.length > 0) {
-        if (!txn.payee || !txn.payee.name) match = false;
-        else {
-          if (!selectedGroupKey.payee.includes(txn.payee.name)) match = false;
-        }
-      }
-      return match;
-    });
-  }
-
-  return rawTxns;
-}
-
 // ─── Main adapter ────────────────────────────────────────────
 
 export function buildLatestItems(
   reportData: ReportData,
-  selectedPeriodId: string | null,
-  selectedGroupKey: GroupKey | null,
+  selectedPeriodId: string | null | undefined,
+  selectedGroupKey: GroupKey | null | undefined,
   flow: "outflows" | "inflows"
 ): LatestItem[] {
-  const txns = extractTransactions(reportData, selectedPeriodId, selectedGroupKey);
+  const txns = extractFilteredTransactions(reportData, selectedPeriodId, selectedGroupKey);
 
   return txns
     .sort(

src/components/LatestItems/LatestItems.models.ts

@@ -5,12 +5,3 @@ export interface LatestItem {
   amount: string;
   timeAgo: string;
 }
-
-export interface LatestItemsViewProps {
-  items: LatestItem[];
-  header: string;
-  accentColor: string;
-  canExpand: boolean;
-  onExpand: () => void;
-  isFetching?: boolean;
-}

src/components/LatestItems/LatestItems.props.ts

@@ -0,0 +1,10 @@
+import { ComponentProps } from "../Dashboard";
+import { LatestItem } from "./LatestItems.models";
+
+export interface LatestItemsProps extends ComponentProps {}
+
+export interface LatestItemsViewProps extends LatestItemsProps {
+  items: LatestItem[];
+  canExpand: boolean;
+  onExpand: () => void;
+}

src/components/LatestItems/LatestItems.tsx

@@ -1,29 +1,24 @@
 import * as React from "react";
-import { ReportData, GroupKey } from "../../features/report";
 import { buildLatestItems } from "./LatestItems.adapter";
 import LatestItemsView from "./LatestItems.view";
+import { LatestItemsProps } from "./LatestItems.props";
 
-type Props = {
-  reportData: ReportData;
-  flow: "outflows" | "inflows";
-  header: string;
-  selectedPeriodId: string | null;
-  selectedGroupKey?: GroupKey | null;
-  accentColor: string;
-  isFetching?: boolean;
-};
+export default function LatestItems(props: LatestItemsProps) {
+  const {
+    reportData,
+    state,
+    stateSetters,
+    isFetching,
+  } = props;
 
-export default function LatestItems({
-  reportData,
-  flow,
-  header,
-  selectedPeriodId,
-  selectedGroupKey = null,
-  accentColor,
-  isFetching,
-}: Props) {
+  const { flow, selectedPeriodId, selectedGroupKey } = state;
   const [visibleCount, setVisibleCount] = React.useState(5);
 
+  // Reset count when flow changes to start clean
+  React.useEffect(() => {
+    setVisibleCount(5);
+  }, [flow]);
+
   const allItems = React.useMemo(() => {
     return buildLatestItems(reportData, selectedPeriodId, selectedGroupKey, flow);
   }, [reportData, selectedPeriodId, selectedGroupKey, flow]);
@@ -36,11 +31,9 @@ export default function LatestItems({
 
   return (
     <LatestItemsView
+      {...props}
       items={visibleItems}
-      header={header}
-      accentColor={accentColor}
       canExpand={canExpand}
-      isFetching={isFetching}
       onExpand={() => setVisibleCount((prev) => prev + 5)}
     />
   );

src/components/LatestItems/LatestItems.view.tsx

@@ -10,21 +10,23 @@ import {
   IconButton,
 } from "@mui/material";
 import ExpandMoreIcon from "@mui/icons-material/ExpandMore";
-import { LatestItemsViewProps } from "./LatestItems.models";
+import { LatestItemsViewProps } from "./LatestItems.props";
 
 export default function LatestItemsView({
   items,
-  header,
-  accentColor,
+  title,
   canExpand,
   onExpand,
   isFetching,
+  colorScheme,
 }: LatestItemsViewProps) {
+  const accentColor = colorScheme?.primary || "";
+
   return (
     <Box sx={{ width: "100%", bgcolor: "background.paper", borderRadius: 4, p: 2, opacity: isFetching ? 0.6 : 1, transition: "opacity 0.3s ease", pointerEvents: isFetching ? "none" : "auto" }}>
       <Box sx={{ mb: 2, px: 2 }}>
         <Typography variant="h6" fontWeight="bold">
-          {header}
+          {title}
         </Typography>
       </Box>