Skip to content

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.png
index 07912ab08a..3ca32e5099 100644
Binary 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 differ
diff --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.png
index 6249ef82ae..a24ced6763 100644
Binary 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 differ
diff --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.png
index 5a7abc44ba..9d83e136eb 100644
Binary 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 differ
diff --git a/packages/desktop-client/e2e/onboarding.test.ts b/packages/desktop-client/e2e/onboarding.test.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.json
index 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.tsx
index 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.tsx
index 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 />
<View
style={{
- 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.tsx
index 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.tsx
index 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 (
<View
data-testid="budget-summary"
+ data-month={month}
style={{
backgroundColor:
month === currentMonth
diff --git a/packages/desktop-client/src/components/budget/tracking/budgetsummary/BudgetSummary.tsx b/packages/desktop-client/src/components/budget/tracking/budgetsummary/BudgetSummary.tsx
index 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 === currentMonth
diff --git a/packages/desktop-client/src/components/sidebar/PrimaryButtons.tsx b/packages/desktop-client/src/components/sidebar/PrimaryButtons.tsx
index 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.tsx
index 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.tsx
index 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 }}>
<ItemContent
style={{
...accountNameStyle,
diff --git a/packages/desktop-client/src/components/sidebar/Sidebar.tsx b/packages/desktop-client/src/components/sidebar/Sidebar.tsx
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
index 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.md
new file mode 100644
index 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 started
diff --git a/yarn.lock b/yarn.lock
index 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: node
linkType: 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.8
resolution: "@fontsource-variable/inter@npm:5.2.8"
@@ -4453,6 +4499,33 @@ __metadata:
languageName: node
linkType: 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.0
resolution: "@gulpjs/to-absolute-glob@npm:4.0.0"
@@ -17421,6 +17494,13 @@ __metadata:
languageName: node
linkType: 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.3
resolution: "is-map@npm:2.0.3"
@@ -23264,6 +23344,16 @@ __metadata:
languageName: node
linkType: 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.1
resolution: "react-is@npm:18.3.1"
@@ -23292,6 +23382,27 @@ __metadata:
languageName: node
linkType: 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.0
resolution: "react-json-view-lite@npm:2.5.0"
@@ -24752,6 +24863,20 @@ __metadata:
languageName: node
linkType: 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.0
resolution: "section-matter@npm:1.0.0"
@@ -26657,6 +26782,13 @@ __metadata:
languageName: node
linkType: 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.1
resolution: "type-is@npm:2.0.1"