Skip to content

A local-first personal finance app

[AI] feat(budget analysis report): allow selecting future months in date range (#8722)

tabedzki30e671b3ec6e
diff --git a/packages/desktop-client/src/components/reports/reports/BudgetAnalysis.tsx b/packages/desktop-client/src/components/reports/reports/BudgetAnalysis.tsx
index 6fad3267e6..bc4d095635 100644
--- a/packages/desktop-client/src/components/reports/reports/BudgetAnalysis.tsx
+++ b/packages/desktop-client/src/components/reports/reports/BudgetAnalysis.tsx
@@ -33,7 +33,10 @@ import { Header } from '#components/reports/Header';
import { LoadingIndicator } from '#components/reports/LoadingIndicator';
import { calculateTimeRange } from '#components/reports/reportRanges';
import { buildBudgetAnalysisCsv } from '#components/reports/spreadsheets/budget-analysis-export';
-import { createBudgetAnalysisSpreadsheet } from '#components/reports/spreadsheets/budget-analysis-spreadsheet';
+import {
+ createBudgetAnalysisSpreadsheet,
+ getLastSelectableMonth,
+} from '#components/reports/spreadsheets/budget-analysis-spreadsheet';
import { useReport } from '#components/reports/useReport';
import { fromDateRepr } from '#components/reports/util';
import { useDashboardWidget } from '#hooks/useDashboardWidget';
@@ -223,8 +226,13 @@ function BudgetAnalysisInternal({ widget }: BudgetAnalysisInternalProps) {
earliestMonth = yearAgo;
}
+ // Extend the selectable range to December of next year so users can
+ // plan ahead (e.g. June 2026 → December 2027), without hiding
+ // transactions dated beyond that.
+ const lastMonth = getLastSelectableMonth(currentMonth, latestMonth);
+
const allMonthsData = monthUtils
- .rangeInclusive(earliestMonth, latestMonth)
+ .rangeInclusive(earliestMonth, lastMonth)
.map(month => ({
name: month,
pretty: monthUtils.format(month, 'MMMM, yyyy', locale),
diff --git a/packages/desktop-client/src/components/reports/spreadsheets/budget-analysis-spreadsheet.test.ts b/packages/desktop-client/src/components/reports/spreadsheets/budget-analysis-spreadsheet.test.ts
index edb218158b..613f00a128 100644
--- a/packages/desktop-client/src/components/reports/spreadsheets/budget-analysis-spreadsheet.test.ts
+++ b/packages/desktop-client/src/components/reports/spreadsheets/budget-analysis-spreadsheet.test.ts
@@ -1,6 +1,13 @@
+import { rangeInclusive } from '@actual-app/core/shared/months';
import type { CategoryEntity } from '@actual-app/core/types/models';
-import { isBaseCategory } from './budget-analysis-spreadsheet';
+import {
+ getLastSelectableMonth,
+ getNextRunningBalance,
+ isBaseCategory,
+ summarizeMonthCategories,
+} from './budget-analysis-spreadsheet';
+import type { BudgetMonthCell } from './budgetMonthCell';
const makeCategory = (
overrides: Partial<CategoryEntity> & Pick<CategoryEntity, 'id' | 'name'>,
@@ -74,4 +81,215 @@ describe('createBudgetAnalysisSpreadsheet', () => {
expect(result).toContain(hiddenExpense);
});
});
+
+ describe('getLastSelectableMonth', () => {
+ it('extends the range to December of next year', () => {
+ expect(getLastSelectableMonth('2026-06', '2026-06')).toBe('2027-12');
+ });
+
+ it('ends in December regardless of the current month', () => {
+ for (const month of ['2024-01', '2024-06', '2024-12']) {
+ expect(getLastSelectableMonth(month, month)).toBe('2025-12');
+ }
+ });
+
+ it('keeps a later transaction month selectable', () => {
+ // A transaction dated past December of next year must not be cut off.
+ expect(getLastSelectableMonth('2026-08', '2028-03')).toBe('2028-03');
+ });
+
+ it('prefers December of next year when the latest transaction is earlier', () => {
+ expect(getLastSelectableMonth('2026-08', '2026-11')).toBe('2027-12');
+ });
+
+ it('keeps the boundary month itself', () => {
+ expect(getLastSelectableMonth('2026-08', '2027-12')).toBe('2027-12');
+ });
+
+ it('produces a range that spans from the earliest month to the endpoint', () => {
+ const range = rangeInclusive(
+ '2026-06',
+ getLastSelectableMonth('2026-06', '2026-06'),
+ );
+
+ expect(range[0]).toBe('2026-06');
+ expect(range[range.length - 1]).toBe('2027-12');
+ });
+
+ it('lists future months before the current month once reversed', () => {
+ const last = getLastSelectableMonth('2026-06', '2026-06');
+ const allMonths = rangeInclusive('2026-06', last).reverse();
+
+ expect(allMonths[0]).toBe(last);
+ expect(allMonths[allMonths.length - 1]).toBe('2026-06');
+ });
+ });
+
+ describe('summarizeMonthCategories', () => {
+ const cells = (
+ values: Record<string, number | boolean>,
+ ): BudgetMonthCell[] =>
+ Object.entries(values).map(([name, value]) => ({
+ name: `budget202601!${name}`,
+ value,
+ })) as BudgetMonthCell[];
+
+ it('reports no budget data when every cell is empty', () => {
+ const result = summarizeMonthCategories([], [visibleExpense]);
+
+ expect(result).toEqual({
+ budgeted: 0,
+ spent: 0,
+ carryoverToNextMonth: 0,
+ overspendingThisMonth: 0,
+ hasBudgetData: false,
+ });
+ });
+
+ it('reports no budget data for a never-budgeted month', () => {
+ // `envelope-budget-month` emits a cell for every category in every
+ // month, so an untouched future month arrives as present-but-zero
+ // cells rather than as missing ones. Presence alone cannot distinguish
+ // it from a real month.
+ const result = summarizeMonthCategories(
+ cells({
+ 'budget-c1': 0,
+ 'sum-amount-c1': 0,
+ 'leftover-c1': 0,
+ 'carryover-c1': false,
+ }),
+ [visibleExpense],
+ );
+
+ expect(result.hasBudgetData).toBe(false);
+ });
+
+ it('carries a positive balance to the next month', () => {
+ const result = summarizeMonthCategories(
+ cells({
+ 'budget-c1': 10000,
+ 'sum-amount-c1': -4000,
+ 'leftover-c1': 6000,
+ 'carryover-c1': false,
+ }),
+ [visibleExpense],
+ );
+
+ expect(result.carryoverToNextMonth).toBe(6000);
+ expect(result.overspendingThisMonth).toBe(0);
+ expect(result.hasBudgetData).toBe(true);
+ });
+
+ it('treats an overspend without carryover as an overspending adjustment', () => {
+ const result = summarizeMonthCategories(
+ cells({
+ 'budget-c1': 0,
+ 'sum-amount-c1': -10000,
+ 'leftover-c1': -10000,
+ 'carryover-c1': false,
+ }),
+ [visibleExpense],
+ );
+
+ expect(result.carryoverToNextMonth).toBe(0);
+ expect(result.overspendingThisMonth).toBe(-10000);
+ expect(result.hasBudgetData).toBe(true);
+ });
+
+ it('carries a negative balance forward when carryover is enabled', () => {
+ const result = summarizeMonthCategories(
+ cells({
+ 'budget-c1': 0,
+ 'sum-amount-c1': -10000,
+ 'leftover-c1': -10000,
+ 'carryover-c1': true,
+ }),
+ [visibleExpense],
+ );
+
+ expect(result.carryoverToNextMonth).toBe(-10000);
+ expect(result.overspendingThisMonth).toBe(0);
+ });
+
+ it('only counts the categories it is given', () => {
+ const result = summarizeMonthCategories(
+ cells({
+ 'budget-c1': 10000,
+ 'leftover-c1': 10000,
+ 'budget-c2': 5000,
+ 'leftover-c2': 5000,
+ }),
+ [visibleExpense],
+ );
+
+ expect(result.budgeted).toBe(10000);
+ expect(result.carryoverToNextMonth).toBe(10000);
+ });
+ });
+
+ describe('getNextRunningBalance', () => {
+ it('hands off only what carries over when the month has data', () => {
+ expect(
+ getNextRunningBalance({
+ hasBudgetData: true,
+ carryoverToNextMonth: 6000,
+ runningBalance: 20000,
+ }),
+ ).toBe(6000);
+ });
+
+ it('resets a non-carryover overspend instead of dragging it forward', () => {
+ // The overspend surfaces as next month's overspending adjustment, so it
+ // must not also reduce the running balance.
+ expect(
+ getNextRunningBalance({
+ hasBudgetData: true,
+ carryoverToNextMonth: 0,
+ runningBalance: 20000,
+ }),
+ ).toBe(0);
+ });
+
+ it('passes the running balance through months with no budget data', () => {
+ expect(
+ getNextRunningBalance({
+ hasBudgetData: false,
+ carryoverToNextMonth: 0,
+ runningBalance: 20000,
+ }),
+ ).toBe(20000);
+ });
+
+ it('preserves a balance across a run of empty future months', () => {
+ let runningBalance = 15000;
+ for (let i = 0; i < 6; i++) {
+ runningBalance = getNextRunningBalance({
+ hasBudgetData: false,
+ carryoverToNextMonth: 0,
+ runningBalance,
+ });
+ }
+
+ expect(runningBalance).toBe(15000);
+ });
+
+ it('does not carry a non-carryover overspend into later empty months', () => {
+ // Overspend of -10000 in a category without carryover enabled.
+ let runningBalance = getNextRunningBalance({
+ hasBudgetData: true,
+ carryoverToNextMonth: 0,
+ runningBalance: 0,
+ });
+
+ for (let i = 0; i < 3; i++) {
+ runningBalance = getNextRunningBalance({
+ hasBudgetData: false,
+ carryoverToNextMonth: 0,
+ runningBalance,
+ });
+ }
+
+ expect(runningBalance).toBe(0);
+ });
+ });
});
diff --git a/packages/desktop-client/src/components/reports/spreadsheets/budget-analysis-spreadsheet.ts b/packages/desktop-client/src/components/reports/spreadsheets/budget-analysis-spreadsheet.ts
index 7541cda30b..a45d721de6 100644
--- a/packages/desktop-client/src/components/reports/spreadsheets/budget-analysis-spreadsheet.ts
+++ b/packages/desktop-client/src/components/reports/spreadsheets/budget-analysis-spreadsheet.ts
@@ -43,6 +43,134 @@ export function isBaseCategory(
return !cat.is_income && (showHiddenCategories || !cat.hidden);
}
+/**
+ * Last month the date pickers offer.
+ *
+ * The range runs through December of next year so the report can be used for
+ * planning ahead, but it never cuts off existing data: if a transaction is
+ * dated even further out, that month stays selectable.
+ */
+export function getLastSelectableMonth(
+ currentMonth: string,
+ latestMonth: string,
+): string {
+ const futureMonth = `${Number(currentMonth.slice(0, 4)) + 1}-12`;
+ return latestMonth > futureMonth ? latestMonth : futureMonth;
+}
+
+export type MonthCategoryTotals = {
+ budgeted: number;
+ spent: number;
+ /**
+ * Sum of category balances that roll into the next month: positive balances
+ * always roll over, negative ones only when the category has carryover
+ * ("rollover overspending") enabled.
+ */
+ carryoverToNextMonth: number;
+ /**
+ * Sum of negative balances for categories without carryover enabled. These
+ * are zeroed out at the month boundary and surface as next month's
+ * overspending adjustment instead of reducing the running balance.
+ */
+ overspendingThisMonth: number;
+ /**
+ * Whether the month returned any budget data at all. Months in the future
+ * that have never been budgeted come back with every cell empty; there is
+ * nothing to carry over from them, so the running balance must pass through
+ * untouched rather than being reset to zero.
+ */
+ hasBudgetData: boolean;
+};
+
+/**
+ * Reduce a month's raw budget cells down to the totals the report needs.
+ */
+export function summarizeMonthCategories(
+ monthData: BudgetMonthCell[],
+ categoriesToInclude: CategoryEntity[],
+): MonthCategoryTotals {
+ let budgeted = 0;
+ let spent = 0;
+ let carryoverToNextMonth = 0;
+ let overspendingThisMonth = 0;
+ let hasBudgetData = false;
+
+ for (const cat of categoriesToInclude) {
+ // Find the budget, spent, balance, and carryover flag for this category
+ const budgetCell = monthData.find((cell: BudgetMonthCell) =>
+ cell.name.endsWith(`budget-${cat.id}`),
+ );
+ const spentCell = monthData.find((cell: BudgetMonthCell) =>
+ cell.name.endsWith(`sum-amount-${cat.id}`),
+ );
+ const balanceCell = monthData.find((cell: BudgetMonthCell) =>
+ cell.name.endsWith(`leftover-${cat.id}`),
+ );
+ const carryoverCell = monthData.find((cell: BudgetMonthCell) =>
+ cell.name.endsWith(`carryover-${cat.id}`),
+ );
+
+ const catBudgeted = (budgetCell?.value as number) || 0;
+ const catSpent = (spentCell?.value as number) || 0;
+ const catBalance = (balanceCell?.value as number) || 0;
+ const hasCarryover = Boolean(carryoverCell?.value);
+
+ // Detect by value, not by cell presence: `envelope-budget-month` builds
+ // its response from the category list, so it emits a cell for every
+ // category in every month and fills missing sheet values with 0. Every
+ // month therefore has all its cells, and presence tells us nothing.
+ // A zero here is unambiguous: `leftover` already folds in the previous
+ // month's balance, so a month with a real balance carrying in cannot
+ // report zero across all three.
+ if (catBudgeted !== 0 || catSpent !== 0 || catBalance !== 0) {
+ hasBudgetData = true;
+ }
+
+ budgeted += catBudgeted;
+ spent += catSpent;
+
+ // Add to next month's carryover if:
+ // - Balance is positive (always carries over), OR
+ // - Balance is negative AND carryover is enabled
+ if (catBalance > 0 || (catBalance < 0 && hasCarryover)) {
+ carryoverToNextMonth += catBalance;
+ } else if (catBalance < 0 && !hasCarryover) {
+ // If balance is negative and carryover is NOT enabled,
+ // this will be zeroed out and becomes next month's overspending adjustment
+ overspendingThisMonth += catBalance; // Keep as negative
+ }
+ }
+
+ return {
+ budgeted,
+ spent,
+ carryoverToNextMonth,
+ overspendingThisMonth,
+ hasBudgetData,
+ };
+}
+
+/**
+ * The balance that seeds the following month.
+ *
+ * Months with budget data hand off only what actually carries over, so
+ * overspending in a category without carryover enabled is reset rather than
+ * dragged forward. Months with no data at all (typically future months that
+ * have never been budgeted) have nothing to carry over and must leave the
+ * running balance untouched.
+ */
+export function getNextRunningBalance({
+ hasBudgetData,
+ carryoverToNextMonth,
+ runningBalance,
+}: {
+ hasBudgetData: boolean;
+ carryoverToNextMonth: number;
+ runningBalance: number;
+}): number {
+ return hasBudgetData ? carryoverToNextMonth : runningBalance;
+}
+
export function createBudgetAnalysisSpreadsheet({
conditions = [],
conditionsOp = 'and',
@@ -174,7 +302,6 @@ export function createBudgetAnalysisSpreadsheet({
// Track running balance that respects carryover flags
// Get the balance from the month before the start period to initialize properly
- let runningBalance = 0;
const monthBeforeStart = monthUtils.subMonths(
monthUtils.getMonth(startDate),
1,
@@ -184,22 +311,10 @@ export function createBudgetAnalysisSpreadsheet({
});
// Calculate the carryover from the previous month
- for (const cat of categoriesToInclude) {
- const balanceCell = prevMonthData.find((cell: BudgetMonthCell) =>
- cell.name.endsWith(`leftover-${cat.id}`),
- );
- const carryoverCell = prevMonthData.find((cell: BudgetMonthCell) =>
- cell.name.endsWith(`carryover-${cat.id}`),
- );
-
- const catBalance = (balanceCell?.value as number) || 0;
- const hasCarryover = Boolean(carryoverCell?.value);
-
- // Add to running balance if it would carry over
- if (catBalance > 0 || (catBalance < 0 && hasCarryover)) {
- runningBalance += catBalance;
- }
- }
+ let runningBalance = summarizeMonthCategories(
+ prevMonthData,
+ categoriesToInclude,
+ ).carryoverToNextMonth;
// Track totals across all months
let totalBudgeted = 0;
@@ -215,48 +330,13 @@ export function createBudgetAnalysisSpreadsheet({
// This uses the same calculations as the budget page
const monthData = await send('envelope-budget-month', { month });
- let budgeted = 0;
- let spent = 0;
- let overspendingThisMonth = 0;
-
- // Track what will carry over to next month
- let carryoverToNextMonth = 0;
-
- // Sum up values for categories we're interested in
- for (const cat of categoriesToInclude) {
- // Find the budget, spent, balance, and carryover flag for this category
- const budgetCell = monthData.find((cell: BudgetMonthCell) =>
- cell.name.endsWith(`budget-${cat.id}`),
- );
- const spentCell = monthData.find((cell: BudgetMonthCell) =>
- cell.name.endsWith(`sum-amount-${cat.id}`),
- );
- const balanceCell = monthData.find((cell: BudgetMonthCell) =>
- cell.name.endsWith(`leftover-${cat.id}`),
- );
- const carryoverCell = monthData.find((cell: BudgetMonthCell) =>
- cell.name.endsWith(`carryover-${cat.id}`),
- );
-
- const catBudgeted = (budgetCell?.value as number) || 0;
- const catSpent = (spentCell?.value as number) || 0;
- const catBalance = (balanceCell?.value as number) || 0;
- const hasCarryover = Boolean(carryoverCell?.value);
-
- budgeted += catBudgeted;
- spent += catSpent;
-
- // Add to next month's carryover if:
- // - Balance is positive (always carries over), OR
- // - Balance is negative AND carryover is enabled
- if (catBalance > 0 || (catBalance < 0 && hasCarryover)) {
- carryoverToNextMonth += catBalance;
- } else if (catBalance < 0 && !hasCarryover) {
- // If balance is negative and carryover is NOT enabled,
- // this will be zeroed out and becomes next month's overspending adjustment
- overspendingThisMonth += catBalance; // Keep as negative
- }
- }
+ const {
+ budgeted,
+ spent,
+ carryoverToNextMonth,
+ overspendingThisMonth,
+ hasBudgetData,
+ } = summarizeMonthCategories(monthData, categoriesToInclude);
// Apply overspending adjustment from previous month (negative value)
const overspendingAdjustment = overspendingFromPrevMonth;
@@ -272,13 +352,16 @@ export function createBudgetAnalysisSpreadsheet({
intervalData.push({
date: month,
budgeted,
- spent, // Display as positive
+ spent,
balance: monthBalance,
- overspendingAdjustment: Math.abs(overspendingAdjustment), // Display as positive
+ overspendingAdjustment: Math.abs(overspendingAdjustment),
});
- // Update running balance for next month
- runningBalance = carryoverToNextMonth;
+ runningBalance = getNextRunningBalance({
+ hasBudgetData,
+ carryoverToNextMonth,
+ runningBalance,
+ });
// Save this month's overspending to apply in next month
overspendingFromPrevMonth = overspendingThisMonth;
}
diff --git a/upcoming-release-notes/ai-feat-budget-analysis-report-allow-selecting-future-months-in-date-range.md b/upcoming-release-notes/ai-feat-budget-analysis-report-allow-selecting-future-months-in-date-range.md
new file mode 100644
index 0000000000..8d86c89cee
--- /dev/null
+++ b/upcoming-release-notes/ai-feat-budget-analysis-report-allow-selecting-future-months-in-date-range.md
@@ -0,0 +1,6 @@
+---
+category: Enhancements
+authors: [tabedzki]
+---
+
+Allow selecting future months in the Budget Analysis report date range, so you can plan ahead.