Skip to content

A local-first personal finance app

Feat/add-budget-analysis-report (#6137)

tabedzkie4903ca6e30a
diff --git a/packages/desktop-client/e2e/reports.test.ts-snapshots/Reports-loads-net-worth-graph-and-checks-visuals-1-chromium-linux.png b/packages/desktop-client/e2e/reports.test.ts-snapshots/Reports-loads-net-worth-graph-and-checks-visuals-1-chromium-linux.png
index 464c35e67f..0429001505 100644
Binary files a/packages/desktop-client/e2e/reports.test.ts-snapshots/Reports-loads-net-worth-graph-and-checks-visuals-1-chromium-linux.png and b/packages/desktop-client/e2e/reports.test.ts-snapshots/Reports-loads-net-worth-graph-and-checks-visuals-1-chromium-linux.png differ
diff --git a/packages/desktop-client/e2e/reports.test.ts-snapshots/Reports-loads-net-worth-graph-and-checks-visuals-2-chromium-linux.png b/packages/desktop-client/e2e/reports.test.ts-snapshots/Reports-loads-net-worth-graph-and-checks-visuals-2-chromium-linux.png
index 6e5ea49c44..5202741042 100644
Binary files a/packages/desktop-client/e2e/reports.test.ts-snapshots/Reports-loads-net-worth-graph-and-checks-visuals-2-chromium-linux.png and b/packages/desktop-client/e2e/reports.test.ts-snapshots/Reports-loads-net-worth-graph-and-checks-visuals-2-chromium-linux.png differ
diff --git a/packages/desktop-client/e2e/reports.test.ts-snapshots/Reports-loads-net-worth-graph-and-checks-visuals-3-chromium-linux.png b/packages/desktop-client/e2e/reports.test.ts-snapshots/Reports-loads-net-worth-graph-and-checks-visuals-3-chromium-linux.png
index e84eca293f..3648f581e4 100644
Binary files a/packages/desktop-client/e2e/reports.test.ts-snapshots/Reports-loads-net-worth-graph-and-checks-visuals-3-chromium-linux.png and b/packages/desktop-client/e2e/reports.test.ts-snapshots/Reports-loads-net-worth-graph-and-checks-visuals-3-chromium-linux.png differ
diff --git a/packages/desktop-client/src/components/reports/Header.tsx b/packages/desktop-client/src/components/reports/Header.tsx
index e6e1b353b6..520518b75a 100644
--- a/packages/desktop-client/src/components/reports/Header.tsx
+++ b/packages/desktop-client/src/components/reports/Header.tsx
@@ -43,6 +43,8 @@ type HeaderProps = {
) => void;
children?: ReactNode;
inlineContent?: ReactNode;
+ // no separate category filter; use main filters instead
+ filterExclude?: string[];
} & (
| {
filters: RuleConditionEntity[];
@@ -82,10 +84,12 @@ export function Header({
onConditionsOpChange,
children,
inlineContent,
+ filterExclude,
}: HeaderProps) {
const locale = useLocale();
const { t } = useTranslation();
const { isNarrowWidth } = useResponsive();
+
function convertToMonth(
start: string,
end: string,
@@ -293,10 +297,11 @@ export function Header({
compact={isNarrowWidth}
onApply={onApply}
hover={false}
+ exclude={filterExclude}
/>
)}
+ {inlineContent}
</SpaceBetween>
- <SpaceBetween gap={0}>{inlineContent}</SpaceBetween>
</View>
{children && (
diff --git a/packages/desktop-client/src/components/reports/Overview.tsx b/packages/desktop-client/src/components/reports/Overview.tsx
index b9b8e0f62e..f592893665 100644
--- a/packages/desktop-client/src/components/reports/Overview.tsx
+++ b/packages/desktop-client/src/components/reports/Overview.tsx
@@ -26,6 +26,7 @@ import { NON_DRAGGABLE_AREA_CLASS_NAME } from './constants';
import { DashboardHeader } from './DashboardHeader';
import { DashboardSelector } from './DashboardSelector';
import { LoadingIndicator } from './LoadingIndicator';
+import { BudgetAnalysisCard } from './reports/BudgetAnalysisCard';
import { CalendarCard } from './reports/CalendarCard';
import { CashFlowCard } from './reports/CashFlowCard';
import { CrossoverCard } from './reports/CrossoverCard';
@@ -70,6 +71,7 @@ export function Overview({ dashboard }: OverviewProps) {
const [_firstDayOfWeekIdx] = useSyncedPref('firstDayOfWeekIdx');
const firstDayOfWeekIdx = _firstDayOfWeekIdx || '0';
const crossoverReportEnabled = useFeatureFlag('crossoverReport');
+ const budgetAnalysisReportEnabled = useFeatureFlag('budgetAnalysisReport');
const formulaMode = useFeatureFlag('formulaMode');
@@ -518,6 +520,14 @@ export function Overview({ dashboard }: OverviewProps) {
name: 'spending-card' as const,
text: t('Spending analysis'),
},
+ ...(budgetAnalysisReportEnabled
+ ? [
+ {
+ name: 'budget-analysis-card' as const,
+ text: t('Budget analysis'),
+ },
+ ]
+ : []),
{
name: 'markdown-card' as const,
text: t('Text widget'),
@@ -726,6 +736,18 @@ export function Overview({ dashboard }: OverviewProps) {
onCopyWidget(item.i, targetDashboardId)
}
/>
+ ) : widget.type === 'budget-analysis-card' &&
+ budgetAnalysisReportEnabled ? (
+ <BudgetAnalysisCard
+ widgetId={item.i}
+ isEditing={isEditing}
+ meta={widget.meta}
+ onMetaChange={newMeta => onMetaChange(item, newMeta)}
+ onRemove={() => onRemoveWidget(item.i)}
+ onCopy={targetDashboardId =>
+ onCopyWidget(item.i, targetDashboardId)
+ }
+ />
) : widget.type === 'markdown-card' ? (
<MarkdownCard
isEditing={isEditing}
diff --git a/packages/desktop-client/src/components/reports/ReportRouter.tsx b/packages/desktop-client/src/components/reports/ReportRouter.tsx
index d4578c8000..4942737adb 100644
--- a/packages/desktop-client/src/components/reports/ReportRouter.tsx
+++ b/packages/desktop-client/src/components/reports/ReportRouter.tsx
@@ -1,6 +1,7 @@
import React from 'react';
import { Route, Routes } from 'react-router';
+import { BudgetAnalysis } from './reports/BudgetAnalysis';
import { Calendar } from './reports/Calendar';
import { CashFlow } from './reports/CashFlow';
import { Crossover } from './reports/Crossover';
@@ -15,6 +16,7 @@ import { useFeatureFlag } from '@desktop-client/hooks/useFeatureFlag';
export function ReportRouter() {
const crossoverReportEnabled = useFeatureFlag('crossoverReport');
+ const budgetAnalysisReportEnabled = useFeatureFlag('budgetAnalysisReport');
return (
<Routes>
@@ -34,6 +36,12 @@ export function ReportRouter() {
<Route path="/custom/:id" element={<CustomReport />} />
<Route path="/spending" element={<Spending />} />
<Route path="/spending/:id" element={<Spending />} />
+ {budgetAnalysisReportEnabled && (
+ <>
+ <Route path="/budget-analysis" element={<BudgetAnalysis />} />
+ <Route path="/budget-analysis/:id" element={<BudgetAnalysis />} />
+ </>
+ )}
<Route path="/summary" element={<Summary />} />
<Route path="/summary/:id" element={<Summary />} />
<Route path="/calendar" element={<Calendar />} />
diff --git a/packages/desktop-client/src/components/reports/graphs/BudgetAnalysisGraph.tsx b/packages/desktop-client/src/components/reports/graphs/BudgetAnalysisGraph.tsx
new file mode 100644
index 0000000000..e34f73b776
--- /dev/null
+++ b/packages/desktop-client/src/components/reports/graphs/BudgetAnalysisGraph.tsx
@@ -0,0 +1,371 @@
+import React, { useState } from 'react';
+import { Trans, useTranslation } from 'react-i18next';
+
+import { AlignedText } from '@actual-app/components/aligned-text';
+import { type CSSProperties } from '@actual-app/components/styles';
+import { theme } from '@actual-app/components/theme';
+import { css } from '@emotion/css';
+import {
+ Bar,
+ CartesianGrid,
+ ComposedChart,
+ Line,
+ LineChart,
+ Tooltip,
+ XAxis,
+ YAxis,
+} from 'recharts';
+
+import * as monthUtils from 'loot-core/shared/months';
+
+import { FinancialText } from '@desktop-client/components/FinancialText';
+import { Container } from '@desktop-client/components/reports/Container';
+import { useFormat, type FormatType } from '@desktop-client/hooks/useFormat';
+import { useLocale } from '@desktop-client/hooks/useLocale';
+import { usePrivacyMode } from '@desktop-client/hooks/usePrivacyMode';
+
+/**
+ * Interval data for the Budget Analysis graph.
+ * @property date - A date string in format 'YYYY-MM' for monthly intervals
+ * or 'YYYY-MM-DD' for daily intervals, compatible with monthUtils.format
+ */
+type BudgetAnalysisIntervalData = {
+ date: string;
+ budgeted: number;
+ spent: number;
+ balance: number;
+ overspendingAdjustment: number;
+};
+
+type PayloadItem = {
+ payload: {
+ date: string;
+ budgeted: number;
+ spent: number;
+ balance: number;
+ overspendingAdjustment: number;
+ };
+};
+
+type BudgetAnalysisGraphProps = {
+ style?: CSSProperties;
+ data: {
+ intervalData: BudgetAnalysisIntervalData[];
+ };
+ graphType?: 'Line' | 'Bar';
+ showBalance?: boolean;
+ isConcise?: boolean;
+};
+
+type CustomTooltipProps = {
+ active?: boolean;
+ payload?: PayloadItem[];
+ isConcise: boolean;
+ format: (value: unknown, type?: FormatType) => string;
+ showBalance: boolean;
+};
+
+function CustomTooltip({
+ active,
+ payload,
+ isConcise,
+ format,
+ showBalance,
+}: CustomTooltipProps) {
+ const locale = useLocale();
+ const { t } = useTranslation();
+
+ if (!active || !payload || !Array.isArray(payload) || !payload[0]) {
+ return null;
+ }
+
+ const [{ payload: data }] = payload;
+
+ return (
+ <div
+ className={css({
+ pointerEvents: 'none',
+ borderRadius: 2,
+ boxShadow: '0 1px 6px rgba(0, 0, 0, .20)',
+ backgroundColor: theme.menuBackground,
+ color: theme.menuItemText,
+ padding: 10,
+ })}
+ >
+ <div>
+ <div style={{ marginBottom: 10 }}>
+ <strong>
+ {monthUtils.format(
+ data.date,
+ isConcise ? 'MMMM yyyy' : 'MMMM dd, yyyy',
+ locale,
+ )}
+ </strong>
+ </div>
+ <div style={{ lineHeight: 1.5 }}>
+ <AlignedText
+ left={
+ <span style={{ display: 'flex', alignItems: 'center', gap: 5 }}>
+ <span
+ style={{
+ width: 10,
+ height: 10,
+ backgroundColor: theme.reportsNumberPositive,
+ display: 'inline-block',
+ }}
+ />
+ <Trans>Budgeted:</Trans>
+ </span>
+ }
+ right={
+ <FinancialText>
+ {format(data.budgeted, 'financial')}
+ </FinancialText>
+ }
+ />
+ <AlignedText
+ left={
+ <span style={{ display: 'flex', alignItems: 'center', gap: 5 }}>
+ <span
+ style={{
+ width: 10,
+ height: 10,
+ backgroundColor: theme.reportsNumberNegative,
+ display: 'inline-block',
+ }}
+ />
+ <Trans>Spent:</Trans>
+ </span>
+ }
+ right={
+ <FinancialText>{format(data.spent, 'financial')}</FinancialText>
+ }
+ />
+ <AlignedText
+ left={
+ <span style={{ display: 'flex', alignItems: 'center', gap: 5 }}>
+ <span
+ style={{
+ width: 10,
+ height: 10,
+ backgroundColor: theme.templateNumberUnderFunded,
+ display: 'inline-block',
+ }}
+ />
+ {t('Overspending Adjustment:')}
+ </span>
+ }
+ right={
+ <FinancialText>
+ {format(data.overspendingAdjustment, 'financial')}
+ </FinancialText>
+ }
+ />
+ {showBalance && (
+ <AlignedText
+ left={
+ <span style={{ display: 'flex', alignItems: 'center', gap: 5 }}>
+ <span
+ style={{
+ width: 10,
+ height: 10,
+ backgroundColor: theme.reportsNumberNeutral,
+ display: 'inline-block',
+ }}
+ />
+ <Trans>Balance:</Trans>
+ </span>
+ }
+ right={
+ <FinancialText>
+ <strong>{format(data.balance, 'financial')}</strong>
+ </FinancialText>
+ }
+ />
+ )}
+ </div>
+ </div>
+ </div>
+ );
+}
+
+export function BudgetAnalysisGraph({
+ style,
+ data,
+ graphType = 'Line',
+ showBalance = true,
+ isConcise = true,
+}: BudgetAnalysisGraphProps) {
+ const { t } = useTranslation();
+ const format = useFormat();
+ const locale = useLocale();
+ const privacyMode = usePrivacyMode();
+ const [yAxisIsHovered, setYAxisIsHovered] = useState(false);
+
+ // Centralize translated labels to avoid repetition
+ const budgetedLabel = t('Budgeted');
+ const spentLabel = t('Spent');
+ const balanceLabel = t('Balance');
+ const overspendingLabel = t('Overspending Adjustment');
+
+ const graphData = data.intervalData;
+
+ const formatDate = (date: string) => {
+ if (isConcise) {
+ // Monthly format
+ return monthUtils.format(date, 'MMM', locale);
+ }
+ // Daily format
+ return monthUtils.format(date, 'MMM d', locale);
+ };
+
+ const commonProps = {
+ width: 0,
+ height: 0,
+ data: graphData,
+ margin: { top: 5, right: 5, left: 5, bottom: 5 },
+ };
+
+ return (
+ <Container style={style}>
+ {(width, height) => {
+ const chartProps = { ...commonProps, width, height };
+
+ return graphType === 'Bar' ? (
+ <ComposedChart {...chartProps}>
+ <CartesianGrid strokeDasharray="3 3" stroke={theme.pillBorder} />
+ <XAxis
+ dataKey="date"
+ tick={{ fill: theme.reportsLabel }}
+ tickFormatter={formatDate}
+ minTickGap={50}
+ />
+ <YAxis
+ tick={{ fill: theme.reportsLabel }}
+ tickCount={8}
+ tickFormatter={value =>
+ privacyMode && !yAxisIsHovered
+ ? '...'
+ : format(value, 'financial-no-decimals')
+ }
+ onMouseEnter={() => setYAxisIsHovered(true)}
+ onMouseLeave={() => setYAxisIsHovered(false)}
+ stroke={theme.pageTextSubdued}
+ />
+ <Tooltip
+ cursor={{ fill: 'transparent' }}
+ content={
+ <CustomTooltip
+ isConcise={isConcise}
+ format={format}
+ showBalance={showBalance}
+ />
+ }
+ isAnimationActive={false}
+ />
+ <Bar
+ dataKey="budgeted"
+ fill={theme.reportsNumberPositive}
+ name={budgetedLabel}
+ animationDuration={1000}
+ />
+ <Bar
+ dataKey="spent"
+ fill={theme.reportsNumberNegative}
+ name={spentLabel}
+ animationDuration={1000}
+ />
+ <Bar
+ dataKey="overspendingAdjustment"
+ fill={theme.templateNumberUnderFunded}
+ name={overspendingLabel}
+ animationDuration={1000}
+ />
+ {showBalance && (
+ <Line
+ type="monotone"
+ dataKey="balance"
+ stroke={theme.reportsNumberNeutral}
+ strokeWidth={2}
+ name={balanceLabel}
+ dot={false}
+ animationDuration={1000}
+ />
+ )}
+ </ComposedChart>
+ ) : (
+ <LineChart {...chartProps}>
+ <CartesianGrid strokeDasharray="3 3" stroke={theme.pillBorder} />
+ <XAxis
+ dataKey="date"
+ tick={{ fill: theme.reportsLabel }}
+ tickFormatter={formatDate}
+ minTickGap={50}
+ />
+ <YAxis
+ tick={{ fill: theme.reportsLabel }}
+ tickCount={8}
+ tickFormatter={value =>
+ privacyMode && !yAxisIsHovered
+ ? '...'
+ : format(value, 'financial-no-decimals')
+ }
+ onMouseEnter={() => setYAxisIsHovered(true)}
+ onMouseLeave={() => setYAxisIsHovered(false)}
+ stroke={theme.pageTextSubdued}
+ />
+ <Tooltip
+ cursor={{ fill: 'transparent' }}
+ content={
+ <CustomTooltip
+ isConcise={isConcise}
+ format={format}
+ showBalance={showBalance}
+ />
+ }
+ isAnimationActive={false}
+ />
+ <Line
+ type="monotone"
+ dataKey="budgeted"
+ stroke={theme.reportsNumberPositive}
+ strokeWidth={2}
+ name={budgetedLabel}
+ dot={false}
+ animationDuration={1000}
+ />
+ <Line
+ type="monotone"
+ dataKey="spent"
+ stroke={theme.reportsNumberNegative}
+ strokeWidth={2}
+ name={spentLabel}
+ dot={false}
+ animationDuration={1000}
+ />
+ <Line
+ type="monotone"
+ dataKey="overspendingAdjustment"
+ stroke={theme.templateNumberUnderFunded}
+ strokeWidth={2}
+ name={overspendingLabel}
+ dot={false}
+ animationDuration={1000}
+ />
+ {showBalance && (
+ <Line
+ type="monotone"
+ dataKey="balance"
+ stroke={theme.reportsNumberNeutral}
+ strokeWidth={2}
+ name={balanceLabel}
+ dot={false}
+ animationDuration={1000}
+ />
+ )}
+ </LineChart>
+ );
+ }}
+ </Container>
+ );
+}
diff --git a/packages/desktop-client/src/components/reports/reports/BudgetAnalysis.tsx b/packages/desktop-client/src/components/reports/reports/BudgetAnalysis.tsx
new file mode 100644
index 0000000000..d46e52ffc3
--- /dev/null
+++ b/packages/desktop-client/src/components/reports/reports/BudgetAnalysis.tsx
@@ -0,0 +1,508 @@
+import React, { useEffect, useMemo, useState } from 'react';
+import { Trans, useTranslation } from 'react-i18next';
+import { useParams } from 'react-router';
+
+import { AlignedText } from '@actual-app/components/aligned-text';
+import { Block } from '@actual-app/components/block';
+import { Button } from '@actual-app/components/button';
+import { useResponsive } from '@actual-app/components/hooks/useResponsive';
+import { SvgChart, SvgChartBar } from '@actual-app/components/icons/v1';
+import { Paragraph } from '@actual-app/components/paragraph';
+import { theme } from '@actual-app/components/theme';
+import { Tooltip } from '@actual-app/components/tooltip';
+import { View } from '@actual-app/components/view';
+import * as d from 'date-fns';
+
+import { send } from 'loot-core/platform/client/fetch';
+import * as monthUtils from 'loot-core/shared/months';
+import {
+ type BudgetAnalysisWidget,
+ type RuleConditionEntity,
+ type TimeFrame,
+} from 'loot-core/types/models';
+
+import { EditablePageHeaderTitle } from '@desktop-client/components/EditablePageHeaderTitle';
+import { FinancialText } from '@desktop-client/components/FinancialText';
+import { MobileBackButton } from '@desktop-client/components/mobile/MobileBackButton';
+import {
+ MobilePageHeader,
+ Page,
+ PageHeader,
+} from '@desktop-client/components/Page';
+import { PrivacyFilter } from '@desktop-client/components/PrivacyFilter';
+import { Change } from '@desktop-client/components/reports/Change';
+import { BudgetAnalysisGraph } from '@desktop-client/components/reports/graphs/BudgetAnalysisGraph';
+import { Header } from '@desktop-client/components/reports/Header';
+import { LoadingIndicator } from '@desktop-client/components/reports/LoadingIndicator';
+import { calculateTimeRange } from '@desktop-client/components/reports/reportRanges';
+import { createBudgetAnalysisSpreadsheet } from '@desktop-client/components/reports/spreadsheets/budget-analysis-spreadsheet';
+import { useReport } from '@desktop-client/components/reports/useReport';
+import { fromDateRepr } from '@desktop-client/components/reports/util';
+import { useFormat } from '@desktop-client/hooks/useFormat';
+import { useLocale } from '@desktop-client/hooks/useLocale';
+import { useNavigate } from '@desktop-client/hooks/useNavigate';
+import { useRuleConditionFilters } from '@desktop-client/hooks/useRuleConditionFilters';
+import { useSyncedPref } from '@desktop-client/hooks/useSyncedPref';
+import { useWidget } from '@desktop-client/hooks/useWidget';
+import { addNotification } from '@desktop-client/notifications/notificationsSlice';
+import { useDispatch } from '@desktop-client/redux';
+
+export function BudgetAnalysis() {
+ const params = useParams();
+ const { data: widget, isLoading } = useWidget<BudgetAnalysisWidget>(
+ params.id ?? '',
+ 'budget-analysis-card',
+ );
+
+ if (isLoading) {
+ return <LoadingIndicator />;
+ }
+
+ return <BudgetAnalysisInternal widget={widget} />;
+}
+
+type BudgetAnalysisInternalProps = {
+ widget?: BudgetAnalysisWidget;
+};
+
+function BudgetAnalysisInternal({ widget }: BudgetAnalysisInternalProps) {
+ const locale = useLocale();
+ const dispatch = useDispatch();
+ const { t } = useTranslation();
+ const format = useFormat();
+
+ const {
+ conditions,
+ conditionsOp,
+ onApply: onApplyFilter,
+ onDelete: onDeleteFilter,
+ onUpdate: onUpdateFilter,
+ onConditionsOpChange,
+ } = useRuleConditionFilters<RuleConditionEntity>(
+ widget?.meta?.conditions,
+ widget?.meta?.conditionsOp,
+ );
+
+ const [allMonths, setAllMonths] = useState<Array<{
+ name: string;
+ pretty: string;
+ }> | null>(null);
+
+ const [start, setStart] = useState(monthUtils.currentMonth());
+ const [end, setEnd] = useState(monthUtils.currentMonth());
+ const [mode, setMode] = useState<TimeFrame['mode']>('sliding-window');
+ const [graphType, setGraphType] = useState<'Line' | 'Bar'>(
+ widget?.meta?.graphType || 'Bar',
+ );
+ const [showBalance, setShowBalance] = useState(
+ widget?.meta?.showBalance ?? true,
+ );
+ const [latestTransaction, setLatestTransaction] = useState('');
+ const [isConcise, setIsConcise] = useState(() => {
+ // Default to concise (monthly) view until we load the actual date range
+ return true;
+ });
+
+ const [_firstDayOfWeekIdx] = useSyncedPref('firstDayOfWeekIdx');
+ const firstDayOfWeekIdx = _firstDayOfWeekIdx || '0';
+
+ const calculateIsConcise = (startMonth: string, endMonth: string) => {
+ const numDays = d.differenceInCalendarDays(
+ d.parseISO(endMonth + '-01'),
+ d.parseISO(startMonth + '-01'),
+ );
+ return numDays > 31 * 3;
+ };
+
+ useEffect(() => {
+ async function run() {
+ const earliestTrans = await send('get-earliest-transaction');
+ const latestTrans = await send('get-latest-transaction');
+ const latestTransDate = latestTrans
+ ? fromDateRepr(latestTrans.date)
+ : monthUtils.currentDay();
+ setLatestTransaction(latestTransDate);
+
+ const currentMonth = monthUtils.currentMonth();
+ let earliestMonth = earliestTrans
+ ? monthUtils.monthFromDate(d.parseISO(fromDateRepr(earliestTrans.date)))
+ : currentMonth;
+ const latestTransactionMonth = latestTrans
+ ? monthUtils.monthFromDate(d.parseISO(fromDateRepr(latestTrans.date)))
+ : currentMonth;
+
+ const latestMonth =
+ latestTransactionMonth > currentMonth
+ ? latestTransactionMonth
+ : currentMonth;
+
+ const yearAgo = monthUtils.subMonths(latestMonth, 12);
+ if (earliestMonth > yearAgo) {
+ earliestMonth = yearAgo;
+ }
+
+ const allMonthsData = monthUtils
+ .rangeInclusive(earliestMonth, latestMonth)
+ .map(month => ({
+ name: month,
+ pretty: monthUtils.format(month, 'MMMM, yyyy', locale),
+ }))
+ .reverse();
+
+ setAllMonths(allMonthsData);
+
+ if (widget?.meta?.timeFrame) {
+ const [calculatedStart, calculatedEnd] = calculateTimeRange(
+ widget.meta.timeFrame,
+ undefined,
+ latestTransDate,
+ );
+ setStart(calculatedStart);
+ setEnd(calculatedEnd);
+ setMode(widget.meta.timeFrame.mode);
+
+ setIsConcise(calculateIsConcise(calculatedStart, calculatedEnd));
+ } else {
+ const [liveStart, liveEnd] = calculateTimeRange({
+ start: monthUtils.subMonths(currentMonth, 5),
+ end: currentMonth,
+ mode: 'sliding-window',
+ });
+ setStart(liveStart);
+ setEnd(liveEnd);
+
+ setIsConcise(calculateIsConcise(liveStart, liveEnd));
+ }
+ }
+ run();
+ }, [locale, widget?.meta?.timeFrame]);
+
+ const startDate = start + '-01';
+ const endDate = monthUtils.getMonthEnd(end + '-01');
+
+ const getGraphData = useMemo(
+ () =>
+ createBudgetAnalysisSpreadsheet({
+ conditions,
+ conditionsOp,
+ startDate,
+ endDate,
+ }),
+ [conditions, conditionsOp, startDate, endDate],
+ );
+
+ const data = useReport('default', getGraphData);
+ const navigate = useNavigate();
+ const { isNarrowWidth } = useResponsive();
+
+ const onChangeDates = (
+ newStart: string,
+ newEnd: string,
+ newMode: TimeFrame['mode'],
+ ) => {
+ setStart(newStart);
+ setEnd(newEnd);
+ setMode(newMode);
+
+ setIsConcise(calculateIsConcise(newStart, newEnd));
+ };
+
+ async function onSaveWidget() {
+ if (!widget) {
+ throw new Error('No widget that could be saved.');
+ }
+
+ await send('dashboard-update-widget', {
+ id: widget.id,
+ meta: {
+ ...(widget.meta ?? {}),
+ conditions,
+ conditionsOp,
+ timeFrame: {
+ start,
+ end,
+ mode,
+ },
+ graphType,
+ showBalance,
+ },
+ });
+ dispatch(
+ addNotification({
+ notification: {
+ type: 'message',
+ message: t('Dashboard widget successfully saved.'),
+ },
+ }),
+ );
+ }
+
+ if (!data || !allMonths) {
+ return <LoadingIndicator />;
+ }
+
+ const latestInterval = data.intervalData[data.intervalData.length - 1];
+ const endingBalance = latestInterval?.balance ?? 0;
+
+ const title = widget?.meta?.name || t('Budget Analysis');
+ const onSaveWidgetName = async (newName: string) => {
+ if (!widget) {
+ throw new Error('No widget that could be saved.');
+ }
+
+ const name = newName || t('Budget Analysis');
+ await send('dashboard-update-widget', {
+ id: widget.id,
+ meta: {
+ ...(widget.meta ?? {}),
+ name,
+ },
+ });
+ };
+
+ return (
+ <Page
+ header={
+ isNarrowWidth ? (
+ <MobilePageHeader
+ title={title}
+ leftContent={
+ <MobileBackButton onPress={() => navigate('/reports')} />
+ }
+ />
+ ) : (
+ <PageHeader
+ title={
+ widget ? (
+ <EditablePageHeaderTitle
+ title={title}
+ onSave={onSaveWidgetName}
+ />
+ ) : (
+ title
+ )
+ }
+ />
+ )
+ }
+ padding={0}
+ >
+ <Header
+ start={start}
+ end={end}
+ mode={mode}
+ show1Month
+ allMonths={allMonths}
+ earliestTransaction={allMonths[allMonths.length - 1].name}
+ latestTransaction={latestTransaction}
+ firstDayOfWeekIdx={firstDayOfWeekIdx}
+ onChangeDates={onChangeDates}
+ filters={conditions}
+ conditionsOp={conditionsOp}
+ onApply={onApplyFilter}
+ onUpdateFilter={onUpdateFilter}
+ onDeleteFilter={onDeleteFilter}
+ onConditionsOpChange={onConditionsOpChange}
+ filterExclude={[
+ 'date',
+ 'account',
+ 'payee',
+ 'notes',
+ 'amount',
+ 'cleared',
+ 'reconciled',
+ 'transfer',
+ ]}
+ inlineContent={
+ <Tooltip
+ content={
+ graphType === 'Line'
+ ? t('Switch to bar chart')
+ : t('Switch to line chart')
+ }
+ >
+ <Button
+ variant="bare"
+ onPress={() =>
+ setGraphType(graphType === 'Line' ? 'Bar' : 'Line')
+ }
+ >
+ {graphType === 'Line' ? (
+ <SvgChartBar style={{ width: 12, height: 12 }} />
+ ) : (
+ <SvgChart style={{ width: 12, height: 12 }} />
+ )}
+ </Button>
+ </Tooltip>
+ }
+ >
+ <View style={{ flexDirection: 'row', gap: 10 }}>
+ <Button onPress={() => setShowBalance(state => !state)}>
+ {showBalance ? t('Hide balance') : t('Show balance')}
+ </Button>
+
+ {widget && (
+ <Button variant="primary" onPress={onSaveWidget}>
+ <Trans>Save widget</Trans>
+ </Button>
+ )}
+ </View>
+ </Header>
+ <View
+ style={{
+ display: 'flex',
+ flexDirection: 'row',
+ paddingTop: 0,
+ flexGrow: 1,
+ }}
+ >
+ <View
+ style={{
+ flexGrow: 1,
+ }}
+ >
+ <View
+ style={{
+ backgroundColor: theme.tableBackground,
+ padding: 20,
+ paddingTop: 0,
+ flex: '1 0 auto',
+ overflowY: 'auto',
+ }}
+ >
+ <View
+ style={{
+ flexDirection: 'column',
+ flexGrow: 1,
+ padding: 10,
+ paddingTop: 10,
+ }}
+ >
+ <View
+ style={{
+ alignItems: 'flex-end',
+ flexDirection: 'row',
+ }}
+ >
+ <View style={{ flex: 1 }} />
+ <View
+ style={{
+ alignItems: 'flex-end',
+ color: theme.pageText,
+ }}
+ >
+ <View>
+ {data && (
+ <>
+ <AlignedText
+ style={{ marginBottom: 5, minWidth: 210 }}
+ left={
+ <Block>
+ <Trans>Budgeted:</Trans>
+ </Block>
+ }
+ right={
+ <FinancialText style={{ fontWeight: 600 }}>
+ <PrivacyFilter>
+ {format(data.totalBudgeted, 'financial')}
+ </PrivacyFilter>
+ </FinancialText>
+ }
+ />
+ <AlignedText
+ style={{ marginBottom: 5, minWidth: 210 }}
+ left={
+ <Block>
+ <Trans>Spent:</Trans>
+ </Block>
+ }
+ right={
+ <FinancialText style={{ fontWeight: 600 }}>
+ <PrivacyFilter>
+ {format(data.totalSpent, 'financial')}
+ </PrivacyFilter>
+ </FinancialText>
+ }
+ />
+ <AlignedText
+ style={{ marginBottom: 5, minWidth: 210 }}
+ left={
+ <Block>
+ <Trans>Overspending adj:</Trans>
+ </Block>
+ }
+ right={
+ <FinancialText style={{ fontWeight: 600 }}>
+ <PrivacyFilter>
+ {format(
+ data.totalOverspendingAdjustment,
+ 'financial',
+ )}
+ </PrivacyFilter>
+ </FinancialText>
+ }
+ />
+ {showBalance && (
+ <AlignedText
+ style={{ marginBottom: 5, minWidth: 210 }}
+ left={
+ <Block>
+ <Trans>Ending balance:</Trans>
+ </Block>
+ }
+ right={
+ <FinancialText style={{ fontWeight: 600 }}>
+ <PrivacyFilter>
+ <Change amount={endingBalance} />
+ </PrivacyFilter>
+ </FinancialText>
+ }
+ />
+ )}
+ </>
+ )}
+ </View>
+ </View>
+ </View>
+ <BudgetAnalysisGraph
+ style={{ flexGrow: 1 }}
+ data={data}
+ graphType={graphType}
+ showBalance={showBalance}
+ isConcise={isConcise}
+ />
+ <View style={{ marginTop: 30 }}>
+ <Trans>
+ <Paragraph>
+ <strong>Understanding the Chart</strong>
+ <br />• <strong>Budgeted:</strong> The amount you allocated
+ each month
+ <br />• <strong>Spent:</strong> Your actual spending
+ <br />• <strong>Overspending Adjustment:</strong> Amounts
+ from categories without rollover that were reset
+ <br />• <strong>Balance:</strong> Your cumulative budget
+ performance, starting with any prior balance. Respects
+ category rollover settings from your budget.
+ </Paragraph>
+ <Paragraph>
+ <strong>Understanding the Budget Summary</strong>
+ <br />
+ The balance starts from the month before your selected
+ period. Budgeted, spent, and overspending adjustments show
+ totals over the period. Ending balance shows the final
+ balance at period end. You can filter by categories to track
+ changes in a specific area.
+ </Paragraph>
+ <Paragraph>
+ Hint: You can use the icon in the header to toggle between
+ line and bar chart views.
+ </Paragraph>
+ </Trans>
+ </View>
+ </View>
+ </View>
+ </View>
+ </View>
+ </Page>
+ );
+}
diff --git a/packages/desktop-client/src/components/reports/reports/BudgetAnalysisCard.tsx b/packages/desktop-client/src/components/reports/reports/BudgetAnalysisCard.tsx
new file mode 100644
index 0000000000..791521ba62
--- /dev/null
+++ b/packages/desktop-client/src/components/reports/reports/BudgetAnalysisCard.tsx
@@ -0,0 +1,168 @@
+import React, { useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { Block } from '@actual-app/components/block';
+import { styles } from '@actual-app/components/styles';
+import { theme } from '@actual-app/components/theme';
+import { View } from '@actual-app/components/view';
+
+import * as monthUtils from 'loot-core/shared/months';
+import { type BudgetAnalysisWidget } from 'loot-core/types/models';
+
+import { FinancialText } from '@desktop-client/components/FinancialText';
+import { PrivacyFilter } from '@desktop-client/components/PrivacyFilter';
+import { DateRange } from '@desktop-client/components/reports/DateRange';
+import { BudgetAnalysisGraph } from '@desktop-client/components/reports/graphs/BudgetAnalysisGraph';
+import { LoadingIndicator } from '@desktop-client/components/reports/LoadingIndicator';
+import { ReportCard } from '@desktop-client/components/reports/ReportCard';
+import { ReportCardName } from '@desktop-client/components/reports/ReportCardName';
+import { createBudgetAnalysisSpreadsheet } from '@desktop-client/components/reports/spreadsheets/budget-analysis-spreadsheet';
+import { useReport } from '@desktop-client/components/reports/useReport';
+import { useWidgetCopyMenu } from '@desktop-client/components/reports/useWidgetCopyMenu';
+import { useFormat } from '@desktop-client/hooks/useFormat';
+
+type BudgetAnalysisCardProps = {
+ widgetId: string;
+ isEditing?: boolean;
+ meta?: BudgetAnalysisWidget['meta'];
+ onMetaChange: (newMeta: BudgetAnalysisWidget['meta']) => void;
+ onRemove: () => void;
+ onCopy: (targetDashboardId: string) => void;
+};
+
+export function BudgetAnalysisCard({
+ widgetId,
+ isEditing,
+ meta = {},
+ onMetaChange,
+ onRemove,
+ onCopy,
+}: BudgetAnalysisCardProps) {
+ const { t } = useTranslation();
+ const format = useFormat();
+
+ const [isCardHovered, setIsCardHovered] = useState(false);
+ const [nameMenuOpen, setNameMenuOpen] = useState(false);
+
+ const { menuItems: copyMenuItems, handleMenuSelect: handleCopyMenuSelect } =
+ useWidgetCopyMenu(onCopy);
+
+ const timeFrame = meta?.timeFrame ?? {
+ start: monthUtils.subMonths(monthUtils.currentMonth(), 5),
+ end: monthUtils.currentMonth(),
+ mode: 'sliding-window' as const,
+ };
+
+ // Calculate date range
+ let startDate = timeFrame.start + '-01';
+ let endDate = monthUtils.getMonthEnd(timeFrame.end + '-01');
+
+ if (timeFrame.mode === 'sliding-window') {
+ const currentMonth = monthUtils.currentMonth();
+ startDate = monthUtils.subMonths(currentMonth, 5) + '-01';
+ endDate = monthUtils.getMonthEnd(currentMonth + '-01');
+ }
+
+ const getGraphData = useMemo(() => {
+ return createBudgetAnalysisSpreadsheet({
+ conditions: meta?.conditions,
+ conditionsOp: meta?.conditionsOp,
+ startDate,
+ endDate,
+ });
+ }, [meta?.conditions, meta?.conditionsOp, startDate, endDate]);
+
+ const data = useReport('default', getGraphData);
+
+ const latestInterval =
+ data && data.intervalData.length > 0
+ ? data.intervalData[data.intervalData.length - 1]
+ : undefined;
+ const balance = latestInterval?.balance ?? 0;
+ return (
+ <ReportCard
+ isEditing={isEditing}
+ disableClick={nameMenuOpen}
+ to={`/reports/budget-analysis/${widgetId}`}
+ menuItems={[
+ {
+ name: 'rename',
+ text: t('Rename'),
+ },
+ {
+ name: 'remove',
+ text: t('Remove'),
+ },
+ ...copyMenuItems,
+ ]}
+ onMenuSelect={item => {
+ if (handleCopyMenuSelect(item)) return;
+ switch (item) {
+ case 'rename':
+ setNameMenuOpen(true);
+ break;
+ case 'remove':
+ onRemove();
+ break;
+ default:
+ throw new Error(`Unrecognized selection: ${item}`);
+ }
+ }}
+ >
+ <View
+ style={{ flex: 1 }}
+ onPointerEnter={() => setIsCardHovered(true)}
+ onPointerLeave={() => setIsCardHovered(false)}
+ >
+ <View style={{ flexDirection: 'row', padding: 20 }}>
+ <View style={{ flex: 1 }}>
+ <ReportCardName
+ name={meta?.name || t('Budget Analysis')}
+ isEditing={nameMenuOpen}
+ onChange={newName => {
+ onMetaChange({
+ ...meta,
+ name: newName,
+ });
+ setNameMenuOpen(false);
+ }}
+ onClose={() => setNameMenuOpen(false)}
+ />
+ <DateRange
+ start={monthUtils.getMonth(startDate)}
+ end={monthUtils.getMonth(endDate)}
+ />
+ </View>
+ {data && (
+ <View style={{ textAlign: 'right' }}>
+ <Block
+ style={{
+ ...styles.mediumText,
+ fontWeight: 500,
+ marginBottom: 5,
+ color: balance >= 0 ? theme.noticeTextLight : theme.errorText,
+ }}
+ >
+ <FinancialText>
+ <PrivacyFilter activationFilters={[!isCardHovered]}>
+ {format(balance, 'financial')}
+ </PrivacyFilter>
+ </FinancialText>
+ </Block>
+ </View>
+ )}
+ </View>
+ {data ? (
+ <BudgetAnalysisGraph
+ style={{ flex: 1 }}
+ data={data}
+ graphType={meta?.graphType || 'Bar'}
+ showBalance={meta?.showBalance ?? true}
+ />
+ ) : (
+ <LoadingIndicator />
+ )}
+ </View>
+ </ReportCard>
+ );
+}
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
new file mode 100644
index 0000000000..94c79d51c8
--- /dev/null
+++ b/packages/desktop-client/src/components/reports/spreadsheets/budget-analysis-spreadsheet.ts
@@ -0,0 +1,238 @@
+// @ts-strict-ignore
+import { send } from 'loot-core/platform/client/fetch';
+import * as monthUtils from 'loot-core/shared/months';
+import {
+ type CategoryEntity,
+ type RuleConditionEntity,
+} from 'loot-core/types/models';
+
+import { type useSpreadsheet } from '@desktop-client/hooks/useSpreadsheet';
+
+type BudgetAnalysisIntervalData = {
+ date: string;
+ budgeted: number;
+ spent: number;
+ balance: number;
+ overspendingAdjustment: number;
+};
+
+type BudgetAnalysisData = {
+ intervalData: BudgetAnalysisIntervalData[];
+ startDate: string;
+ endDate: string;
+ totalBudgeted: number;
+ totalSpent: number;
+ totalOverspendingAdjustment: number;
+ finalOverspendingAdjustment: number;
+};
+
+type createBudgetAnalysisSpreadsheetProps = {
+ conditions?: RuleConditionEntity[];
+ conditionsOp?: 'and' | 'or';
+ startDate: string;
+ endDate: string;
+};
+
+export function createBudgetAnalysisSpreadsheet({
+ conditions = [],
+ conditionsOp = 'and',
+ startDate,
+ endDate,
+}: createBudgetAnalysisSpreadsheetProps) {
+ return async (
+ spreadsheet: ReturnType<typeof useSpreadsheet>,
+ setData: (data: BudgetAnalysisData) => void,
+ ) => {
+ // Get all categories
+ const { list: allCategories } = await send('get-categories');
+
+ // Filter categories based on conditions
+ const categoryConditions = conditions.filter(
+ cond => !cond.customName && cond.field === 'category',
+ );
+
+ // Base set: expense categories only (exclude income and hidden)
+ const baseCategories = allCategories.filter(
+ (cat: CategoryEntity) => !cat.is_income && !cat.hidden,
+ );
+
+ let categoriesToInclude: CategoryEntity[];
+ if (categoryConditions.length > 0) {
+ // Evaluate each condition to get sets of matching categories
+ const conditionResults = categoryConditions.map(cond => {
+ return baseCategories.filter((cat: CategoryEntity) => {
+ if (cond.op === 'is') {
+ return cond.value === cat.id;
+ } else if (cond.op === 'isNot') {
+ return cond.value !== cat.id;
+ } else if (cond.op === 'oneOf') {
+ return cond.value.includes(cat.id);
+ } else if (cond.op === 'notOneOf') {
+ return !cond.value.includes(cat.id);
+ }
+ return false;
+ });
+ });
+
+ // Combine results based on conditionsOp
+ if (conditionsOp === 'or') {
+ // OR: Union of all matching categories
+ const categoryIds = new Set(conditionResults.flat().map(cat => cat.id));
+ categoriesToInclude = baseCategories.filter(cat =>
+ categoryIds.has(cat.id),
+ );
+ } else {
+ // AND: Intersection of all matching categories
+ if (conditionResults.length === 0) {
+ categoriesToInclude = [];
+ } else {
+ const firstSet = new Set(conditionResults[0].map(cat => cat.id));
+ for (let i = 1; i < conditionResults.length; i++) {
+ const currentIds = new Set(conditionResults[i].map(cat => cat.id));
+ // Keep only categories that are in both sets
+ for (const id of firstSet) {
+ if (!currentIds.has(id)) {
+ firstSet.delete(id);
+ }
+ }
+ }
+ categoriesToInclude = baseCategories.filter(cat =>
+ firstSet.has(cat.id),
+ );
+ }
+ }
+ } else {
+ // No category filter, use all expense categories
+ categoriesToInclude = baseCategories;
+ }
+
+ // Get monthly intervals (Budget Analysis only supports monthly)
+ const intervals = monthUtils.rangeInclusive(
+ monthUtils.getMonth(startDate),
+ monthUtils.getMonth(endDate),
+ );
+
+ const intervalData: BudgetAnalysisIntervalData[] = [];
+
+ // 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,
+ );
+ const prevMonthData = await send('envelope-budget-month', {
+ month: monthBeforeStart,
+ });
+
+ // Calculate the carryover from the previous month
+ for (const cat of categoriesToInclude) {
+ const balanceCell = prevMonthData.find((cell: { name: string }) =>
+ cell.name.endsWith(`leftover-${cat.id}`),
+ );
+ const carryoverCell = prevMonthData.find((cell: { name: string }) =>
+ 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;
+ }
+ }
+
+ // Track totals across all months
+ let totalBudgeted = 0;
+ let totalSpent = 0;
+ let totalOverspendingAdjustment = 0;
+
+ // Track overspending from previous month to apply in next month
+ let overspendingFromPrevMonth = 0;
+
+ // Process each month
+ for (const month of intervals) {
+ // Get budget values from the server for this month
+ // 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: { name: string }) =>
+ cell.name.endsWith(`budget-${cat.id}`),
+ );
+ const spentCell = monthData.find((cell: { name: string }) =>
+ cell.name.endsWith(`sum-amount-${cat.id}`),
+ );
+ const balanceCell = monthData.find((cell: { name: string }) =>
+ cell.name.endsWith(`leftover-${cat.id}`),
+ );
+ const carryoverCell = monthData.find((cell: { name: string }) =>
+ 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
+ }
+ }
+
+ // Apply overspending adjustment from previous month (negative value)
+ const overspendingAdjustment = overspendingFromPrevMonth;
+
+ // This month's balance = budgeted + spent + running balance + overspending adjustment
+ const monthBalance = budgeted + spent + runningBalance;
+
+ // Update totals
+ totalBudgeted += budgeted;
+ totalSpent += spent;
+ totalOverspendingAdjustment += Math.abs(overspendingAdjustment);
+
+ intervalData.push({
+ date: month,
+ budgeted,
+ spent, // Display as positive
+ balance: monthBalance,
+ overspendingAdjustment: Math.abs(overspendingAdjustment), // Display as positive
+ });
+
+ // Update running balance for next month
+ runningBalance = carryoverToNextMonth;
+ // Save this month's overspending to apply in next month
+ overspendingFromPrevMonth = overspendingThisMonth;
+ }
+
+ setData({
+ intervalData,
+ startDate,
+ endDate,
+ totalBudgeted,
+ totalSpent,
+ totalOverspendingAdjustment,
+ finalOverspendingAdjustment: overspendingFromPrevMonth,
+ });
+ };
+}
diff --git a/packages/desktop-client/src/components/settings/Experimental.tsx b/packages/desktop-client/src/components/settings/Experimental.tsx
index 2f0e17f563..15e0e5f662 100644
--- a/packages/desktop-client/src/components/settings/Experimental.tsx
+++ b/packages/desktop-client/src/components/settings/Experimental.tsx
@@ -208,11 +208,17 @@ export function ExperimentalFeatures() {
>
<Trans>Custom themes</Trans>
</FeatureToggle>
+ <FeatureToggle
+ flag="budgetAnalysisReport"
+ feedbackLink="https://github.com/actualbudget/actual/pull/6137"
+ >
+ <Trans>Budget Analysis Report</Trans>
+ </FeatureToggle>
{showServerPrefs && (
<ServerFeatureToggle
prefName="flags.plugins"
disableToggle
- feedbackLink="https://github.com/actualbudget/actual/issues/5950"
+ feedbackLink="https://github.com/actualbudget/actual/issues/6742"
>
<Trans>Client-Side plugins (soon)</Trans>
</ServerFeatureToggle>
diff --git a/packages/desktop-client/src/hooks/useFeatureFlag.ts b/packages/desktop-client/src/hooks/useFeatureFlag.ts
index 88010927db..3ee4c789b8 100644
--- a/packages/desktop-client/src/hooks/useFeatureFlag.ts
+++ b/packages/desktop-client/src/hooks/useFeatureFlag.ts
@@ -10,6 +10,7 @@ const DEFAULT_FEATURE_FLAG_STATE: Record<FeatureFlag, boolean> = {
currency: false,
crossoverReport: false,
customThemes: false,
+ budgetAnalysisReport: false,
};
export function useFeatureFlag(name: FeatureFlag): boolean {
diff --git a/packages/docs/docs-sidebar.js b/packages/docs/docs-sidebar.js
index b903264f1f..9565443a1f 100644
--- a/packages/docs/docs-sidebar.js
+++ b/packages/docs/docs-sidebar.js
@@ -219,6 +219,7 @@ const sidebars = {
'experimental/pluggyai',
'experimental/crossover-point-report',
'experimental/custom-themes',
+ 'experimental/budget-analysis-report',
],
},
'getting-started/tips-tricks',
diff --git a/packages/docs/docs/experimental/budget-analysis-report.md b/packages/docs/docs/experimental/budget-analysis-report.md
new file mode 100644
index 0000000000..98a6332765
--- /dev/null
+++ b/packages/docs/docs/experimental/budget-analysis-report.md
@@ -0,0 +1,39 @@
+# Budget Analysis Report
+
+:::warning
+This is an **experimental feature**. That means we’re still working on finishing it. There may be bugs, missing functionality or incomplete documentation, and we may decide to remove the feature in a future release. If you have any feedback, please comment on the [dedicated issue](https://github.com/actualbudget/actual/issues/6742) or post a message in the Discord.
+:::
+
+## What it is
+
+The Budget Analysis is a financial planning tool, that tracks the balance of your budget over time.
+It tracks four separate series: **Budgeted**, **Spent**, **Overspending Adjustment**, and the cumulative **Balance**.
+
+![Example image of Budget Analysis Report](/img/experimental/budget-analysis/budget-analysis-image.webp)
+
+## Important information
+
+- The report pulls the numbers directly from the Budget page, so it only includes budget categories (no transfers or off‑budget accounts).
+- The report's numbers reflect your filtered view, so if you exclude categories or change date ranges, the report updates accordingly.
+- Category rollover rules affect negative balances:
+ - If **Rollover overspending** is enabled for a category, negative balances carry forward.
+ - If **Rollover overspending** is disabled, negative balances for that category are zeroed and recorded as an **Overspending Adjustment** (aggregated and shown as its own series).
+
+## Display options
+
+- **Live / Static**: toggle a rolling window (auto-updates) or a fixed date range.
+- **Start / End**: pick start and end months.
+- **Quick ranges**: 1, 3, 6 months, 1 year, Year-to-date, Previous year-to-date, All time.
+- **Filters**: use the Filter button → choose _Category_ to include/exclude categories; active filters appear as editable chips.
+- **Graph type**: toggle Line ↔ Bar via the header icon.
+- **Show/Hide balance**: toggle the running balance series.
+
+## Quick troubleshooting
+
+- **No data**: check that budgets and transactions exist in the selected months and that filters aren’t excluding everything.
+- **Balance looks wrong**: verify category rollover settings and transaction categorization.
+
+## Related
+
+- [Budget page](/docs/tour/budget.md) — configure budgets and rollover settings.
+- [Reports index](/docs/reports/index.md) — other report types and tips.
diff --git a/packages/docs/static/img/experimental/budget-analysis/budget-analysis-image.webp b/packages/docs/static/img/experimental/budget-analysis/budget-analysis-image.webp
new file mode 100644
index 0000000000..8ced61f1ec
Binary files /dev/null and b/packages/docs/static/img/experimental/budget-analysis/budget-analysis-image.webp differ
diff --git a/packages/loot-core/src/server/dashboard/app.ts b/packages/loot-core/src/server/dashboard/app.ts
index d4def2d032..cf426e9a35 100644
--- a/packages/loot-core/src/server/dashboard/app.ts
+++ b/packages/loot-core/src/server/dashboard/app.ts
@@ -34,6 +34,7 @@ function isWidgetType(type: string): type is Widget['type'] {
'cash-flow-card',
'spending-card',
'crossover-card',
+ 'budget-analysis-card',
'markdown-card',
'summary-card',
'calendar-card',
diff --git a/packages/loot-core/src/types/models/dashboard.ts b/packages/loot-core/src/types/models/dashboard.ts
index 17dce9a6b3..68d2939968 100644
--- a/packages/loot-core/src/types/models/dashboard.ts
+++ b/packages/loot-core/src/types/models/dashboard.ts
@@ -69,6 +69,18 @@ export type SpendingWidget = AbstractWidget<
mode?: 'single-month' | 'budget' | 'average';
} | null
>;
+export type BudgetAnalysisWidget = AbstractWidget<
+ 'budget-analysis-card',
+ {
+ name?: string;
+ conditions?: RuleConditionEntity[];
+ conditionsOp?: 'and' | 'or';
+ timeFrame?: TimeFrame;
+ interval?: 'Daily' | 'Weekly' | 'Monthly' | 'Yearly';
+ graphType?: 'Line' | 'Bar';
+ showBalance?: boolean;
+ } | null
+>;
export type CustomReportWidget = AbstractWidget<
'custom-report',
{ id: string }
@@ -97,6 +109,7 @@ type SpecializedWidget =
| NetWorthWidget
| CashFlowWidget
| SpendingWidget
+ | BudgetAnalysisWidget
| CrossoverWidget
| MarkdownWidget
| SummaryWidget
diff --git a/packages/loot-core/src/types/prefs.ts b/packages/loot-core/src/types/prefs.ts
index 87a6271c31..59e6395380 100644
--- a/packages/loot-core/src/types/prefs.ts
+++ b/packages/loot-core/src/types/prefs.ts
@@ -5,7 +5,8 @@ export type FeatureFlag =
| 'formulaMode'
| 'currency'
| 'crossoverReport'
- | 'customThemes';
+ | 'customThemes'
+ | 'budgetAnalysisReport';
/**
* Cross-device preferences. These sync across devices when they are changed.
diff --git a/upcoming-release-notes/6137.md b/upcoming-release-notes/6137.md
new file mode 100644
index 0000000000..bf9b355c8d
--- /dev/null
+++ b/upcoming-release-notes/6137.md
@@ -0,0 +1,6 @@
+---
+category: Features
+authors: [tabedzki]
+---
+
+Add "Budget Analysis" : a report that tracks the balance of your budget categories over time. Displays budgeted amounts, actual spending, overspending adjustments, and cumulative balance, considering category rollover settings.