[WIP] Pay Periods - MM 13 through 99

packages/desktop-client/src/components/budget/BudgetPageHeader.tsx

@@ -7,6 +7,8 @@
 import { getScrollbarWidth } from './util';
 
 import { useGlobalPref } from '@desktop-client/hooks/useGlobalPref';
+import { useFeatureFlag } from '@desktop-client/hooks/useFeatureFlag';
+import { useSyncedPref } from '@desktop-client/hooks/useSyncedPref';
 
 type BudgetPageHeaderProps = {
   startMonth: string;
@@ -20,6 +22,8 @@
     const [categoryExpandedStatePref] = useGlobalPref('categoryExpandedState');
     const categoryExpandedState = categoryExpandedStatePref ?? 0;
     const offsetMultipleMonths = numMonths === 1 ? 4 : 0;
+    const payPeriodFeatureFlagEnabled = useFeatureFlag('payPeriodsEnabled');
+    const [payPeriodViewEnabled, setPayPeriodViewEnabled] = useSyncedPref('showPayPeriods');
 
     return (
       <View
@@ -29,6 +33,18 @@
           flexShrink: 0,
         }}
       >
+        {payPeriodFeatureFlagEnabled && (
+          <View style={{ alignItems: 'center', marginBottom: 5 }}>
+            <label style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+              <input
+                type="checkbox"
+                checked={String(payPeriodViewEnabled) === 'true'}
+                onChange={e => setPayPeriodViewEnabled(e.target.checked ? 'true' : 'false')}
+              />
+              <span>Show pay periods</span>
+            </label>
+          </View>
+        )}
         <View
           style={{
             marginRight: 5 + getScrollbarWidth() - offsetMultipleMonths,

packages/desktop-client/src/components/budget/MonthPicker.tsx

@@ -127,7 +127,8 @@ export const MonthPicker = ({
           </View>
         </Link>
         {range.map((month, idx) => {
-          const monthName = monthUtils.format(month, 'MMM', locale);
+          const config = monthUtils.getPayPeriodConfig();
+          const displayLabel = monthUtils.getMonthDisplayName(month, config, locale);
           const selected =
             idx >= firstSelectedIndex && idx <= lastSelectedIndex;
 
@@ -214,7 +215,13 @@ export const MonthPicker = ({
               onMouseLeave={() => setHoverId(null)}
             >
               <View>
-                {size === 'small' ? monthName[0] : monthName}
+                {monthUtils.isPayPeriod(month)
+                  ? size === 'small'
+                    ? `P${String(parseInt(month.slice(5, 7)) - 12)}`
+                    : displayLabel
+                  : size === 'small'
+                    ? displayLabel[0]
+                    : displayLabel}
                 {showYearHeader && (
                   <View
                     style={{

packages/desktop-client/src/components/budget/envelope/budgetsummary/BudgetSummary.tsx

@@ -59,7 +59,8 @@ export const BudgetSummary = memo(({ month }: BudgetSummaryProps) => {
     ? SvgArrowButtonDown1
     : SvgArrowButtonUp1;
 
-  const displayMonth = monthUtils.format(month, 'MMMM ‘yy', locale);
+  const config = monthUtils.getPayPeriodConfig();
+  const displayMonth = monthUtils.getMonthDateRange(month, config, locale);
   const { t } = useTranslation();
 
   return (
@@ -133,7 +134,7 @@ export const BudgetSummary = memo(({ month }: BudgetSummaryProps) => {
               currentMonth === month && { fontWeight: 'bold' },
             ])}
           >
-            {monthUtils.format(month, 'MMMM', locale)}
+            {displayMonth}
           </div>
 
           <View

packages/desktop-client/src/components/budget/index.tsx

@@ -29,11 +29,12 @@
 } from '@desktop-client/budget/budgetSlice';
 import { useCategories } from '@desktop-client/hooks/useCategories';
 import { useGlobalPref } from '@desktop-client/hooks/useGlobalPref';
+import { useFeatureFlag } from '@desktop-client/hooks/useFeatureFlag';
+import { useSyncedPref } from '@desktop-client/hooks/useSyncedPref';
 import { useLocalPref } from '@desktop-client/hooks/useLocalPref';
 import { useNavigate } from '@desktop-client/hooks/useNavigate';
 import { SheetNameProvider } from '@desktop-client/hooks/useSheetName';
 import { useSpreadsheet } from '@desktop-client/hooks/useSpreadsheet';
-import { useSyncedPref } from '@desktop-client/hooks/useSyncedPref';
 import { pushModal } from '@desktop-client/modals/modalsSlice';
 import { addNotification } from '@desktop-client/notifications/notificationsSlice';
 import { useDispatch } from '@desktop-client/redux';
@@ -80,6 +81,10 @@
     end: startMonth,
   });
   const [budgetType = 'envelope'] = useSyncedPref('budgetType');
+  const payPeriodFeatureFlagEnabled = useFeatureFlag('payPeriodsEnabled');
+  const [payPeriodFrequency] = useSyncedPref('payPeriodFrequency');
+  const [payPeriodStartDate] = useSyncedPref('payPeriodStartDate');
+  const [payPeriodViewEnabled] = useSyncedPref('showPayPeriods');
   const [maxMonthsPref] = useGlobalPref('maxMonths');
   const maxMonths = maxMonthsPref || 1;
   const [initialized, setInitialized] = useState(false);
@@ -105,6 +110,24 @@
     run();
   }, []);
 
+  // Wire pay period config from synced prefs into month utils
+  useEffect(() => {
+    const enabled = payPeriodFeatureFlagEnabled && String(payPeriodViewEnabled) === 'true';
+    const frequency = (payPeriodFrequency as any) || 'monthly';
+    const start = (payPeriodStartDate as any) || `${new Date().getFullYear()}-01-01`;
+
+    monthUtils.setPayPeriodConfig({
+      enabled,
+      payFrequency: frequency,
+      startDate: start,
+    } as any);
+  }, [
+    payPeriodFeatureFlagEnabled,
+    payPeriodViewEnabled,
+    payPeriodFrequency,
+    payPeriodStartDate,
+  ]);
+
   useEffect(() => {
     send('get-budget-bounds').then(({ start, end }) => {
       if (bounds.start !== start || bounds.end !== end) {
@@ -328,6 +351,22 @@
 
   const { trackingComponents, envelopeComponents } = props;
 
+  // Derive the month to render based on pay period view toggle
+  const derivedStartMonth = useMemo(() => {
+    const config = monthUtils.getPayPeriodConfig();
+    const usePayPeriods = config?.enabled;
+
+    if (!usePayPeriods) return startMonth;
+
+    // If already a pay period id, keep it
+    const mm = parseInt(startMonth.slice(5, 7));
+    if (Number.isFinite(mm) && mm >= 13) return startMonth;
+
+    // For calendar months, use the current year for pay periods
+    const currentYear = parseInt(startMonth.slice(0, 4));
+    return String(currentYear) + '-13';
+  }, [startMonth, payPeriodViewEnabled]);
+
   if (!initialized || !categoryGroups) {
     return null;
   }
@@ -342,8 +381,8 @@
       >
         <DynamicBudgetTable
           type={budgetType}
-          prewarmStartMonth={startMonth}
-          startMonth={startMonth}
+          prewarmStartMonth={derivedStartMonth}
+          startMonth={derivedStartMonth}
           monthBounds={bounds}
           maxMonths={maxMonths}
           dataComponents={trackingComponents}
@@ -369,8 +408,8 @@
       >
         <DynamicBudgetTable
           type={budgetType}
-          prewarmStartMonth={startMonth}
-          startMonth={startMonth}
+          prewarmStartMonth={derivedStartMonth}
+          startMonth={derivedStartMonth}
           monthBounds={bounds}
           maxMonths={maxMonths}
           dataComponents={envelopeComponents}
@@ -390,7 +429,7 @@
   }
 
   return (
-    <SheetNameProvider name={monthUtils.sheetForMonth(startMonth)}>
+    <SheetNameProvider name={monthUtils.sheetForMonth(derivedStartMonth)}>
       <View style={{ flex: 1 }}>{table}</View>
     </SheetNameProvider>
   );

packages/desktop-client/src/components/budget/tracking/budgetsummary/BudgetSummary.tsx

@@ -57,7 +57,8 @@ export function BudgetSummary({ month }: BudgetSummaryProps) {
     ? SvgArrowButtonDown1
     : SvgArrowButtonUp1;
 
-  const displayMonth = monthUtils.format(month, 'MMMM ‘yy', locale);
+  const config = monthUtils.getPayPeriodConfig();
+  const displayMonth = monthUtils.getMonthDateRange(month, config, locale);
 
   return (
     <View
@@ -126,7 +127,7 @@ export function BudgetSummary({ month }: BudgetSummaryProps) {
               textDecorationSkip: 'ink',
             })}
           >
-            {monthUtils.format(month, 'MMMM', locale)}
+            {displayMonth}
           </div>
 
           <View

packages/desktop-client/src/components/mobile/budget/BudgetPage.tsx

@@ -995,7 +995,7 @@ function MonthSelector({
         data-month={month}
       >
         <Text style={styles.underlinedText}>
-          {monthUtils.format(month, 'MMMM ‘yy', locale)}
+          {monthUtils.getMonthDateRange(month, monthUtils.getPayPeriodConfig(), locale)}
         </Text>
       </Button>
       <Button

packages/desktop-client/src/components/settings/Experimental.tsx

@@ -105,6 +105,9 @@ export function ExperimentalFeatures() {
             >
               <Trans>Currency support</Trans>
             </FeatureToggle>
+            <FeatureToggle flag="payPeriodsEnabled">
+              <Trans>Pay periods</Trans>
+            </FeatureToggle>
           </View>
         ) : (
           <Link

packages/desktop-client/src/components/settings/PayPeriodSettings.tsx

@@ -0,0 +1,58 @@
+import React from 'react';
+import { Trans, useTranslation } from 'react-i18next';
+
+import { Select } from '@actual-app/components/select';
+import { Text } from '@actual-app/components/text';
+import { View } from '@actual-app/components/view';
+
+import { Column, Setting } from './UI';
+import { Input } from '@actual-app/components/input';
+import { useFeatureFlag } from '@desktop-client/hooks/useFeatureFlag';
+import { useSyncedPref } from '@desktop-client/hooks/useSyncedPref';
+
+export function PayPeriodSettings() {
+  const enabledByFlag = useFeatureFlag('payPeriodsEnabled');
+  const { t } = useTranslation();
+
+  const [frequency, setFrequency] = useSyncedPref('payPeriodFrequency');
+  const [startDate, setStartDate] = useSyncedPref('payPeriodStartDate');
+
+  const frequencyOptions: [string, string][] = [
+    ['weekly', t('Weekly')],
+    ['biweekly', t('Biweekly')],
+    ['monthly', t('Monthly')],
+  ];
+
+  return (
+    <Setting
+      primaryAction={
+        <View style={{ display: 'flex', flexDirection: 'row', gap: '1.5em' }}>
+          <Column title={t('Frequency')}>
+            <Select
+              value={frequency || 'monthly'}
+              onChange={value => setFrequency(value)}
+              options={frequencyOptions}
+              disabled={!enabledByFlag}
+            />
+          </Column>
+
+          <Column title={t('Start Date')}>
+            <Input
+              type="date"
+              value={startDate || ''}
+              onChange={e => setStartDate(e.target.value)}
+              disabled={!enabledByFlag}
+            />
+          </Column>
+        </View>
+      }
+    >
+      <Text>
+        <Trans>
+          <strong>Pay period settings.</strong> Configure how pay periods are generated and displayed.
+        </Trans>
+      </Text>
+    </Setting>
+  );
+}
+

packages/desktop-client/src/components/settings/index.tsx

@@ -19,6 +19,7 @@ import { BudgetTypeSettings } from './BudgetTypeSettings';
 import { CurrencySettings } from './Currency';
 import { EncryptionSettings } from './Encryption';
 import { ExperimentalFeatures } from './Experimental';
+import { PayPeriodSettings } from './PayPeriodSettings';
 import { ExportBudget } from './Export';
 import { FormatSettings } from './Format';
 import { LanguageSettings } from './LanguageSettings';
@@ -176,6 +177,7 @@ export function Settings() {
   const [budgetName] = useMetadataPref('budgetName');
   const dispatch = useDispatch();
   const isCurrencyExperimentalEnabled = useFeatureFlag('currency');
+  const isPayPeriodsEnabled = useFeatureFlag('payPeriodsEnabled');
   const [_, setDefaultCurrencyCodePref] = useSyncedPref('defaultCurrencyCode');
 
   const onCloseBudget = () => {
@@ -238,6 +240,7 @@ export function Settings() {
         <ThemeSettings />
         <FormatSettings />
         {isCurrencyExperimentalEnabled && <CurrencySettings />}
+        {isPayPeriodsEnabled && <PayPeriodSettings />}
         <LanguageSettings />
         <AuthSettings />
         <EncryptionSettings />

packages/desktop-client/src/hooks/useFeatureFlag.ts

@@ -7,6 +7,7 @@ const DEFAULT_FEATURE_FLAG_STATE: Record<FeatureFlag, boolean> = {
   goalTemplatesUIEnabled: false,
   actionTemplating: false,
   currency: false,
+  payPeriodsEnabled: false,
 };
 
 export function useFeatureFlag(name: FeatureFlag): boolean {

packages/loot-core/migrations/1757000000000_add_pay_period_config.sql

@@ -0,0 +1,14 @@
+-- Add pay period configuration table
+CREATE TABLE IF NOT EXISTS pay_period_config (
+  id TEXT PRIMARY KEY,
+  pay_frequency TEXT DEFAULT 'monthly',
+  start_date TEXT,
+  pay_day_of_week INTEGER,
+  pay_day_of_month INTEGER
+);
+
+-- Insert default configuration if not exists
+INSERT INTO pay_period_config (id, pay_frequency, start_date)
+SELECT 'default', 'monthly', '2025-01-01'
+WHERE NOT EXISTS (SELECT 1 FROM pay_period_config WHERE id = 'default');
+

packages/loot-core/src/server/db/types/index.ts

@@ -251,6 +251,14 @@ export type DbDashboard = {
   tombstone: 1 | 0;
 };
 
+export type DbPayPeriodConfig = {
+  id: string;
+  pay_frequency: string;
+  start_date: string;
+  pay_day_of_week?: number | null;
+  pay_day_of_month?: number | null;
+};
+
 export type DbViewTransactionInternal = {
   id: DbTransaction['id'];
   is_parent: DbTransaction['isParent'];