---
phase: 02-dashboard-charts-and-layout
plan: 02
type: execute
wave: 1
depends_on: []
files_modified:
  - src/components/dashboard/charts/ExpenseDonutChart.tsx
  - src/components/dashboard/charts/IncomeBarChart.tsx
  - src/components/dashboard/charts/SpendBarChart.tsx
autonomous: true
requirements: [UI-DONUT-01, UI-BAR-01, UI-HBAR-01]

must_haves:
  truths:
    - "Donut chart renders expense data by category type with center total label and active sector hover expansion"
    - "Donut chart shows custom legend with category colors and formatted amounts"
    - "Donut chart shows neutral empty ring with $0 center when all actuals are zero"
    - "Vertical bar chart renders grouped budgeted vs actual bars for income with muted/vivid color distinction"
    - "Horizontal bar chart renders budget vs actual spending by category type with over-budget red accent"
    - "All three charts consume CSS variable tokens via ChartConfig -- no hardcoded hex values"
    - "All three charts handle empty data by rendering ChartEmptyState placeholder"
  artifacts:
    - path: "src/components/dashboard/charts/ExpenseDonutChart.tsx"
      provides: "Donut pie chart for expense breakdown"
      exports: ["ExpenseDonutChart"]
      min_lines: 60
    - path: "src/components/dashboard/charts/IncomeBarChart.tsx"
      provides: "Vertical grouped bar chart for income budget vs actual"
      exports: ["IncomeBarChart"]
      min_lines: 40
    - path: "src/components/dashboard/charts/SpendBarChart.tsx"
      provides: "Horizontal bar chart for category spend budget vs actual"
      exports: ["SpendBarChart"]
      min_lines: 40
  key_links:
    - from: "src/components/dashboard/charts/ExpenseDonutChart.tsx"
      to: "@/components/ui/chart"
      via: "ChartContainer + ChartConfig"
      pattern: "ChartContainer.*config"
    - from: "src/components/dashboard/charts/IncomeBarChart.tsx"
      to: "@/components/ui/chart"
      via: "ChartContainer + ChartConfig"
      pattern: "ChartContainer.*config"
    - from: "src/components/dashboard/charts/SpendBarChart.tsx"
      to: "@/components/ui/chart"
      via: "ChartContainer + ChartConfig"
      pattern: "ChartContainer.*config"
    - from: "src/components/dashboard/charts/ExpenseDonutChart.tsx"
      to: "@/lib/format"
      via: "formatCurrency for center label and legend"
      pattern: "formatCurrency"
---

<objective>
Build the three chart components -- ExpenseDonutChart, IncomeBarChart, and SpendBarChart -- as isolated presentational components.

Purpose: These are the core visual deliverables of Phase 2. Each chart is self-contained, receives pre-computed data as props, uses ChartContainer/ChartConfig from shadcn for CSS-variable-driven color theming, and handles its own empty state. Plan 03 will wire them into the dashboard layout.

Output: Three chart component files in `src/components/dashboard/charts/`.
</objective>

<execution_context>
@/home/jlmak/.claude/get-shit-done/workflows/execute-plan.md
@/home/jlmak/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/02-dashboard-charts-and-layout/02-CONTEXT.md
@.planning/phases/02-dashboard-charts-and-layout/02-RESEARCH.md

<interfaces>
<!-- Key types, chart patterns, and color tokens the executor needs. -->

From src/components/ui/chart.tsx:
```typescript
export type ChartConfig = {
  [k in string]: { label?: React.ReactNode; icon?: React.ComponentType } &
    ({ color?: string; theme?: never } | { color?: never; theme: Record<"light" | "dark", string> })
}
export function ChartContainer({ config, className, children, ...props }: { config: ChartConfig; children: ReactNode } & ComponentProps<"div">): JSX.Element
export const ChartTooltip: typeof RechartsPrimitive.Tooltip
export function ChartTooltipContent({ nameKey, ...props }: TooltipProps & { nameKey?: string }): JSX.Element
export const ChartLegend: typeof RechartsPrimitive.Legend
export function ChartLegendContent({ nameKey, payload, verticalAlign, ...props }: LegendProps & { nameKey?: string }): JSX.Element
```

From src/lib/types.ts:
```typescript
export type CategoryType = "income" | "bill" | "variable_expense" | "debt" | "saving" | "investment"
```

From src/lib/palette.ts:
```typescript
export const categoryColors: Record<CategoryType, string>
// Values: "var(--color-income)", "var(--color-bill)", etc.
```

From src/lib/format.ts:
```typescript
export function formatCurrency(amount: number, currency?: string, locale?: string): string
```

CSS tokens available in index.css @theme:
```css
--color-income-fill: oklch(0.68 0.19 155);
--color-bill-fill: oklch(0.65 0.19 25);
--color-variable-expense-fill: oklch(0.70 0.18 50);
--color-debt-fill: oklch(0.60 0.20 355);
--color-saving-fill: oklch(0.68 0.18 220);
--color-investment-fill: oklch(0.65 0.18 285);
--color-over-budget: oklch(0.55 0.20 25);
--color-on-budget: oklch(0.50 0.17 155);
--color-budget-bar-bg: oklch(0.92 0.01 260);
```

From src/pages/DashboardPage.tsx (existing data patterns):
```typescript
const EXPENSE_TYPES: CategoryType[] = ["bill", "variable_expense", "debt", "saving", "investment"]
// pieData shape: { name: string, value: number, type: CategoryType }[]
// totalExpenses: number
```
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create ExpenseDonutChart component</name>
  <files>src/components/dashboard/charts/ExpenseDonutChart.tsx</files>
  <action>
Create `src/components/dashboard/charts/ExpenseDonutChart.tsx`. If the `charts/` directory was not created by Plan 01 yet (parallel wave), create it.

**Props interface:**
```typescript
interface ExpenseDonutChartProps {
  data: Array<{ type: string; value: number; label: string }>
  totalExpenses: number
  currency: string
  emptyMessage: string  // i18n-driven, passed from parent
}
```

**ChartConfig:** Build config from data entries, mapping each `type` to its fill color:
```typescript
const chartConfig = useMemo(() => {
  const config: ChartConfig = {}
  for (const entry of data) {
    config[entry.type] = {
      label: entry.label,
      color: `var(--color-${entry.type}-fill)`,
    }
  }
  return config
}, [data])
```

**Empty/Zero states:**
- If `data.length === 0` and `totalExpenses === 0`: check if this is a "no items at all" case. Render `ChartEmptyState` with `emptyMessage` prop. Import from `./ChartEmptyState`.
- If data is empty but there may be items with zero amounts: the parent will pass an `allZero` indicator (or the totalExpenses will be 0). When totalExpenses is 0 but the component is rendered, show a single neutral sector (full ring) in `var(--color-muted)` with `$0` center label. Use a synthetic data point: `[{ type: "empty", value: 1, label: "" }]` with `fill="var(--color-muted)"`.

**Donut rendering:**
- Wrap in `ChartContainer` with `config={chartConfig}` and `className="min-h-[250px] w-full"`
- Use `PieChart` > `Pie` with `dataKey="value"` `nameKey="type"` `innerRadius={60}` `outerRadius={85}` `cx="50%"` `cy="50%"`
- Active sector hover: maintain `activeIndex` state with `useState(-1)`. Set `activeShape` to a render function that draws a `Sector` with `outerRadius + 8` (expanded). Wire `onMouseEnter={(_, index) => setActiveIndex(index)}` and `onMouseLeave={() => setActiveIndex(-1)}` per Research Pattern 2.
- Cell coloring: map data entries to `<Cell key={entry.type} fill={`var(--color-${entry.type}-fill)`} />`
- Center label: use `<Label>` inside `<Pie>` with content function that checks `viewBox && "cx" in viewBox && "cy" in viewBox` (per Pitfall 4), then renders `<text>` with `textAnchor="middle"` `dominantBaseline="middle"` and a `<tspan className="fill-foreground text-xl font-bold">` showing `formatCurrency(totalExpenses, currency)`. Center label shows total expense amount only (per user decision -- no label text).

**Custom legend:** Below the chart, render a `<ul>` with legend items (following the existing pattern from DashboardPage.tsx lines 168-182). Each item shows a color dot (using `var(--color-${entry.type}-fill)` as background), the label text, and the formatted amount right-aligned. Use the shadcn `ChartLegend` + `ChartLegendContent` if it works well with the pie chart nameKey, otherwise use the manual ul-based legend matching the existing codebase pattern. Place legend below the donut (per research recommendation for tight 3-column layout).

**Tooltip:** Use `<ChartTooltip content={<ChartTooltipContent nameKey="type" formatter={(value) => formatCurrency(Number(value), currency)} />} />` for formatted currency tooltips.

**Import order:** Follow conventions -- React first, then recharts, then @/ imports.
  </action>
  <verify>
    <automated>cd /home/jlmak/Projects/jlmak/SimpleFinanceDash && bun run build</automated>
  </verify>
  <done>ExpenseDonutChart renders a donut with center total label, active sector expansion on hover, custom legend below, CSS variable fills, and handles empty/zero-amount states. Build passes.</done>
</task>

<task type="auto">
  <name>Task 2: Create IncomeBarChart and SpendBarChart components</name>
  <files>src/components/dashboard/charts/IncomeBarChart.tsx, src/components/dashboard/charts/SpendBarChart.tsx</files>
  <action>
**IncomeBarChart** (`src/components/dashboard/charts/IncomeBarChart.tsx`):

Props interface:
```typescript
interface IncomeBarChartProps {
  data: Array<{ label: string; budgeted: number; actual: number }>
  currency: string
  emptyMessage: string
}
```

- If `data.length === 0`, render `ChartEmptyState` with `emptyMessage`
- ChartConfig: `{ budgeted: { label: "Budgeted" (from props or hardcode), color: "var(--color-budget-bar-bg)" }, actual: { label: "Actual", color: "var(--color-income-fill)" } } satisfies ChartConfig`
- Wrap in `ChartContainer` with `className="min-h-[250px] w-full"`
- Use `BarChart` (vertical, which is the default -- no `layout` prop needed)
- `<CartesianGrid vertical={false} />` for horizontal grid lines only
- `<XAxis dataKey="label" tick={{ fontSize: 12 }} />` for category labels
- `<YAxis tick={{ fontSize: 12 }} />` for amount axis
- Two `<Bar>` components (NOT stacked -- no `stackId`): `<Bar dataKey="budgeted" fill="var(--color-budgeted)" radius={[4, 4, 0, 0]} />` and `<Bar dataKey="actual" radius={[4, 4, 0, 0]}>` with `<Cell>` per entry: if `entry.actual > entry.budgeted`, use `fill="var(--color-over-budget)"`, otherwise use `fill="var(--color-income-fill)"` (per user decision: actual bars vivid, over-budget bars red)
- Tooltip: `<ChartTooltip content={<ChartTooltipContent formatter={(value) => formatCurrency(Number(value), currency)} />} />`
- ChartLegend: `<ChartLegend content={<ChartLegendContent />} />` for budgeted/actual legend

**SpendBarChart** (`src/components/dashboard/charts/SpendBarChart.tsx`):

Props interface:
```typescript
interface SpendBarChartProps {
  data: Array<{ type: string; label: string; budgeted: number; actual: number }>
  currency: string
  emptyMessage: string
}
```

- If `data.length === 0`, render `ChartEmptyState` with `emptyMessage`
- ChartConfig: `{ budgeted: { label: "Budgeted", color: "var(--color-budget-bar-bg)" }, actual: { label: "Actual", color: "var(--color-muted-foreground)" } } satisfies ChartConfig` (base color for actual; overridden per-cell)
- Wrap in `ChartContainer` with `className="min-h-[250px] w-full"`
- **CRITICAL: Horizontal bars via `layout="vertical"`** on `<BarChart>` (per Research Pattern 3 and Pitfall 2)
- `<CartesianGrid horizontal={false} />` -- only vertical grid lines for horizontal bar layout
- `<XAxis type="number" hide />` (number axis, hidden)
- `<YAxis type="category" dataKey="label" width={120} tick={{ fontSize: 12 }} />` (category labels on Y axis)
- Two `<Bar>` components (NOT stacked): `<Bar dataKey="budgeted" fill="var(--color-budgeted)" radius={4} />` and `<Bar dataKey="actual" radius={4}>` with `<Cell>` per entry: if `entry.actual > entry.budgeted`, fill is `"var(--color-over-budget)"` (red accent per user decision), otherwise fill is `var(--color-${entry.type}-fill)` (vivid category color)
- Tooltip and Legend same pattern as IncomeBarChart
- The actual bar naturally extending past the budgeted bar IS the over-budget visual indicator (per Research Pattern 5)

**Both components:** Follow project import conventions. Use named exports. Accept `t()` translations via props or use i18n keys in config labels.
  </action>
  <verify>
    <automated>cd /home/jlmak/Projects/jlmak/SimpleFinanceDash && bun run build</automated>
  </verify>
  <done>IncomeBarChart renders grouped vertical bars (budgeted muted, actual vivid) with over-budget red fill. SpendBarChart renders horizontal bars via layout="vertical" with per-cell over-budget coloring. Both handle empty data with ChartEmptyState. Build passes.</done>
</task>

</tasks>

<verification>
- `bun run build` passes with no type errors
- All three chart files exist in `src/components/dashboard/charts/`
- Each chart uses `ChartContainer` as its outer wrapper (not raw `ResponsiveContainer`)
- No hardcoded hex color values -- all colors via CSS variables
- Each chart handles empty data gracefully (ChartEmptyState or neutral ring)
- ExpenseDonutChart has center label with formatted currency, active hover, and legend
- IncomeBarChart has two grouped (not stacked) bars
- SpendBarChart uses `layout="vertical"` with swapped axis types
</verification>

<success_criteria>
- ExpenseDonutChart renders donut with center total, hover expansion, and custom legend using CSS variable fills
- IncomeBarChart renders grouped vertical bars comparing budgeted (muted) vs actual (vivid) for income
- SpendBarChart renders horizontal bars comparing budget vs actual by category type with over-budget red accent
- All charts handle zero-data and empty states
- `bun run build` passes
</success_criteria>

<output>
After completion, create `.planning/phases/02-dashboard-charts-and-layout/02-02-SUMMARY.md`
</output>