Add income toggle feature and update AGENTS.md with date command instructions

Author: MatissJanis

AGENTS.md

@@ -4,11 +4,78 @@ This document explains how to use the tools and utilities available in the Actua
 
 ## Table of Contents
 
+- [CHANGELOG Maintenance](#changelog-maintenance)
 - [File API Service](#file-api-service)
 - [React Hooks](#react-hooks)
 - [Data Transformation Utilities](#data-transformation-utilities)
 - [Type Definitions](#type-definitions)
 
+## CHANGELOG Maintenance
+
+**IMPORTANT**: Agents MUST update `CHANGELOG.md` after making any code changes to the project.
+
+### Update Requirements
+
+1. **When to Update**: Update `CHANGELOG.md` after making any changes to:
+   - Source code files (`.ts`, `.tsx`, `.js`, `.jsx`)
+   - Configuration files (e.g., `package.json`, `vite.config.ts`, `tsconfig.json`)
+   - Documentation files (e.g., `README.md`, `AGENTS.md`)
+   - Test files that represent new functionality
+   - Build or deployment configurations
+
+2. **Format**: Use date-based format with entries grouped by date (YYYY-MM-DD)
+   - Most recent entries appear at the top
+   - Each date section should be formatted as: `## YYYY-MM-DD`
+   - **Getting Today's Date**: Use the CLI command to get the current date in the correct format:
+     ```bash
+     date +%Y-%m-%d
+     ```
+     This will output the date in YYYY-MM-DD format (e.g., `2026-01-08`)
+
+3. **Categories**: Use appropriate categories under each date:
+   - **Added**: New features, components, utilities, or functionality
+   - **Changed**: Changes to existing functionality or behavior
+   - **Fixed**: Bug fixes or corrections
+   - **Removed**: Removed features, code, or functionality
+   - **Security**: Security-related updates
+
+4. **Entry Format**:
+   - Add entries under the current date (YYYY-MM-DD)
+   - If a date section doesn't exist for today, create it at the top of the file
+   - Each entry should be concise but descriptive
+   - Use bullet points for multiple entries under the same category
+   - Example:
+
+     ```
+     ## 2026-01-04
+
+     ### Added
+     - New feature description
+
+     ### Fixed
+     - Bug fix description
+     ```
+
+5. **Placement**: Always add new entries to the top of the file, under the current date. If today's date section already exists, add your entry to the appropriate category within that section.
+
+### Example
+
+```markdown
+## 2026-01-04
+
+### Added
+- New calendar heatmap visualization component
+- Support for currency override in settings
+
+### Changed
+- Updated data transformation logic to handle transfers more efficiently
+
+### Fixed
+- Resolved issue with off-budget transaction filtering
+```
+
+Remember: The CHANGELOG serves as a historical record of all project changes. Keep entries clear and meaningful for future reference.
+
 ## File API Service
 
 The File API service (`src/services/fileApi.ts`) provides functions to load and query an Actual Budget SQLite database from a zip file in the browser.
@@ -357,7 +424,12 @@ console.log(wrappedData.monthlyData);
   - Multiple transfers to the same account are grouped together in both categories and payees
 - **Off-Budget Filtering**: Excludes off-budget transactions by default. Set `includeOffBudget = true` to include them
 - Excludes starting balance transactions (transactions where payee name is "Starting Balance")
-- Handles deleted categories/payees (marks with "deleted: " prefix)
+- **Category Merges**: When a category is deleted and merged into another category, transactions are automatically resolved through the `category_mapping` table:
+  - Transactions from merged categories appear under the merged (target) category name
+  - Handles transitive merges (Category A → B → C resolves to C)
+  - Budget data is also resolved through merge chains and combined for merged categories
+  - Only non-merged deleted categories show the "deleted: " prefix
+- Handles deleted categories/payees (marks with "deleted: " prefix for non-merged deleted categories)
 - Converts amounts from cents to dollars
 - Calculates all derived metrics automatically
 

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to date-based versioning with entries grouped by date.
 
+## 2026-01-08
+
+### Added
+
+- Add toggle to include/exclude income transactions from calculations (default: expenses only)
+- Add CLI command instructions to AGENTS.md for getting today's date when updating CHANGELOG
+
 ## 2026-01-05
 
 ### Added

src/App.tsx

@@ -3,6 +3,7 @@ import { useState } from 'react';
 import styles from './App.module.css';
 import { ConnectionForm } from './components/ConnectionForm';
 import { CurrencySelector } from './components/CurrencySelector';
+import { IncludeIncomeToggle } from './components/IncludeIncomeToggle';
 import { Navigation } from './components/Navigation';
 import { OffBudgetToggle } from './components/OffBudgetToggle';
 import { AllTransfersToggle } from './components/OffBudgetTransfersToggle';
@@ -40,6 +41,7 @@ const PAGES = [
 
 function App() {
   const [currentPage, setCurrentPage] = useState(0);
+  const [includeIncome, setIncludeIncome] = useLocalStorage('includeIncome', false);
   const [includeOffBudget, setIncludeOffBudget] = useLocalStorage('includeOffBudget', false);
   const [includeOnBudgetTransfers, setIncludeOnBudgetTransfers] = useLocalStorage(
     'includeOnBudgetTransfers',
@@ -62,6 +64,18 @@ function App() {
       includeOnBudgetTransfers,
       includeAllTransfers,
       overrideCurrency || undefined,
+      includeIncome,
+    );
+  };
+
+  const handleIncludeIncomeToggle = (value: boolean) => {
+    setIncludeIncome(value);
+    retransformData(
+      includeOffBudget,
+      includeOnBudgetTransfers,
+      includeAllTransfers,
+      overrideCurrency || undefined,
+      value,
     );
   };
 
@@ -72,12 +86,19 @@ function App() {
       includeOnBudgetTransfers,
       includeAllTransfers,
       overrideCurrency || undefined,
+      includeIncome,
     );
   };
 
   const handleOnBudgetTransfersToggle = (value: boolean) => {
     setIncludeOnBudgetTransfers(value);
-    retransformData(includeOffBudget, value, includeAllTransfers, overrideCurrency || undefined);
+    retransformData(
+      includeOffBudget,
+      value,
+      includeAllTransfers,
+      overrideCurrency || undefined,
+      includeIncome,
+    );
   };
 
   const handleAllTransfersToggle = (value: boolean) => {
@@ -92,6 +113,7 @@ function App() {
       effectiveIncludeOnBudgetTransfers, // If includeAllTransfers is true, also enable on-budget transfers
       value,
       overrideCurrency || undefined,
+      includeIncome,
     );
   };
 
@@ -100,14 +122,21 @@ function App() {
     const defaultCurrency = data?.currencySymbol || '$';
     if (currencySymbol === defaultCurrency) {
       setOverrideCurrency(null);
-      retransformData(includeOffBudget, includeOnBudgetTransfers, includeAllTransfers, undefined);
+      retransformData(
+        includeOffBudget,
+        includeOnBudgetTransfers,
+        includeAllTransfers,
+        undefined,
+        includeIncome,
+      );
     } else {
       setOverrideCurrency(currencySymbol);
       retransformData(
         includeOffBudget,
         includeOnBudgetTransfers,
         includeAllTransfers,
         currencySymbol,
+        includeIncome,
       );
     }
   };
@@ -164,6 +193,7 @@ function App() {
     return (
       <div className={styles.app}>
         <SettingsMenu>
+          <IncludeIncomeToggle includeIncome={includeIncome} onToggle={handleIncludeIncomeToggle} />
           <OffBudgetToggle includeOffBudget={includeOffBudget} onToggle={handleOffBudgetToggle} />
           <OnBudgetTransfersToggle
             includeOnBudgetTransfers={includeAllTransfers || includeOnBudgetTransfers}

src/components/IncludeIncomeToggle.module.css

@@ -0,0 +1,65 @@
+.toggle {
+  position: fixed;
+  top: 2rem;
+  right: 2rem;
+  z-index: 1001;
+  background: rgba(0, 0, 0, 0.8);
+  backdrop-filter: blur(10px);
+  padding: 0.75rem 1.25rem;
+  border-radius: 12px;
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  color: white;
+  font-size: 0.9rem;
+  font-weight: 500;
+}
+
+.toggleLabel {
+  user-select: none;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  gap: 0.75rem;
+}
+
+.toggleSwitch {
+  position: relative;
+  width: 44px;
+  height: 24px;
+  background: rgba(255, 255, 255, 0.2);
+  border-radius: 12px;
+  cursor: pointer;
+  transition: background-color 0.3s;
+  flex-shrink: 0;
+  margin-left: auto;
+}
+
+.toggleSwitch.active {
+  background: linear-gradient(90deg, #667eea 0%, #764ba2 100%);
+}
+
+.toggleSlider {
+  position: absolute;
+  top: 2px;
+  left: 2px;
+  width: 20px;
+  height: 20px;
+  background: white;
+  border-radius: 50%;
+  transition: transform 0.3s;
+}
+
+.toggleSwitch.active .toggleSlider {
+  transform: translateX(20px);
+}
+
+.toggleText {
+  font-size: 0.85rem;
+  opacity: 0.9;
+  text-align: left;
+  flex: 1;
+}

src/components/IncludeIncomeToggle.tsx

@@ -0,0 +1,39 @@
+import { motion } from 'framer-motion';
+
+import styles from './IncludeIncomeToggle.module.css';
+
+interface IncludeIncomeToggleProps {
+  includeIncome: boolean;
+  onToggle: (value: boolean) => void;
+}
+
+export function IncludeIncomeToggle({ includeIncome, onToggle }: IncludeIncomeToggleProps) {
+  return (
+    <motion.div
+      className={styles.toggle}
+      initial={{ opacity: 0, y: -20 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.3, delay: 0.1 }}
+    >
+      <div className={styles.toggleLabel}>
+        <span className={styles.toggleText}>Include Income</span>
+        <div
+          className={`${styles.toggleSwitch} ${includeIncome ? styles.active : ''}`}
+          onClick={() => onToggle(!includeIncome)}
+          role="switch"
+          aria-checked={includeIncome}
+          aria-label="Include income transactions"
+          tabIndex={0}
+          onKeyDown={e => {
+            if (e.key === 'Enter' || e.code === 'Space') {
+              e.preventDefault();
+              onToggle(!includeIncome);
+            }
+          }}
+        >
+          <div className={styles.toggleSlider} />
+        </div>
+      </div>
+    </motion.div>
+  );
+}

src/hooks/useActualData.ts

@@ -50,6 +50,7 @@ export function useActualData() {
       budgetData?: Array<{ categoryId: string; month: string; budgetedAmount: number }>,
       groupSortOrders: Map<string, number> = new Map(),
       groupTombstones: Map<string, boolean> = new Map(),
+      includeIncome: boolean = false,
     ) => {
       const wrappedData = transformToWrappedData(
         raw.transactions,
@@ -64,6 +65,7 @@ export function useActualData() {
         budgetData,
         groupSortOrders,
         groupTombstones,
+        includeIncome,
       );
       setData(wrappedData);
     },
@@ -77,6 +79,7 @@ export function useActualData() {
       includeOnBudgetTransfers: boolean = true, // Default to true (on by default)
       includeAllTransfers: boolean = false,
       overrideCurrencySymbol?: string,
+      includeIncome: boolean = false,
     ) => {
       setLoading(true);
       setError(null);
@@ -151,6 +154,7 @@ export function useActualData() {
           fetchedBudgetData.length > 0 ? fetchedBudgetData : undefined,
           fetchedGroupSortOrders,
           fetchedGroupTombstones,
+          includeIncome,
         );
 
         setProgress(100);
@@ -176,6 +180,7 @@ export function useActualData() {
       includeOnBudgetTransfers: boolean = true, // Default to true (on by default)
       includeAllTransfers: boolean = false,
       overrideCurrencySymbol?: string,
+      includeIncome: boolean = false,
     ) => {
       if (!file) {
         throw new Error('No file available');
@@ -186,6 +191,7 @@ export function useActualData() {
         includeOnBudgetTransfers,
         includeAllTransfers,
         overrideCurrencySymbol,
+        includeIncome,
       );
     },
     [file, fetchData],
@@ -197,6 +203,7 @@ export function useActualData() {
       includeOnBudgetTransfers: boolean,
       includeAllTransfers: boolean,
       overrideCurrencySymbol?: string,
+      includeIncome: boolean = false,
     ) => {
       if (rawData) {
         const effectiveCurrency = overrideCurrencySymbol || currencySymbol;
@@ -209,6 +216,7 @@ export function useActualData() {
           budgetData,
           groupSortOrders,
           groupTombstones,
+          includeIncome,
         );
       }
     },