apps/khata-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Dashboard Refactor (#5)

Browse Source 
# 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>
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-05-19 07:11:46 +00:00
committed by aetos
parent 8bea3d06f6
commit 16d164b92a
23 changed files with 510 additions and 620 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
src/components/ProgressCard/ProgressCard.models.ts
View File

@@ -1,11 +0,0 @@
export interface ProgressCardProps {
header: string;
summary?: string;
progressAmount: number;
totalAmount: number;
colorTheme?: "primary" | "secondary" | "error" | "info" | "success" | "warning";
compact?: boolean;
selected?: boolean;
onClick?: () => void;
isFetching?: boolean;
}

14
src/components/ProgressCard/ProgressCard.props.ts Normal file
View File

@@ -0,0 +1,14 @@
import { ComponentProps } from "../Dashboard";
export interface ProgressCardProps extends ComponentProps {
settings: {
compact: boolean;
};
}
export interface ProgressCardViewProps extends ProgressCardProps {
progressAmount: number;
totalAmount: number;
selected: boolean;
onClick: () => void;
}

25
src/components/ProgressCard/ProgressCard.tsx
View File

@@ -1,25 +0,0 @@
import * as React from "react";
import ProgressCardView from "./ProgressCard.view";
import { ProgressCardProps } from "./ProgressCard.models";
import { getPercentage, formatCurrency } from "../report.helpers";
export default function ProgressCard(props: ProgressCardProps) {
const { progressAmount, totalAmount, compact = false } = props;
const percentage = getPercentage(progressAmount, totalAmount);
const formattedProgress = formatCurrency(progressAmount);
const formattedTotal = formatCurrency(totalAmount);
return (
<ProgressCardView
{...props}
percentage={percentage}
formattedProgress={formattedProgress}
formattedTotal={formattedTotal}
compact={compact}
selected={props.selected}
onClick={props.onClick}
/>
);
}

124
src/components/ProgressCard/ProgressCard.view.tsx
View File

@@ -8,93 +8,83 @@ import {
linearProgressClasses
} from "@mui/material";
import { useTheme, alpha } from "@mui/material/styles";
import { ProgressCardProps } from "./ProgressCard.models";
interface ViewProps extends ProgressCardProps {
percentage: number;
formattedProgress: string;
formattedTotal: string;
selected?: boolean;
onClick?: () => void;
}
import { getPercentage, formatCurrency } from "../report.helpers";
import { ProgressCardViewProps } from "./ProgressCard.props";
export default function ProgressCardView({
header,
colorTheme = "info",
percentage,
formattedProgress,
formattedTotal,
compact = false,
title,
settings,
isFetching,
colorScheme,
progressAmount,
totalAmount,
selected,
onClick,
}: ViewProps) {
}: ProgressCardViewProps) {
const theme = useTheme();
const isDark = theme.palette.mode === "dark";
const percentage = getPercentage(progressAmount, totalAmount);
const formattedProgress = formatCurrency(progressAmount);
const formattedTotal = formatCurrency(totalAmount);
return (
<Paper
elevation={compact ? 2 : 4}
elevation={settings.compact ? 2 : 4}
onClick={onClick}
sx={{
width: "100%",
p: compact ? { xs: 2.5, md: 3 } : { xs: 3, md: 4 },
borderRadius: compact ? 3 : 4,
cursor: onClick ? "pointer" : "default",
p: settings.compact ? { xs: 2.5, md: 3 } : { xs: 3, md: 4 },
borderRadius: settings.compact ? 3 : 4,
transform: selected ? "scale(1.02)" : "scale(1)",
transition: "transform 0.2s ease, box-shadow 0.2s ease",
background: (theme) => {
const baseColor = theme.palette[colorTheme]?.main || theme.palette.primary.main;
const lightColor = theme.palette[colorTheme]?.light || theme.palette.primary.light;
return isDark
? `linear-gradient(135deg, ${alpha(baseColor, 0.9)} 0%, ${alpha(baseColor, 0.3)} 100%)`
: `linear-gradient(135deg, ${baseColor} 0%, ${lightColor} 100%)`;
},
color: "#fff",
bgcolor: colorScheme.light,
color: colorScheme.text,
display: "flex",
flexDirection: "column",
alignItems: compact ? "flex-start" : "center",
alignItems: settings.compact ? "flex-start" : "center",
justifyContent: "center",
position: "relative",
overflow: "hidden",
border: selected
? `2px solid #fff`
: isDark ? "1px solid rgba(255,255,255,0.1)" : "none",
boxShadow: (theme) => {
const baseShadow = `0 ${compact ? 6 : 12}px ${compact ? 12 : 24}px -10px ${
isDark
? "rgba(0,0,0,0.5)"
: theme.palette[colorTheme]?.main || theme.palette.primary.main
}`;
return selected
? `${baseShadow}, 0 0 0 2px ${theme.palette.background.paper}, 0 0 0 4px ${theme.palette[colorTheme]?.main || theme.palette.primary.main}`
: baseShadow;
},
opacity: arguments[0].isFetching ? 0.6 : 1,
pointerEvents: arguments[0].isFetching ? "none" : "auto",
border: selected
? `2px solid ${colorScheme.primary}`
: isDark
? "1px solid rgba(255,255,255,0.1)"
: "1px solid rgba(0,0,0,0.06)",
boxShadow: "none",
opacity: isFetching ? 0.6 : 1,
pointerEvents: isFetching ? "none" : "auto",
}}
>
<Typography
variant={compact ? "body2" : "subtitle1"}
fontWeight={700}
sx={{
opacity: 0.95,
mb: compact ? 1.5 : 2,
width: '100%',
overflow: 'hidden',
textOverflow: 'ellipsis',
whiteSpace: 'nowrap',
<Typography
variant={settings.compact ? "body2" : "subtitle1"}
fontWeight={700}
sx={{
opacity: 0.95,
mb: settings.compact ? 1.5 : 2,
width: "100%",
overflow: "hidden",
textOverflow: "ellipsis",
whiteSpace: "nowrap",
letterSpacing: 0.5,
textShadow: isDark ? '0 1px 2px rgba(0,0,0,0.3)' : 'none'
textShadow: isDark ? "0 1px 2px rgba(0,0,0,0.3)" : "none",
}}
>
{header}
{title}
</Typography>
<Box sx={{ mb: compact ? 2 : 3, width: '100%' }}>
<Box sx={{ mb: settings.compact ? 2 : 3, width: "100%" }}>
<Typography
variant={compact ? "h5" : "h3"}
variant={settings.compact ? "h5" : "h3"}
fontWeight={900}
sx={{ mb: 0.5, lineHeight: 1.2, textShadow: isDark ? '0 2px 4px rgba(0,0,0,0.3)' : 'none' }}
sx={{
mb: 0.5,
lineHeight: 1.2,
textShadow: isDark ? "0 2px 4px rgba(0,0,0,0.3)" : "none",
}}
>
{formattedProgress}
</Typography>
@@ -102,38 +92,38 @@ export default function ProgressCardView({
<Divider
sx={{
my: 1,
borderColor: "rgba(255,255,255,0.25)",
borderColor: isDark ? "rgba(255,255,255,0.15)" : "rgba(0,0,0,0.1)",
width: "100%",
}}
/>
<Typography
variant={compact ? "caption" : "body2"}
variant={settings.compact ? "caption" : "body2"}
sx={{
opacity: 0.85,
fontWeight: 500,
display: "block",
color: "rgba(255,255,255,0.9)"
color: alpha(colorScheme.text, 0.85),
}}
>
of {formattedTotal}
</Typography>
</Box>
<Box sx={{ width: "100%", mt: 'auto' }}>
<Box sx={{ width: "100%", mt: "auto" }}>
<LinearProgress
variant="determinate"
value={percentage}
sx={{
height: compact ? 6 : 10,
height: settings.compact ? 6 : 10,
borderRadius: 5,
[`&.${linearProgressClasses.colorPrimary}`]: {
backgroundColor: "rgba(0, 0, 0, 0.25)",
backgroundColor: isDark ? "rgba(255, 255, 255, 0.12)" : "rgba(0, 0, 0, 0.08)",
},
[`& .${linearProgressClasses.bar}`]: {
borderRadius: 5,
backgroundColor: "#fff",
boxShadow: '0 0 8px rgba(255,255,255,0.4)'
backgroundColor: colorScheme.primary,
boxShadow: `0 0 8px ${alpha(colorScheme.primary, 0.4)}`,
},
}}
/>

56
src/components/ProgressCard/TopPayees.adapter.ts
View File

@@ -1,5 +1,8 @@
import { mergeBucketPeriods, periodIdToKey } from "../report.helpers";
import { GroupKey, ReportData } from "../../features/report";
import {
extractFilteredTransactions,
aggregateTransactions,
} from "../report.helpers";
export interface PayeeItem {
name: string;
@@ -12,54 +15,17 @@ export function extractTopPayees(
selectedPeriodId?: string | null,
selectedGroupKey?: GroupKey | null
): { items: PayeeItem[]; total: number } {
const payeeMap = new Map<string, number>();
const txns = extractFilteredTransactions(reportData, selectedPeriodId, selectedGroupKey);
let targetPeriods = [];
if (selectedPeriodId) {
const key = periodIdToKey(selectedPeriodId);
const periods = mergeBucketPeriods(reportData.buckets, key);
const selected = periods.find((p) => p.id === selectedPeriodId);
if (selected) {
targetPeriods.push(selected);
const { items, total } = aggregateTransactions(txns, (txn) => {
if (txn.payee && txn.payee.name) {
return [txn.payee.name];
}
} else {
// If no specific period is selected, aggregate over the "all" period bucket
targetPeriods = mergeBucketPeriods(reportData.buckets, "all");
}
for (const p of targetPeriods) {
let txns = p.metric.transactions || [];
if (selectedGroupKey?.tags && selectedGroupKey.tags.length > 0) {
txns = txns.filter(txn => {
if (!txn.tags) return false;
const txnTags = txn.tags.map(t => typeof t === "string" ? t : t.name);
return selectedGroupKey.tags!.every(selectedTag => txnTags.includes(selectedTag));
});
}
for (const txn of txns) {
if (txn.payee && txn.payee.name) {
const current = payeeMap.get(txn.payee.name) || 0;
payeeMap.set(txn.payee.name, current + txn.amount);
}
}
}
let items: PayeeItem[] = [];
let total = 0;
for (const [name, amount] of payeeMap.entries()) {
items.push({ name, amount });
total += amount;
}
// Sort descending by amount
items.sort((a, b) => b.amount - a.amount);
return [];
});
return {
items: items.slice(0, 4), // Top 4
items,
total,
};
}

48
src/components/ProgressCard/TopPayees.tsx
View File

@@ -1,30 +1,22 @@
import * as React from "react";
import { Box, Paper, Typography } from "@mui/material";
import { ReportData, GroupKey } from "../../features/report";
import ProgressCard from "./ProgressCard";
import ProgressCardView from "./ProgressCard.view";
import { extractTopPayees } from "./TopPayees.adapter";
import { ProgressCardProps } from "./ProgressCard.props";
type Props = {
reportData: ReportData;
flow: "outflows" | "inflows";
header: string;
selectedPeriodId?: string | null;
selectedGroupKey?: GroupKey | null;
setSelectedGroupKey?: (key: GroupKey | null) => void;
compact?: boolean;
isFetching?: boolean;
};
export default function TopPayees(props: ProgressCardProps) {
const {
title,
reportData,
state,
stateSetters,
isFetching,
} = props
const { flow, selectedPeriodId, selectedGroupKey } = state;
const { setSelectedGroupKey } = stateSetters;
export default function TopPayees({
reportData,
flow,
header,
selectedPeriodId,
selectedGroupKey,
setSelectedGroupKey,
compact = true,
isFetching,
}: Props) {
const { items, total } = React.useMemo(() => {
return extractTopPayees(reportData, flow, selectedPeriodId, selectedGroupKey);
}, [reportData, flow, selectedPeriodId, selectedGroupKey]);
@@ -45,7 +37,7 @@ export default function TopPayees({
}}
>
<Typography variant="h6" fontWeight={700} gutterBottom>
{header}
{title}
</Typography>
<Box
@@ -60,17 +52,15 @@ export default function TopPayees({
}}
>
{items.map((item) => {
const isSelected = selectedGroupKey?.payee?.includes(item.name);
const isSelected = !!selectedGroupKey?.payee?.includes(item.name);
return (
<ProgressCard
<ProgressCardView
{...props}
key={item.name}
header={item.name}
title={item.name}
progressAmount={item.amount}
totalAmount={total}
compact={compact}
colorTheme={flow === "outflows" ? "error" : "success"}
selected={isSelected}
isFetching={isFetching}
onClick={() => {
if (setSelectedGroupKey) {
let newKey = selectedGroupKey ? { ...selectedGroupKey } : {};

66
src/components/ProgressCard/TopTags.adapter.ts
View File

@@ -1,11 +1,9 @@
import { ReportData } from "../../features/report";
import { ReportData, GroupKey } from "../../features/report";
import {
mergeBucketPeriods,
periodIdToKey,
extractFilteredTransactions,
aggregateTransactions,
} from "../report.helpers";
import { GroupKey } from "../../features/report";
export interface TagItem {
tag: string;
amount: number;
@@ -17,55 +15,17 @@ export function extractTopTags(
selectedPeriodId?: string | null,
selectedGroupKey?: GroupKey | null
): { items: TagItem[]; total: number } {
const tagMap = new Map<string, number>();
const txns = extractFilteredTransactions(reportData, selectedPeriodId, selectedGroupKey);
let periodKey: ReturnType<typeof periodIdToKey> = "all";
if (selectedPeriodId) {
periodKey = periodIdToKey(selectedPeriodId);
}
const periods = mergeBucketPeriods(reportData.buckets, periodKey);
let period = periods[0];
if (selectedPeriodId) {
period = periods.find(p => p.id === selectedPeriodId) || period;
} else if (periods.length > 0) {
period = periods.reduce((latest, p) =>
new Date(p.start).getTime() > new Date(latest.start).getTime()
? p
: latest
);
}
if (period && period.metric && period.metric.transactions) {
let txns = period.metric.transactions;
if (selectedGroupKey?.payee && selectedGroupKey.payee.length > 0) {
txns = txns.filter(txn =>
txn.payee?.name && selectedGroupKey.payee!.includes(txn.payee.name)
);
const { items, total } = aggregateTransactions(txns, (txn) => {
if (txn.tags && txn.tags.length > 0) {
return txn.tags.map((t) => (typeof t === "string" ? t : t.name));
}
return ["Untagged"];
});
for (const txn of txns) {
if (txn.tags && txn.tags.length > 0) {
for (const tagObj of txn.tags) {
const tagName = typeof tagObj === "string" ? tagObj : tagObj.name;
tagMap.set(tagName, (tagMap.get(tagName) || 0) + txn.amount);
}
} else {
tagMap.set("Untagged", (tagMap.get("Untagged") || 0) + txn.amount);
}
}
}
const arr = Array.from(tagMap.entries()).map(([tag, amount]) => ({
tag,
amount,
}));
arr.sort((a, b) => b.amount - a.amount);
const top = arr.slice(0, 4);
const total = top.reduce((sum, t) => sum + t.amount, 0);
return { items: top, total };
return {
items: items.map((item) => ({ tag: item.name, amount: item.amount })),
total,
};
}

48
src/components/ProgressCard/TopTags.tsx
View File

@@ -1,30 +1,22 @@
import * as React from "react";
import { Box, Paper, Typography } from "@mui/material";
import { ReportData, GroupKey } from "../../features/report";
import ProgressCard from "./ProgressCard";
import ProgressCardView from "./ProgressCard.view";
import { extractTopTags } from "./TopTags.adapter";
import { ProgressCardProps } from "./ProgressCard.props";
type Props = {
reportData: ReportData;
flow: "outflows" | "inflows";
header: string;
selectedPeriodId?: string | null;
selectedGroupKey?: GroupKey | null;
setSelectedGroupKey?: (key: GroupKey | null) => void;
compact?: boolean;
isFetching?: boolean;
};
export default function TopTags(props: ProgressCardProps) {
const {
title,
reportData,
state,
stateSetters,
isFetching,
} = props
const { flow, selectedPeriodId, selectedGroupKey } = state;
const { setSelectedGroupKey } = stateSetters;
export default function TopTags({
reportData,
flow,
header,
selectedPeriodId,
selectedGroupKey,
setSelectedGroupKey,
compact = true,
isFetching,
}: Props) {
const { items, total } = React.useMemo(() => {
return extractTopTags(reportData, flow, selectedPeriodId, selectedGroupKey);
}, [reportData, flow, selectedPeriodId, selectedGroupKey]);
@@ -45,7 +37,7 @@ export default function TopTags({
}}
>
<Typography variant="h6" fontWeight={700} gutterBottom>
{header}
{title}
</Typography>
<Box
@@ -60,17 +52,15 @@ export default function TopTags({
}}
>
{items.map((item) => {
const isSelected = selectedGroupKey?.tags?.includes(item.tag);
const isSelected = !!selectedGroupKey?.tags?.includes(item.tag);
return (
<ProgressCard
<ProgressCardView
{...props}
key={item.tag}
header={item.tag}
title={item.tag}
progressAmount={item.amount}
totalAmount={total}
compact={compact}
colorTheme={flow === "outflows" ? "error" : "success"}
selected={isSelected}
isFetching={isFetching}
onClick={() => {
if (setSelectedGroupKey) {
let newKey = selectedGroupKey ? { ...selectedGroupKey } : {};

4
src/components/ProgressCard/index.ts
View File

@@ -1,2 +1,2 @@
export { default } from "./ProgressCard";
export * from "./ProgressCard.models";
export { default } from "./ProgressCard.view";
export * from "./ProgressCard.props";