A local-first personal finance app
🛣️ tour: add initial tour framework (#8656)
Matt Fiddamand67ca574673f
diff --git a/packages/desktop-client/e2e/help-menu.test.ts-snapshots/Help-menu-Check-the-help-menu-visuals-1-chromium-linux.png b/packages/desktop-client/e2e/help-menu.test.ts-snapshots/Help-menu-Check-the-help-menu-visuals-1-chromium-linux.pngindex 07912ab08a..3ca32e5099 100644Binary files a/packages/desktop-client/e2e/help-menu.test.ts-snapshots/Help-menu-Check-the-help-menu-visuals-1-chromium-linux.png and b/packages/desktop-client/e2e/help-menu.test.ts-snapshots/Help-menu-Check-the-help-menu-visuals-1-chromium-linux.png differdiff --git a/packages/desktop-client/e2e/help-menu.test.ts-snapshots/Help-menu-Check-the-help-menu-visuals-2-chromium-linux.png b/packages/desktop-client/e2e/help-menu.test.ts-snapshots/Help-menu-Check-the-help-menu-visuals-2-chromium-linux.pngindex 6249ef82ae..a24ced6763 100644Binary files a/packages/desktop-client/e2e/help-menu.test.ts-snapshots/Help-menu-Check-the-help-menu-visuals-2-chromium-linux.png and b/packages/desktop-client/e2e/help-menu.test.ts-snapshots/Help-menu-Check-the-help-menu-visuals-2-chromium-linux.png differdiff --git a/packages/desktop-client/e2e/help-menu.test.ts-snapshots/Help-menu-Check-the-help-menu-visuals-3-chromium-linux.png b/packages/desktop-client/e2e/help-menu.test.ts-snapshots/Help-menu-Check-the-help-menu-visuals-3-chromium-linux.pngindex 5a7abc44ba..9d83e136eb 100644Binary files a/packages/desktop-client/e2e/help-menu.test.ts-snapshots/Help-menu-Check-the-help-menu-visuals-3-chromium-linux.png and b/packages/desktop-client/e2e/help-menu.test.ts-snapshots/Help-menu-Check-the-help-menu-visuals-3-chromium-linux.png differdiff --git a/packages/desktop-client/e2e/onboarding.test.ts b/packages/desktop-client/e2e/onboarding.test.tsindex d65f5f6ebe..77dcb4aa8a 100644--- a/packages/desktop-client/e2e/onboarding.test.ts+++ b/packages/desktop-client/e2e/onboarding.test.ts@@ -3,7 +3,6 @@ import path from 'path';import type { Page } from '@playwright/test';import { expect, test } from './fixtures';-import { AccountPage } from './page-models/account-page';import { ConfigurationPage } from './page-models/configuration-page';import { Navigation } from './page-models/navigation';@@ -107,18 +106,20 @@ test.describe('Onboarding', () => {});test('creates a new empty budget file', async () => {- await configurationPage.startFresh();+ const budgetPage = await configurationPage.startFresh();- const accountPage = new AccountPage(page);+ await expect(budgetPage.budgetTable).toBeVisible();++ const accountPage = await navigation.goToAccountPage('All accounts');await expect(accountPage.accountName).toBeVisible();await expect(accountPage.accountName).toHaveText('All Accounts');await expect(accountPage.accountBalance).toHaveText('0.00');});test('navigates back to start page by clicking on "no server" in an empty budget file', async () => {- const accountPage = await configurationPage.startFresh();+ const budgetPage = await configurationPage.startFresh();- await expect(accountPage.transactionTable).toBeVisible();+ await expect(budgetPage.budgetTable).toBeVisible();await navigation.clickOnNoServer();await page.getByRole('button', { name: 'Start using a server' }).click();diff --git a/packages/desktop-client/e2e/page-models/configuration-page.ts b/packages/desktop-client/e2e/page-models/configuration-page.tsindex c692381cea..b08b2f1f99 100644--- a/packages/desktop-client/e2e/page-models/configuration-page.ts+++ b/packages/desktop-client/e2e/page-models/configuration-page.ts@@ -1,6 +1,5 @@import type { Locator, Page } from '@playwright/test';-import { AccountPage } from './account-page';import { BootstrapPage } from './bootstrap-page';import { BudgetPage } from './budget-page';@@ -51,9 +50,9 @@ export class ConfigurationPage {async startFresh() {await this.page.getByRole('button', { name: 'Start budgeting' }).click();- const accountPage = new AccountPage(this.page);- await accountPage.accountName.waitFor();- return accountPage;+ const budgetPage = new BudgetPage(this.page);+ await budgetPage.waitFor();+ return budgetPage;}async importBudget(type: 'YNAB4' | 'nYNAB' | 'Actual', file: string) {diff --git a/packages/desktop-client/e2e/tour.test.ts b/packages/desktop-client/e2e/tour.test.tsnew file mode 100644index 0000000000..bbb014ca97--- /dev/null+++ b/packages/desktop-client/e2e/tour.test.ts@@ -0,0 +1,56 @@+import type { Page } from '@playwright/test';++import { expect, test } from './fixtures';+import { ConfigurationPage } from './page-models/configuration-page';++test.describe('Tour', () => {+ let page: Page;+ let configurationPage: ConfigurationPage;++ test.beforeEach(async ({ browser }) => {+ page = await browser.newPage();+ configurationPage = new ConfigurationPage(page);++ await page.goto('/');+ await configurationPage.createTestFile();+ });++ test.afterEach(async () => {+ await page?.close();+ });++ async function startTourFromHelpMenu() {+ await page.getByRole('button', { name: 'Help' }).click();+ await page.getByText('Take a tour').click();+ return page.getByTestId('tour-tooltip');+ }++ test('walks through every step of the tour', async () => {+ const tooltip = await startTourFromHelpMenu();++ await expect(tooltip).toBeVisible();+ await expect(tooltip).toContainText('Welcome to Actual!');++ const counter = tooltip.getByText(/^\d+ of \d+$/);+ await expect(counter).toBeVisible();+ const total = Number((await counter.textContent())?.match(/of (\d+)/)?.[1]);+ expect(total).toBeGreaterThan(1);++ for (let step = 2; step <= total; step++) {+ await tooltip.getByRole('button', { name: 'Next', exact: true }).click();+ await expect(counter).toHaveText(`${step} of ${total}`);+ }++ await expect(tooltip).toContainText('Getting Help');+ await tooltip.getByRole('button', { name: 'Finish' }).click();+ await expect(tooltip).not.toBeVisible();+ });++ test('skipping the tour dismisses it', async () => {+ const tooltip = await startTourFromHelpMenu();++ await expect(tooltip).toBeVisible();+ await tooltip.getByRole('button', { name: 'Skip tour' }).click();+ await expect(tooltip).not.toBeVisible();+ });+});diff --git a/packages/desktop-client/package.json b/packages/desktop-client/package.jsonindex 6627a598d7..207678fd82 100644--- a/packages/desktop-client/package.json+++ b/packages/desktop-client/package.json@@ -193,6 +193,7 @@"react-grid-layout": "^2.2.3","react-hotkeys-hook": "^5.3.3","react-i18next": "^17.0.10",+ "react-joyride": "^3.2.0","react-markdown": "^10.1.0","react-redux": "^9.3.0","react-router": "8.3.0",diff --git a/packages/desktop-client/src/components/CommandBar.tsx b/packages/desktop-client/src/components/CommandBar.tsxindex c7d8f37934..e38eb104a9 100644--- a/packages/desktop-client/src/components/CommandBar.tsx+++ b/packages/desktop-client/src/components/CommandBar.tsx@@ -14,6 +14,7 @@ import {} from '@actual-app/components/icons/v1';import {SvgCalendar3,+ SvgHelp,SvgNotesPaperText,} from '@actual-app/components/icons/v2';import { styles } from '@actual-app/components/styles';@@ -37,6 +38,7 @@ import {} from '#spreadsheet/bindings';import { CellValue, CellValueText } from './spreadsheet/CellValue';+import { useTour } from './tour/TourProvider';type SearchableItem = {id: string;@@ -97,6 +99,7 @@ export function CommandBar() {const navigate = useNavigate();const [budgetName] = useMetadataPref('budgetName');const { modalStack } = useModalState();+ const { startTour } = useTour();const navigationItems = useMemo(() => [@@ -236,6 +239,21 @@ export function CommandBar() {})),onSelect: ({ id }) => handleNavigate(`/reports/custom/${id}`),},+ {+ key: 'help',+ heading: t('Help'),+ items: [+ {+ id: 'start-tour',+ name: t('Take a tour of {{appName}}', { appName: 'Actual' }),+ Icon: SvgHelp,+ },+ ],+ onSelect: () => {+ setOpen(false);+ startTour();+ },+ },];const searchLower = search.toLowerCase();diff --git a/packages/desktop-client/src/components/FinancesApp.tsx b/packages/desktop-client/src/components/FinancesApp.tsxindex 12019d70f4..fea3a4042b 100644--- a/packages/desktop-client/src/components/FinancesApp.tsx+++ b/packages/desktop-client/src/components/FinancesApp.tsx@@ -12,7 +12,6 @@ import * as undo from '@actual-app/core/platform/client/undo';import { getLatestAppVersion, sync } from '#app/appSlice';import { ProtectedRoute } from '#auth/ProtectedRoute';import { Permissions } from '#auth/types';-import { useAccounts } from '#hooks/useAccounts';import { useGlobalPref } from '#hooks/useGlobalPref';import { useLocalPref } from '#hooks/useLocalPref';import { useMetaThemeColor } from '#hooks/useMetaThemeColor';@@ -35,13 +34,15 @@ import { TransactionEdit } from './mobile/transactions/TransactionEdit';import { Notifications } from './Notifications';import { MobilePageHeaderProvider, MobilePageHeaderSlot } from './Page';import { Reports } from './reports';-import { LoadingIndicator } from './reports/LoadingIndicator';import { NarrowAlternate, WideComponent } from './responsive';import { useMultiuserEnabled } from './ServerContext';import { Settings } from './settings';import { FloatableSidebar } from './sidebar';import { ManageTagsPage } from './tags/ManageTagsPage';import { Titlebar } from './Titlebar';+import { Tour } from './tour/Tour';+import { TourAutoOffer } from './tour/TourAutoOffer';+import { TourProvider } from './tour/TourProvider';function NarrowNotSupported({redirectTo = '/budget',@@ -95,8 +96,6 @@ export function FinancesApp() {const dispatch = useDispatch();const { t } = useTranslation();- const { data: accounts, isFetching: isAccountsFetching } = useAccounts();-const versionInfo = useSelector(state => state.app.versionInfo);const [notifyWhenUpdateIsAvailable] = useGlobalPref('notifyWhenUpdateIsAvailable',@@ -195,297 +194,291 @@ export function FinancesApp() {const scrollableRef = useRef<HTMLDivElement>(null);return (- <View style={{ height: '100%' }}>- <RouterBehaviors />- <GlobalKeys />- <CommandBar />- <ContextMenu />- <View- style={{- flexDirection: 'row',- backgroundColor: theme.pageBackground,- flex: 1,- }}- >- <FloatableSidebar />-+ <TourProvider>+ <View style={{ height: '100%' }}>+ <RouterBehaviors />+ <GlobalKeys />+ <CommandBar />+ <ContextMenu />+ <TourAutoOffer />+ <Tour /><Viewstyle={{- color: theme.pageText,+ flexDirection: 'row',backgroundColor: theme.pageBackground,flex: 1,- overflow: 'hidden',- width: '100%',}}>- <ScrollProvider- isDisabled={!isNarrowWidth}- scrollableRef={scrollableRef}+ <FloatableSidebar />++ <View+ style={{+ color: theme.pageText,+ backgroundColor: theme.pageBackground,+ flex: 1,+ overflow: 'hidden',+ width: '100%',+ }}>- <MobilePageHeaderProvider>- <View- ref={scrollableRef}- style={{- flex: 1,- overflow: 'auto',- position: 'relative',- }}- >- <Titlebar+ <ScrollProvider+ isDisabled={!isNarrowWidth}+ scrollableRef={scrollableRef}+ >+ <MobilePageHeaderProvider>+ <View+ ref={scrollableRef}style={{- WebkitAppRegion: 'drag',- position: 'absolute',- top: 0,- left: 0,- right: 0,- zIndex: 1000,+ flex: 1,+ overflow: 'auto',+ position: 'relative',}}- />- <Notifications />- <BankSyncStatus />- {isNarrowWidth && <MobilePageHeaderSlot />}-- <Routes>- <Route- path="/"- element={- isAccountsFetching || !accounts ? (- <LoadingIndicator />- ) : accounts.length > 0 ? (- <Navigate to="/budget" replace />- ) : (- // If there are no accounts, we want to redirect the user to- // the All Accounts screen which will prompt them to add an account- <Navigate to="/accounts" replace />- )- }+ >+ <Titlebar+ style={{+ WebkitAppRegion: 'drag',+ position: 'absolute',+ top: 0,+ left: 0,+ right: 0,+ zIndex: 1000,+ }}/>+ <Notifications />+ <BankSyncStatus />+ {isNarrowWidth && <MobilePageHeaderSlot />}- <Route path="/reports/*" element={<Reports />} />+ <Routes>+ <Route+ path="/"+ element={<Navigate to="/budget" replace />}+ />- <Route- path="/budget"- element={- <ErrorBoundary- FallbackComponent={FeatureErrorFallback}- resetKeys={[location.pathname]}- >- <NarrowAlternate name="Budget" />- </ErrorBoundary>- }- />+ <Route path="/reports/*" element={<Reports />} />- <Route- path="/schedules"- element={- <ErrorBoundary- FallbackComponent={FeatureErrorFallback}- resetKeys={[location.pathname]}- >- <NarrowAlternate name="Schedules" />- </ErrorBoundary>- }- />- <Route- path="/schedules/:id"- element={- <ErrorBoundary- FallbackComponent={FeatureErrorFallback}- resetKeys={[location.pathname]}- >- <WideNotSupported>- <NarrowAlternate name="ScheduleEdit" />- </WideNotSupported>- </ErrorBoundary>- }- />+ <Route+ path="/budget"+ element={+ <ErrorBoundary+ FallbackComponent={FeatureErrorFallback}+ resetKeys={[location.pathname]}+ >+ <NarrowAlternate name="Budget" />+ </ErrorBoundary>+ }+ />- <Route- path="/payees"- element={- <ErrorBoundary- FallbackComponent={FeatureErrorFallback}- resetKeys={[location.pathname]}- >- <NarrowAlternate name="Payees" />- </ErrorBoundary>- }- />- <Route- path="/payees/:id"- element={- <ErrorBoundary- FallbackComponent={FeatureErrorFallback}- resetKeys={[location.pathname]}- >- <WideNotSupported>- <NarrowAlternate name="PayeeEdit" />- </WideNotSupported>- </ErrorBoundary>- }- />- <Route- path="/rules"- element={- <ErrorBoundary- FallbackComponent={FeatureErrorFallback}- resetKeys={[location.pathname]}- >- <NarrowAlternate name="Rules" />- </ErrorBoundary>- }- />- <Route- path="/rules/:id"- element={- <ErrorBoundary- FallbackComponent={FeatureErrorFallback}- resetKeys={[location.pathname]}- >- <NarrowAlternate name="RuleEdit" />- </ErrorBoundary>- }- />- <Route- path="/bank-sync"- element={- <ErrorBoundary- FallbackComponent={FeatureErrorFallback}- resetKeys={[location.pathname]}- >- <NarrowAlternate name="BankSync" />- </ErrorBoundary>- }- />- <Route- path="/bank-sync/account/:accountId/edit"- element={- <ErrorBoundary- FallbackComponent={FeatureErrorFallback}- resetKeys={[location.pathname]}- >- <WideNotSupported redirectTo="/bank-sync">- <MobileBankSyncAccountEditPage />- </WideNotSupported>- </ErrorBoundary>- }- />- <Route path="/tags" element={<ManageTagsPage />} />- <Route path="/settings" element={<Settings />} />+ <Route+ path="/schedules"+ element={+ <ErrorBoundary+ FallbackComponent={FeatureErrorFallback}+ resetKeys={[location.pathname]}+ >+ <NarrowAlternate name="Schedules" />+ </ErrorBoundary>+ }+ />+ <Route+ path="/schedules/:id"+ element={+ <ErrorBoundary+ FallbackComponent={FeatureErrorFallback}+ resetKeys={[location.pathname]}+ >+ <WideNotSupported>+ <NarrowAlternate name="ScheduleEdit" />+ </WideNotSupported>+ </ErrorBoundary>+ }+ />- <Route- path="/gocardless/link"- element={- <NarrowNotSupported>- <WideComponent name="GoCardlessLink" />- </NarrowNotSupported>- }- />+ <Route+ path="/payees"+ element={+ <ErrorBoundary+ FallbackComponent={FeatureErrorFallback}+ resetKeys={[location.pathname]}+ >+ <NarrowAlternate name="Payees" />+ </ErrorBoundary>+ }+ />+ <Route+ path="/payees/:id"+ element={+ <ErrorBoundary+ FallbackComponent={FeatureErrorFallback}+ resetKeys={[location.pathname]}+ >+ <WideNotSupported>+ <NarrowAlternate name="PayeeEdit" />+ </WideNotSupported>+ </ErrorBoundary>+ }+ />+ <Route+ path="/rules"+ element={+ <ErrorBoundary+ FallbackComponent={FeatureErrorFallback}+ resetKeys={[location.pathname]}+ >+ <NarrowAlternate name="Rules" />+ </ErrorBoundary>+ }+ />+ <Route+ path="/rules/:id"+ element={+ <ErrorBoundary+ FallbackComponent={FeatureErrorFallback}+ resetKeys={[location.pathname]}+ >+ <NarrowAlternate name="RuleEdit" />+ </ErrorBoundary>+ }+ />+ <Route+ path="/bank-sync"+ element={+ <ErrorBoundary+ FallbackComponent={FeatureErrorFallback}+ resetKeys={[location.pathname]}+ >+ <NarrowAlternate name="BankSync" />+ </ErrorBoundary>+ }+ />+ <Route+ path="/bank-sync/account/:accountId/edit"+ element={+ <ErrorBoundary+ FallbackComponent={FeatureErrorFallback}+ resetKeys={[location.pathname]}+ >+ <WideNotSupported redirectTo="/bank-sync">+ <MobileBankSyncAccountEditPage />+ </WideNotSupported>+ </ErrorBoundary>+ }+ />+ <Route path="/tags" element={<ManageTagsPage />} />+ <Route path="/settings" element={<Settings />} />- <Route- path="/enablebanking/auth_callback"- element={<EnableBankingCallback />}- />+ <Route+ path="/gocardless/link"+ element={+ <NarrowNotSupported>+ <WideComponent name="GoCardlessLink" />+ </NarrowNotSupported>+ }+ />- <Route- path="/accounts"- element={- <ErrorBoundary- FallbackComponent={FeatureErrorFallback}- resetKeys={[location.pathname]}- >- <NarrowAlternate name="Accounts" />- </ErrorBoundary>- }- />+ <Route+ path="/enablebanking/auth_callback"+ element={<EnableBankingCallback />}+ />- <Route- path="/accounts/:id"- element={- <ErrorBoundary- FallbackComponent={FeatureErrorFallback}- resetKeys={[location.pathname]}- >- <NarrowAlternate name="Account" />- </ErrorBoundary>- }- />+ <Route+ path="/accounts"+ element={+ <ErrorBoundary+ FallbackComponent={FeatureErrorFallback}+ resetKeys={[location.pathname]}+ >+ <NarrowAlternate name="Accounts" />+ </ErrorBoundary>+ }+ />- <Route- path="/transactions/:transactionId"- element={- <ErrorBoundary- FallbackComponent={FeatureErrorFallback}- resetKeys={[location.pathname]}- >- <WideNotSupported>- <TransactionEdit />- </WideNotSupported>- </ErrorBoundary>- }- />+ <Route+ path="/accounts/:id"+ element={+ <ErrorBoundary+ FallbackComponent={FeatureErrorFallback}+ resetKeys={[location.pathname]}+ >+ <NarrowAlternate name="Account" />+ </ErrorBoundary>+ }+ />- <Route- path="/categories/:id"- element={- <ErrorBoundary- FallbackComponent={FeatureErrorFallback}- resetKeys={[location.pathname]}- >- <NarrowAlternate name="Category" />- </ErrorBoundary>- }- />- {multiuserEnabled && (<Route- path="/user-directory"+ path="/transactions/:transactionId"element={- <ProtectedRoute- permission={Permissions.ADMINISTRATOR}- element={<UserDirectoryPage />}- />+ <ErrorBoundary+ FallbackComponent={FeatureErrorFallback}+ resetKeys={[location.pathname]}+ >+ <WideNotSupported>+ <TransactionEdit />+ </WideNotSupported>+ </ErrorBoundary>}/>- )}- {multiuserEnabled && (+<Route- path="/user-access"+ path="/categories/:id"element={- <ProtectedRoute- permission={Permissions.ADMINISTRATOR}- validateOwner- element={<UserAccessPage />}- />+ <ErrorBoundary+ FallbackComponent={FeatureErrorFallback}+ resetKeys={[location.pathname]}+ >+ <NarrowAlternate name="Category" />+ </ErrorBoundary>}/>- )}- {/* redirect all other traffic to the budget page */}+ {multiuserEnabled && (+ <Route+ path="/user-directory"+ element={+ <ProtectedRoute+ permission={Permissions.ADMINISTRATOR}+ element={<UserDirectoryPage />}+ />+ }+ />+ )}+ {multiuserEnabled && (+ <Route+ path="/user-access"+ element={+ <ProtectedRoute+ permission={Permissions.ADMINISTRATOR}+ validateOwner+ element={<UserAccessPage />}+ />+ }+ />+ )}+ {/* redirect all other traffic to the budget page */}+ <Route+ path="/*"+ element={<Navigate to="/budget" replace />}+ />+ </Routes>+ </View>++ <Routes>+ <Route path="/budget" element={<MobileNavTabs />} />+ <Route path="/accounts" element={<MobileNavTabs />} />+ <Route path="/settings" element={<MobileNavTabs />} />+ <Route path="/reports" element={<MobileNavTabs />} /><Route- path="/*"- element={<Navigate to="/budget" replace />}+ path="/reports/:dashboardId"+ element={<MobileNavTabs />}/>+ <Route path="/bank-sync" element={<MobileNavTabs />} />+ <Route path="/rules" element={<MobileNavTabs />} />+ <Route path="/payees" element={<MobileNavTabs />} />+ <Route path="/schedules" element={<MobileNavTabs />} />+ <Route path="*" element={null} /></Routes>- </View>-- <Routes>- <Route path="/budget" element={<MobileNavTabs />} />- <Route path="/accounts" element={<MobileNavTabs />} />- <Route path="/settings" element={<MobileNavTabs />} />- <Route path="/reports" element={<MobileNavTabs />} />- <Route- path="/reports/:dashboardId"- element={<MobileNavTabs />}- />- <Route path="/bank-sync" element={<MobileNavTabs />} />- <Route path="/rules" element={<MobileNavTabs />} />- <Route path="/payees" element={<MobileNavTabs />} />- <Route path="/schedules" element={<MobileNavTabs />} />- <Route path="*" element={null} />- </Routes>- </MobilePageHeaderProvider>- </ScrollProvider>+ </MobilePageHeaderProvider>+ </ScrollProvider>+ </View></View></View>- </View>+ </TourProvider>);}diff --git a/packages/desktop-client/src/components/HelpMenu.tsx b/packages/desktop-client/src/components/HelpMenu.tsxindex 51b626efb8..f3fec9be5a 100644--- a/packages/desktop-client/src/components/HelpMenu.tsx+++ b/packages/desktop-client/src/components/HelpMenu.tsx@@ -14,6 +14,8 @@ import { useFeatureFlag } from '#hooks/useFeatureFlag';import { pushModal } from '#modals/modalsSlice';import { useDispatch } from '#redux';+import { useTour } from './tour/TourProvider';+const getPageDocs = (page: string) => {switch (page) {case '/budget':@@ -42,6 +44,7 @@ type HelpMenuItem =| 'docs'| 'discord'| 'keyboard-shortcuts'+ | 'start-tour'| 'goal-templates';type HelpButtonProps = {@@ -56,6 +59,7 @@ const HelpButton = forwardRef<HTMLButtonElement, HelpButtonProps>(variant="bare"ref={ref}onPress={onPress}+ data-testid="help-menu-button"style={{display: 'flex',alignItems: 'center',@@ -79,6 +83,7 @@ export const HelpMenu = () => {const dispatch = useDispatch();const page = useLocation().pathname;+ const { startTour } = useTour();const handleItemSelect = (item: HelpMenuItem) => {switch (item) {@@ -91,6 +96,9 @@ export const HelpMenu = () => {case 'keyboard-shortcuts':dispatch(pushModal({ modal: { name: 'keyboard-shortcuts' } }));break;+ case 'start-tour':+ startTour();+ break;case 'goal-templates':dispatch(pushModal({ modal: { name: 'goal-templates' } }));break;@@ -127,6 +135,7 @@ export const HelpMenu = () => {text: t('Community support (Discord)'),},{ name: 'keyboard-shortcuts', text: t('Keyboard shortcuts') },+ { name: 'start-tour', text: t('Take a tour') },...(showGoalTemplates && page === '/budget'? [{ name: 'goal-templates', text: t('Goal templates') }]: []),diff --git a/packages/desktop-client/src/components/budget/envelope/budgetsummary/BudgetSummary.tsx b/packages/desktop-client/src/components/budget/envelope/budgetsummary/BudgetSummary.tsxindex 8f92a2f344..c3c8598a8a 100644--- a/packages/desktop-client/src/components/budget/envelope/budgetsummary/BudgetSummary.tsx+++ b/packages/desktop-client/src/components/budget/envelope/budgetsummary/BudgetSummary.tsx@@ -64,6 +64,7 @@ export const BudgetSummary = memo(({ month }: BudgetSummaryProps) => {return (<Viewdata-testid="budget-summary"+ data-month={month}style={{backgroundColor:month === currentMonthdiff --git a/packages/desktop-client/src/components/budget/tracking/budgetsummary/BudgetSummary.tsx b/packages/desktop-client/src/components/budget/tracking/budgetsummary/BudgetSummary.tsxindex 5e80c93bdb..6ca87c534b 100644--- a/packages/desktop-client/src/components/budget/tracking/budgetsummary/BudgetSummary.tsx+++ b/packages/desktop-client/src/components/budget/tracking/budgetsummary/BudgetSummary.tsx@@ -60,6 +60,8 @@ export function BudgetSummary({ month }: BudgetSummaryProps) {return (<View+ data-testid="budget-summary"+ data-month={month}style={{backgroundColor:month === currentMonthdiff --git a/packages/desktop-client/src/components/sidebar/PrimaryButtons.tsx b/packages/desktop-client/src/components/sidebar/PrimaryButtons.tsxindex 1615d22aef..2302405160 100644--- a/packages/desktop-client/src/components/sidebar/PrimaryButtons.tsx+++ b/packages/desktop-client/src/components/sidebar/PrimaryButtons.tsx@@ -47,7 +47,7 @@ export function PrimaryButtons() {}, [isActive, location.pathname]);return (- <View style={{ flexShrink: 0 }}>+ <View data-testid="sidebar-primary-buttons" style={{ flexShrink: 0 }}><Item title={t('Budget')} Icon={SvgWallet} to="/budget" /><Item title={t('Reports')} Icon={SvgReports} to="/reports" /><Item title={t('Schedules')} Icon={SvgCalendar3} to="/schedules" />diff --git a/packages/desktop-client/src/components/sidebar/SecondaryButtons.tsx b/packages/desktop-client/src/components/sidebar/SecondaryButtons.tsxindex 00e6e56ee0..4f330f93d9 100644--- a/packages/desktop-client/src/components/sidebar/SecondaryButtons.tsx+++ b/packages/desktop-client/src/components/sidebar/SecondaryButtons.tsx@@ -11,6 +11,7 @@ type SecondaryButtonItems = {| ComponentType<SVGProps<SVGElement>>| ComponentType<SVGProps<SVGSVGElement>>;onClick: () => void;+ dataTestId?: string;};type SecondaryButtonsProps = {@@ -31,6 +32,7 @@ export function SecondaryButtons({ buttons }: SecondaryButtonsProps) {title={item.title}Icon={item.Icon}onClick={item.onClick}+ dataTestId={item.dataTestId}/>))}</View>diff --git a/packages/desktop-client/src/components/sidebar/SecondaryItem.tsx b/packages/desktop-client/src/components/sidebar/SecondaryItem.tsxindex ad5eb2b8b0..538a22f5d0 100644--- a/packages/desktop-client/src/components/sidebar/SecondaryItem.tsx+++ b/packages/desktop-client/src/components/sidebar/SecondaryItem.tsx@@ -26,6 +26,7 @@ type SecondaryItemProps = {onClick?: ComponentProps<typeof ItemContent>['onClick'];bold?: boolean;indent?: number;+ dataTestId?: string;};export function SecondaryItem({@@ -36,6 +37,7 @@ export function SecondaryItem({onClick,bold,indent = 0,+ dataTestId,}: SecondaryItemProps) {const content = (<View@@ -53,7 +55,7 @@ export function SecondaryItem({);return (- <View style={{ flexShrink: 0, ...style }}>+ <View data-testid={dataTestId} style={{ flexShrink: 0, ...style }}><ItemContentstyle={{...accountNameStyle,diff --git a/packages/desktop-client/src/components/sidebar/Sidebar.tsx b/packages/desktop-client/src/components/sidebar/Sidebar.tsxindex 1cd658eac0..3b0136021f 100644--- a/packages/desktop-client/src/components/sidebar/Sidebar.tsx+++ b/packages/desktop-client/src/components/sidebar/Sidebar.tsx@@ -132,6 +132,7 @@ export function Sidebar() {title: t('Add account'),Icon: SvgAdd,onClick: onAddAccount,+ dataTestId: 'sidebar-add-account',},]}/>diff --git a/packages/desktop-client/src/components/tour/Tour.tsx b/packages/desktop-client/src/components/tour/Tour.tsxnew file mode 100644index 0000000000..595ccac244--- /dev/null+++ b/packages/desktop-client/src/components/tour/Tour.tsx@@ -0,0 +1,21 @@+import { lazy, Suspense } from 'react';++import { useTour } from './TourProvider';++const TourHost = lazy(() =>+ import('./TourHost').then(module => ({ default: module.TourHost })),+);++export function Tour() {+ const { activeTourId } = useTour();++ if (activeTourId == null) {+ return null;+ }++ return (+ <Suspense fallback={null}>+ <TourHost tourId={activeTourId} />+ </Suspense>+ );+}diff --git a/packages/desktop-client/src/components/tour/TourAutoOffer.ts b/packages/desktop-client/src/components/tour/TourAutoOffer.tsnew file mode 100644index 0000000000..010474c347--- /dev/null+++ b/packages/desktop-client/src/components/tour/TourAutoOffer.ts@@ -0,0 +1,57 @@+import { useEffect, useRef } from 'react';+import { useTranslation } from 'react-i18next';++import { useResponsive } from '@actual-app/components/hooks/useResponsive';++import { useIsTestEnv } from '#hooks/useIsTestEnv';+import { useLocalPref } from '#hooks/useLocalPref';+import { addNotification } from '#notifications/notificationsSlice';+import { useDispatch } from '#redux';++import { TOUR_OFFER_NOTIFICATION_ID, useTour } from './TourProvider';++export function TourAutoOffer() {+ const { t } = useTranslation();+ const dispatch = useDispatch();+ const { isNarrowWidth } = useResponsive();+ const isTestEnv = useIsTestEnv();+ const { startTour } = useTour();+ const [introSeen, setIntroSeen] = useLocalPref('tour.introSeen');+ const hasOffered = useRef(false);++ useEffect(() => {+ if (hasOffered.current || introSeen || isNarrowWidth || isTestEnv) {+ return;+ }+ hasOffered.current = true;+ dispatch(+ addNotification({+ notification: {+ id: TOUR_OFFER_NOTIFICATION_ID,+ type: 'message',+ sticky: true,+ title: t('Welcome to {{appName}}!', { appName: 'Actual' }),+ message: t(+ 'New to {{appName}}? Take a short tour to learn how budgeting works and find your way around.',+ { appName: 'Actual' },+ ),+ button: {+ title: t('Take the tour'),+ action: () => startTour(),+ },+ onClose: () => setIntroSeen(true),+ },+ }),+ );+ }, [+ dispatch,+ introSeen,+ isNarrowWidth,+ isTestEnv,+ setIntroSeen,+ startTour,+ t,+ ]);++ return null;+}diff --git a/packages/desktop-client/src/components/tour/TourHost.ts b/packages/desktop-client/src/components/tour/TourHost.tsnew file mode 100644index 0000000000..1adca28236--- /dev/null+++ b/packages/desktop-client/src/components/tour/TourHost.ts@@ -0,0 +1,122 @@+import { useEffect, useEffectEvent, useRef } from 'react';+import { useTranslation } from 'react-i18next';+import { useJoyride } from 'react-joyride';+import type { Controls, EventData } from 'react-joyride';++import { theme } from '@actual-app/components/theme';++import { useLocalPref } from '#hooks/useLocalPref';+import { useModalState } from '#hooks/useModalState';+import { useNavigate } from '#hooks/useNavigate';+import { useReducedMotion } from '#hooks/useReducedMotion';+import { useSyncedPref } from '#hooks/useSyncedPref';+import { removeNotification } from '#notifications/notificationsSlice';+import { useDispatch } from '#redux';++import { ADD_ACCOUNT_STEP_ID, getTourSteps } from './steps';+import { TOUR_OFFER_NOTIFICATION_ID, useTour } from './TourProvider';+import type { TourId } from './TourProvider';+import { TourTooltip } from './TourTooltip';++// Must stay below MODAL_Z_INDEX (3000) and the notifications layer (2999).+const TOUR_Z_INDEX = 2900;++type TourHostProps = {+ tourId: TourId;+};++export function TourHost({ tourId }: TourHostProps) {+ const { t } = useTranslation();+ const dispatch = useDispatch();+ const { stopTour } = useTour();+ const [, setIntroSeen] = useLocalPref('tour.introSeen');+ const { activeModal, modalStack } = useModalState();+ const reducedMotion = useReducedMotion();+ const navigate = useNavigate();+ const [budgetTypePref] = useSyncedPref('budgetType');+ const pausedAtIndexRef = useRef<number | null>(null);++ const steps = getTourSteps(tourId, {+ navigate,+ budgetType: budgetTypePref === 'tracking' ? 'tracking' : 'envelope',+ });++ const completeTour = () => {+ setIntroSeen(true);+ stopTour();+ };++ const handleEvent = (data: EventData, controls: Controls) => {+ if (data.type === 'error:target_not_found') {+ controls.next();+ } else if (+ data.type === 'tour:end' &&+ (data.status === 'finished' || data.status === 'skipped')+ ) {+ completeTour();+ } else if (data.action === 'close' && data.origin === 'keyboard') {+ controls.skip();+ }+ };++ const { controls, Tour } = useJoyride({+ continuous: true,+ run: true,+ steps,+ onEvent: handleEvent,+ tooltipComponent: TourTooltip,+ locale: {+ back: t('Back'),+ close: t('Close'),+ last: t('Finish'),+ next: t('Next'),+ skip: t('Skip tour'),+ },+ options: {+ arrowColor: theme.menuBackground,+ backgroundColor: theme.menuBackground,+ closeButtonAction: 'skip',+ dismissKeyAction: 'close',+ overlayClickAction: false,+ overlayColor: 'rgba(0, 0, 0, 0.5)',+ scrollDuration: reducedMotion ? 0 : 300,+ skipBeacon: true,+ spotlightPadding: 6,+ targetWaitTimeout: 5000,+ textColor: theme.pageText,+ zIndex: TOUR_Z_INDEX,+ },+ styles: reducedMotion ? { floater: { transition: 'none' } } : undefined,+ });++ useEffect(() => {+ dispatch(removeNotification({ id: TOUR_OFFER_NOTIFICATION_ID }));+ }, [dispatch]);++ const syncTourWithModals = useEffectEvent((modalCount: number) => {+ if (modalCount > 0) {+ const state = controls.info();+ if (state.status !== 'running') {+ return;+ }+ if (+ activeModal === 'add-account' &&+ steps[state.index]?.id === ADD_ACCOUNT_STEP_ID+ ) {+ completeTour();+ return;+ }+ pausedAtIndexRef.current = state.index;+ controls.stop();+ } else if (pausedAtIndexRef.current != null) {+ const resumeIndex = pausedAtIndexRef.current;+ pausedAtIndexRef.current = null;+ controls.start(resumeIndex);+ }+ });++ const modalCount = modalStack.length;+ useEffect(() => syncTourWithModals(modalCount), [modalCount]);++ return Tour;+}diff --git a/packages/desktop-client/src/components/tour/TourProvider.test.tsx b/packages/desktop-client/src/components/tour/TourProvider.test.tsxnew file mode 100644index 0000000000..80e35cf5a2--- /dev/null+++ b/packages/desktop-client/src/components/tour/TourProvider.test.tsx@@ -0,0 +1,37 @@+import type { ReactNode } from 'react';++import { act, renderHook } from '@testing-library/react';+import { describe, expect, it } from 'vitest';++import { TourProvider, useTour } from './TourProvider';++function wrapper({ children }: { children: ReactNode }) {+ return <TourProvider>{children}</TourProvider>;+}++describe('TourProvider', () => {+ it('starts and stops the tour', () => {+ const { result } = renderHook(() => useTour(), { wrapper });++ expect(result.current.activeTourId).toBeNull();++ act(() => result.current.startTour());+ expect(result.current.activeTourId).toBe('budget-tour');++ act(() => result.current.stopTour());+ expect(result.current.activeTourId).toBeNull();+ });++ it('does not start the tour on narrow screens', () => {+ const originalWidth = window.innerWidth;+ window.innerWidth = 400;+ try {+ const { result } = renderHook(() => useTour(), { wrapper });++ act(() => result.current.startTour());+ expect(result.current.activeTourId).toBeNull();+ } finally {+ window.innerWidth = originalWidth;+ }+ });+});diff --git a/packages/desktop-client/src/components/tour/TourProvider.tsx b/packages/desktop-client/src/components/tour/TourProvider.tsxnew file mode 100644index 0000000000..88244b7870--- /dev/null+++ b/packages/desktop-client/src/components/tour/TourProvider.tsx@@ -0,0 +1,50 @@+import { createContext, useContext, useState } from 'react';+import type { ReactNode } from 'react';++import { useResponsive } from '@actual-app/components/hooks/useResponsive';++export type TourId = 'budget-tour';++export const TOUR_OFFER_NOTIFICATION_ID = 'tour-offer';++type TourContextValue = {+ activeTourId: TourId | null;+ startTour: (tourId?: TourId) => void;+ stopTour: () => void;+};++const TourContext = createContext<TourContextValue | null>(null);++type TourProviderProps = {+ children: ReactNode;+};++export function TourProvider({ children }: TourProviderProps) {+ const { isNarrowWidth } = useResponsive();+ const [activeTourId, setActiveTourId] = useState<TourId | null>(null);++ const startTour = (tourId: TourId = 'budget-tour') => {+ if (isNarrowWidth) {+ return;+ }+ setActiveTourId(tourId);+ };++ const stopTour = () => {+ setActiveTourId(null);+ };++ return (+ <TourContext.Provider value={{ activeTourId, startTour, stopTour }}>+ {children}+ </TourContext.Provider>+ );+}++export function useTour(): TourContextValue {+ const context = useContext(TourContext);+ if (!context) {+ throw new Error('useTour must be used within a TourProvider');+ }+ return context;+}diff --git a/packages/desktop-client/src/components/tour/TourTooltip.tsx b/packages/desktop-client/src/components/tour/TourTooltip.tsxnew file mode 100644index 0000000000..9f5fec7924--- /dev/null+++ b/packages/desktop-client/src/components/tour/TourTooltip.tsx@@ -0,0 +1,91 @@+import { useTranslation } from 'react-i18next';+import type { TooltipRenderProps } from 'react-joyride';++import { SvgDelete } from '@actual-app/components/icons/v0';+import { styles } from '@actual-app/components/styles';+import { Text } from '@actual-app/components/text';+import { theme } from '@actual-app/components/theme';+import { View } from '@actual-app/components/view';++import { TourTooltipButton } from './TourTooltipButton';++export function TourTooltip({+ backProps,+ closeProps,+ index,+ isLastStep,+ primaryProps,+ size,+ skipProps,+ step,+ tooltipProps,+}: TooltipRenderProps) {+ const { t } = useTranslation();++ return (+ <View+ {...tooltipProps}+ data-testid="tour-tooltip"+ style={{+ backgroundColor: theme.menuBackground,+ borderRadius: 8,+ color: theme.pageText,+ maxWidth: 360,+ padding: 16,+ ...styles.shadowLarge,+ }}+ >+ <TourTooltipButton+ handleProps={closeProps}+ style={{+ color: theme.pageTextSubdued,+ padding: 6,+ position: 'absolute',+ right: 8,+ top: 8,+ }}+ >+ <SvgDelete style={{ width: 9, height: 9 }} />+ </TourTooltipButton>++ {step.title != null && (+ <Text+ style={{+ ...styles.mediumText,+ fontWeight: 700,+ marginBottom: 8,+ paddingRight: 24,+ }}+ >+ {step.title}+ </Text>+ )}++ <Text style={{ lineHeight: '1.4em' }}>{step.content}</Text>++ <View+ style={{+ alignItems: 'center',+ flexDirection: 'row',+ gap: 10,+ marginTop: 14,+ }}+ >+ <Text style={{ color: theme.pageTextSubdued, flex: 1 }}>+ {t('{{current}} of {{total}}', {+ current: index + 1,+ total: size,+ })}+ </Text>+ {!isLastStep && (+ <TourTooltipButton+ handleProps={skipProps}+ style={{ color: theme.pageTextSubdued }}+ />+ )}+ {index > 0 && <TourTooltipButton handleProps={backProps} />}+ <TourTooltipButton handleProps={primaryProps} variant="primary" />+ </View>+ </View>+ );+}diff --git a/packages/desktop-client/src/components/tour/TourTooltipButton.tsx b/packages/desktop-client/src/components/tour/TourTooltipButton.tsxnew file mode 100644index 0000000000..4687972019--- /dev/null+++ b/packages/desktop-client/src/components/tour/TourTooltipButton.tsx@@ -0,0 +1,32 @@+import type { MouseEvent as ReactMouseEvent, ReactNode } from 'react';+import type { TooltipRenderProps } from 'react-joyride';++import { Button } from '@actual-app/components/button';+import type { CSSProperties } from '@actual-app/components/styles';++type TourTooltipButtonProps = {+ handleProps: TooltipRenderProps['primaryProps'];+ variant?: 'bare' | 'primary';+ style?: CSSProperties;+ children?: ReactNode;+};++export function TourTooltipButton({+ handleProps,+ variant = 'bare',+ style,+ children,+}: TourTooltipButtonProps) {+ const { onClick, title, ...restProps } = handleProps;++ return (+ <Button+ variant={variant}+ {...restProps}+ onClick={event => onClick(event as ReactMouseEvent<HTMLElement>)}+ style={style}+ >+ {children ?? title}+ </Button>+ );+}diff --git a/packages/desktop-client/src/components/tour/steps.test.ts b/packages/desktop-client/src/components/tour/steps.test.tsnew file mode 100644index 0000000000..b2e8f14158--- /dev/null+++ b/packages/desktop-client/src/components/tour/steps.test.ts@@ -0,0 +1,42 @@+import { describe, expect, it, vi } from 'vitest';++import { getTourSteps } from './steps';+import type { TourStepDeps } from './steps';++const deps: TourStepDeps = { navigate: vi.fn(), budgetType: 'envelope' };++describe('getTourSteps', () => {+ it('returns a tour that starts with a centered welcome step', () => {+ const steps = getTourSteps('budget-tour', deps);++ expect(steps.length).toBeGreaterThan(0);+ expect(steps[0].id).toBe('welcome');+ expect(steps[0].placement).toBe('center');+ });++ it('gives every step a unique id, a target, and content', () => {+ const steps = getTourSteps('budget-tour', deps);++ const ids = steps.map(step => step.id);+ expect(new Set(ids).size).toBe(ids.length);++ for (const step of steps) {+ expect(step.id).toBeTruthy();+ expect(step.target).toBeTruthy();+ expect(step.content).toBeTruthy();+ expect(step.title).toBeTruthy();+ }+ });++ it.each(['envelope', 'tracking'] as const)(+ 'returns a complete tour for %s budgets',+ budgetType => {+ const steps = getTourSteps('budget-tour', { ...deps, budgetType });++ const summaryStep = steps.find(step => step.id === 'budget-summary');+ expect(summaryStep?.title).toBeTruthy();+ expect(summaryStep?.content).toBeTruthy();+ expect(summaryStep?.target).toBeTruthy();+ },+ );+});diff --git a/packages/desktop-client/src/components/tour/steps.tsx b/packages/desktop-client/src/components/tour/steps.tsxnew file mode 100644index 0000000000..937bb1d9ca--- /dev/null+++ b/packages/desktop-client/src/components/tour/steps.tsx@@ -0,0 +1,218 @@+import { Trans } from 'react-i18next';+import type { Step } from 'react-joyride';++import * as monthUtils from '@actual-app/core/shared/months';++import { Link } from '#components/common/Link';++import type { TourId } from './TourProvider';++export const ADD_ACCOUNT_STEP_ID = 'add-account';++export type TourStepDeps = {+ navigate: (to: string) => void;+ budgetType: 'envelope' | 'tracking';+};++function findBudgetSummary(): HTMLElement | null {+ return (+ document.querySelector<HTMLElement>(+ `[data-testid="budget-summary"][data-month="${monthUtils.currentMonth()}"]`,+ ) ?? document.querySelector<HTMLElement>('[data-testid="budget-summary"]')+ );+}++// Must resolve within joyride's 5s beforeTimeout+function waitForElement(selector: string, timeoutMs = 4000): Promise<void> {+ return new Promise(resolve => {+ const start = Date.now();+ function check() {+ if (document.querySelector(selector) || Date.now() - start > timeoutMs) {+ resolve();+ return;+ }+ requestAnimationFrame(check);+ }+ check();+ });+}++function getBudgetTourSteps({ navigate, budgetType }: TourStepDeps): Step[] {+ return [+ {+ id: 'welcome',+ target: 'body',+ placement: 'center',+ title: <Trans>Welcome to {{ appName: 'Actual' }}!</Trans>,+ content: (+ <Trans>+ {{ appName: 'Actual' }} is a budgeting app that helps you understand+ exactly where your money goes. This short tour walks you through the+ basics. It only takes a couple of minutes, and you can leave at any+ time and replay it later from the Help menu.+ </Trans>+ ),+ },+ {+ id: 'budget-table',+ target: '[data-testid="budget-table"]',+ scrollTarget: '[data-testid="budget-table-scroll-container"]',+ placement: 'center',+ before: async () => {+ if (window.location.pathname !== '/budget') {+ navigate('/budget');+ }+ await waitForElement('[data-testid="budget-table"]');+ },+ title: <Trans>Your Budget</Trans>,+ content:+ budgetType === 'tracking' ? (+ <Trans>+ In a tracking budget, the amounts you budget are targets for your+ income and spending rather than envelopes of money. This approach is+ called{' '}+ <Link+ variant="external"+ to="https://actualbudget.org/docs/getting-started/tracking-budget"+ >+ tracking budgeting+ </Link>+ . If you prefer, you can switch to{' '}+ <Link+ variant="external"+ to="https://actualbudget.org/docs/getting-started/envelope-budgeting"+ >+ envelope budgeting+ </Link>{' '}+ in the settings.+ </Trans>+ ) : (+ <Trans>+ Categories in {{ appName: 'Actual' }} work like virtual envelopes:+ you assign the money you already have to them, then spend from each+ envelope. This approach is called{' '}+ <Link+ variant="external"+ to="https://actualbudget.org/docs/getting-started/envelope-budgeting"+ >+ envelope budgeting+ </Link>+ . If you prefer, you can switch to{' '}+ <Link+ variant="external"+ to="https://actualbudget.org/docs/getting-started/tracking-budget"+ >+ tracking budgeting+ </Link>{' '}+ in the settings.+ </Trans>+ ),+ },+ {+ ...(budgetType === 'tracking'+ ? {+ title: <Trans>Saved This Month</Trans>,+ content: (+ <Trans>+ This summary compares your income and expenses to show how much+ you saved this month. Rather than rolling funds over, a tracking+ budget plans each month on its own.+ </Trans>+ ),+ }+ : {+ title: <Trans>To Budget</Trans>,+ content: (+ <Trans>+ The <strong>To Budget</strong> amount shows the money you have+ not assigned to a category yet. Aim to bring it to zero, so that+ all of your money has a job.+ </Trans>+ ),+ }),+ id: 'budget-summary',+ target: findBudgetSummary,+ placement: 'bottom',+ },+ {+ id: 'category',+ target: '[data-testid="category-name"]',+ placement: 'bottom',+ title: <Trans>Categories</Trans>,+ content: (+ <Trans>+ Each row in the budget is a category. Click the{' '}+ <strong>Budgeted</strong> amount to assign money to a category, and+ keep an eye on the <strong>Balance</strong> column to see how much is+ left to spend.+ </Trans>+ ),+ },+ {+ id: 'month-picker',+ target: '[data-testid="selected-budget-month"]',+ placement: 'bottom',+ title: <Trans>Month by Month</Trans>,+ content: (+ <Trans>+ Every month gets its own budget. Use the month picker to move between+ months, and the calendar icons on the left to choose how many months+ are shown side by side.+ </Trans>+ ),+ },+ {+ id: 'sidebar-navigation',+ target: '[data-testid="sidebar-primary-buttons"]',+ placement: 'right',+ title: <Trans>Getting Around</Trans>,+ content: (+ <Trans>+ The sidebar takes you to your budget, reports, and scheduled+ transactions. You can find payees, rules, and the settings under{' '}+ <strong>More</strong>.+ </Trans>+ ),+ },+ {+ id: ADD_ACCOUNT_STEP_ID,+ target: '[data-testid="sidebar-add-account"]',+ placement: 'right',+ title: <Trans>Add Your Accounts</Trans>,+ content: (+ <Trans>+ Transactions live in accounts, so adding your first account is the+ best way to get started with {{ appName: 'Actual' }}. Click here to+ add one. You can enter transactions yourself, or{' '}+ <Link+ variant="external"+ to="https://actualbudget.org/docs/advanced/bank-sync"+ >+ link the account to your bank+ </Link>{' '}+ to import them automatically.+ </Trans>+ ),+ },+ {+ id: 'help-menu',+ target: '[data-testid="help-menu-button"]',+ placement: 'bottom-end',+ title: <Trans>Getting Help</Trans>,+ content: (+ <Trans>+ The Help menu is always here when you need it. Use it to replay this+ tour, browse the documentation, or ask the community on Discord.+ </Trans>+ ),+ },+ ];+}++const tourSteps: Record<TourId, (deps: TourStepDeps) => Step[]> = {+ 'budget-tour': getBudgetTourSteps,+};++export function getTourSteps(tourId: TourId, deps: TourStepDeps): Step[] {+ return tourSteps[tourId](deps);+}diff --git a/packages/loot-core/src/types/prefs.ts b/packages/loot-core/src/types/prefs.tsindex fc11e449f7..61edb7a4b7 100644--- a/packages/loot-core/src/types/prefs.ts+++ b/packages/loot-core/src/types/prefs.ts@@ -98,6 +98,7 @@ export type LocalPrefs = Partial<{'budget.showHiddenCategories': boolean;'budget.startMonth': string;'flags.updateNotificationShownForVersion': string;+ 'tour.introSeen': boolean;'schedules.showCompleted': boolean;reportsViewLegend: boolean;reportsViewSummary: boolean;diff --git a/upcoming-release-notes/add-guided-tour.md b/upcoming-release-notes/add-guided-tour.mdnew file mode 100644index 0000000000..db5a6ced1f--- /dev/null+++ b/upcoming-release-notes/add-guided-tour.md@@ -0,0 +1,6 @@+---+category: Features+authors: [matt-fidd]+---++Add an initial in-app tour to guide first-time users in getting starteddiff --git a/yarn.lock b/yarn.lockindex bf4c8947dd..75944e70ec 100644--- a/yarn.lock+++ b/yarn.lock@@ -293,6 +293,7 @@ __metadata:react-grid-layout: "npm:^2.2.3"react-hotkeys-hook: "npm:^5.3.3"react-i18next: "npm:^17.0.10"+ react-joyride: "npm:^3.2.0"react-markdown: "npm:^10.1.0"react-redux: "npm:^9.3.0"react-router: "npm:8.3.0"@@ -4439,6 +4440,51 @@ __metadata:languageName: nodelinkType: hard+"@fastify/deepmerge@npm:^3.2.1":+ version: 3.2.1+ resolution: "@fastify/deepmerge@npm:3.2.1"+ checksum: 10/e35db0525b2cbb45ba5c0ca8b6f40f80016f4d1b89c8428ed17d181e69b2a7262cdaabeb9cd8033684ca9b2771c037ae2749f02519928f1407c118014248033b+ languageName: node+ linkType: hard++"@floating-ui/core@npm:^1.8.0":+ version: 1.8.0+ resolution: "@floating-ui/core@npm:1.8.0"+ dependencies:+ "@floating-ui/utils": "npm:^0.2.12"+ checksum: 10/762cd5677fd4e82597db2efdd8f1e81d248eac5615d8be755e1bbb5f12a14c56a6bccd735676374d4914db7ccb3f09ec405ec7433e8c48a5521f5d66dc8dd5d6+ languageName: node+ linkType: hard++"@floating-ui/dom@npm:^1.8.0":+ version: 1.8.0+ resolution: "@floating-ui/dom@npm:1.8.0"+ dependencies:+ "@floating-ui/core": "npm:^1.8.0"+ "@floating-ui/utils": "npm:^0.2.12"+ checksum: 10/2e7d75fb702875a62795dd8529569f27eff53167768d75476056d6bf824a1ba608177a8877ed9d728eadb5787b4bd07b043fb2c3125b7ad2505a398680b323c0+ languageName: node+ linkType: hard++"@floating-ui/react-dom@npm:^2.1.8":+ version: 2.1.9+ resolution: "@floating-ui/react-dom@npm:2.1.9"+ dependencies:+ "@floating-ui/dom": "npm:^1.8.0"+ peerDependencies:+ react: ">=16.8.0"+ react-dom: ">=16.8.0"+ checksum: 10/d775609760291d0f1477a9e23fc3508a35bcda1f36601d74bd3e94b817841b266914fa9964697963cb1ac09b451e51283a2ce25f0c3719d0aca761e327bdee43+ languageName: node+ linkType: hard++"@floating-ui/utils@npm:^0.2.12":+ version: 0.2.12+ resolution: "@floating-ui/utils@npm:0.2.12"+ checksum: 10/ec4e176fb22d33d75df752c5acf82dcaacae40ed2d09c1a5015cb4081318fff20260db216678e952344b95f90c6b43214762b69eba7c51556ecd82c35a795cff+ languageName: node+ linkType: hard+"@fontsource-variable/inter@npm:^5.2.8":version: 5.2.8resolution: "@fontsource-variable/inter@npm:5.2.8"@@ -4453,6 +4499,33 @@ __metadata:languageName: nodelinkType: hard+"@gilbarbara/deep-equal@npm:^0.4.1":+ version: 0.4.1+ resolution: "@gilbarbara/deep-equal@npm:0.4.1"+ checksum: 10/d53bc77c2002036e029b9234bd5a03b7c58a9798fefc714e7e2e4817fca1dae3ef36db2180dc200122c3c8f8d00415840e5e94a63e11859bc910540e19ec14f8+ languageName: node+ linkType: hard++"@gilbarbara/hooks@npm:^0.11.0":+ version: 0.11.0+ resolution: "@gilbarbara/hooks@npm:0.11.0"+ dependencies:+ "@gilbarbara/deep-equal": "npm:^0.4.1"+ peerDependencies:+ react: 16.8 - 19+ checksum: 10/479963fed7e75afccc35c1f7da64fdc19ae714d0aec11b1bd07c90e2d25c1b8ba04000bb7f4b9e9122022b44a3fa989be899f386f7aa18f0b25d4dc16ca4f8b8+ languageName: node+ linkType: hard++"@gilbarbara/types@npm:^0.2.2":+ version: 0.2.2+ resolution: "@gilbarbara/types@npm:0.2.2"+ dependencies:+ type-fest: "npm:^4.1.0"+ checksum: 10/fb71d2e577a48b68b2205146c4cc6180d4e1d175df8b37de47e7581feaeb68ff32918dade9ddb94627755f0d8270727ef7209a9b238bc3af79dc83493b14da5a+ languageName: node+ linkType: hard+"@gulpjs/to-absolute-glob@npm:^4.0.0":version: 4.0.0resolution: "@gulpjs/to-absolute-glob@npm:4.0.0"@@ -17421,6 +17494,13 @@ __metadata:languageName: nodelinkType: hard+"is-lite@npm:^2.0.0":+ version: 2.0.0+ resolution: "is-lite@npm:2.0.0"+ checksum: 10/0afd026a139b09233652fe7dc628f7a38b78bf09ad466557721b3c3ab36c6b4966d28f2416976c85bcef01e6d20ff7e3678fbe544c10f4cf32e5692c7ba2248e+ languageName: node+ linkType: hard+"is-map@npm:^2.0.3":version: 2.0.3resolution: "is-map@npm:2.0.3"@@ -23264,6 +23344,16 @@ __metadata:languageName: nodelinkType: hard+"react-innertext@npm:^1.1.5":+ version: 1.1.5+ resolution: "react-innertext@npm:1.1.5"+ peerDependencies:+ "@types/react": ">=0.0.0 <=99"+ react: ">=0.0.0 <=99"+ checksum: 10/01c9c8a5a471f03965b9d69c8bee02d420fd3a607b678004f0bdee098c9bccb3e2eae8460c90b1d180d2a8d544a3ddb09b8c2a11e5aa8b3a077733e2d9c25c2c+ languageName: node+ linkType: hard+"react-is-18@npm:react-is@^18.3.1, react-is@npm:^18.2.0":version: 18.3.1resolution: "react-is@npm:18.3.1"@@ -23292,6 +23382,27 @@ __metadata:languageName: nodelinkType: hard+"react-joyride@npm:^3.2.0":+ version: 3.2.0+ resolution: "react-joyride@npm:3.2.0"+ dependencies:+ "@fastify/deepmerge": "npm:^3.2.1"+ "@floating-ui/react-dom": "npm:^2.1.8"+ "@gilbarbara/deep-equal": "npm:^0.4.1"+ "@gilbarbara/hooks": "npm:^0.11.0"+ "@gilbarbara/types": "npm:^0.2.2"+ is-lite: "npm:^2.0.0"+ react-innertext: "npm:^1.1.5"+ scroll: "npm:^3.0.1"+ scrollparent: "npm:^2.1.0"+ use-sync-external-store: "npm:^1.6.0"+ peerDependencies:+ react: 16.8 - 19+ react-dom: 16.8 - 19+ checksum: 10/ade0780b701842065e458bf96d0f5eb617018b67539f7720242a2877806520b6ff8f6ba9827eb06afa469b768865eb129aad9903f3d8600a35f6fb9f11e8a160+ languageName: node+ linkType: hard+"react-json-view-lite@npm:^2.3.0":version: 2.5.0resolution: "react-json-view-lite@npm:2.5.0"@@ -24752,6 +24863,20 @@ __metadata:languageName: nodelinkType: hard+"scroll@npm:^3.0.1":+ version: 3.0.1+ resolution: "scroll@npm:3.0.1"+ checksum: 10/e6b045347adace30035073882e6ef2af7e1c81dd611faf3a578ca8cd0d1a3a9da54932dd97ed6fd99c9573351c758fa50e6d8ed4afb5bd3a33794b6c48d25922+ languageName: node+ linkType: hard++"scrollparent@npm:^2.1.0":+ version: 2.1.0+ resolution: "scrollparent@npm:2.1.0"+ checksum: 10/646cfdaf981f94b52f1020cc26b18ff1a751c2fa4e40777f6dfac314500d365b4db3fec39fd06be7b683f0a1dbd29df8ce1629db50381e9072433465b2f446fa+ languageName: node+ linkType: hard+"section-matter@npm:^1.0.0":version: 1.0.0resolution: "section-matter@npm:1.0.0"@@ -26657,6 +26782,13 @@ __metadata:languageName: nodelinkType: hard+"type-fest@npm:^4.1.0":+ version: 4.41.0+ resolution: "type-fest@npm:4.41.0"+ checksum: 10/617ace794ac0893c2986912d28b3065ad1afb484cad59297835a0807dc63286c39e8675d65f7de08fafa339afcb8fe06a36e9a188b9857756ae1e92ee8bda212+ languageName: node+ linkType: hard+"type-is@npm:^2.0.1":version: 2.0.1resolution: "type-is@npm:2.0.1"