fix(mobile): offer to allow exact alarms on Android 12+ so reminders and the pomodoro alert stop arriving late (#528)

Author: dongdongbh

apps/mobile/components/settings/exact-alarm-notice.test.tsx

@@ -0,0 +1,150 @@
+import React from 'react';
+import renderer, { act } from 'react-test-renderer';
+import { Text } from 'react-native';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { mockRelevant, mockRefresh, mockOpen, appStateListeners } = vi.hoisted(() => ({
+  mockRelevant: vi.fn(() => true),
+  mockRefresh: vi.fn(async () => true),
+  mockOpen: vi.fn(async () => undefined),
+  appStateListeners: [] as ((state: string) => void)[],
+}));
+
+vi.mock('@/lib/exact-alarm-permission', () => ({
+  isExactAlarmPermissionRelevant: mockRelevant,
+  refreshExactAlarmPermission: mockRefresh,
+  openExactAlarmSettings: mockOpen,
+}));
+
+vi.mock('@/hooks/use-theme-colors', () => ({
+  useThemeColors: () => ({
+    bg: '#0f172a',
+    cardBg: '#111827',
+    border: '#334155',
+    text: '#f8fafc',
+    secondaryText: '#94a3b8',
+  }),
+}));
+
+vi.mock('react-native', async () => {
+  const actual = await vi.importActual<typeof import('react-native')>('react-native');
+  return {
+    ...actual,
+    AppState: {
+      currentState: 'active',
+      addEventListener: (_event: string, listener: (state: string) => void) => {
+        appStateListeners.push(listener);
+        return {
+          remove: () => {
+            const index = appStateListeners.indexOf(listener);
+            if (index >= 0) appStateListeners.splice(index, 1);
+          },
+        };
+      },
+    },
+  };
+});
+
+import { ExactAlarmNoticeRow, useExactAlarmPermission } from './exact-alarm-notice';
+
+function Probe({ enabled }: { enabled: boolean }) {
+  const { showNotice } = useExactAlarmPermission(enabled);
+  return <Text>{showNotice ? 'notice' : 'no-notice'}</Text>;
+}
+
+const renderProbe = async (enabled: boolean) => {
+  let tree!: renderer.ReactTestRenderer;
+  await act(async () => {
+    tree = renderer.create(<Probe enabled={enabled} />);
+  });
+  return tree;
+};
+
+const noticeState = (tree: renderer.ReactTestRenderer) => tree.root.findByType(Text).props.children;
+
+beforeEach(() => {
+  appStateListeners.length = 0;
+  mockRelevant.mockReturnValue(true);
+  mockRefresh.mockClear();
+  mockRefresh.mockResolvedValue(true);
+  mockOpen.mockClear();
+});
+
+describe('useExactAlarmPermission', () => {
+  it('shows the notice when the feature is on and exact alarms are denied', async () => {
+    mockRefresh.mockResolvedValue(false);
+    const tree = await renderProbe(true);
+    expect(noticeState(tree)).toBe('notice');
+  });
+
+  it('hides the notice when exact alarms are allowed', async () => {
+    const tree = await renderProbe(true);
+    expect(noticeState(tree)).toBe('no-notice');
+  });
+
+  it('does not read the permission while the feature is off', async () => {
+    mockRefresh.mockResolvedValue(false);
+    const tree = await renderProbe(false);
+    expect(noticeState(tree)).toBe('no-notice');
+    expect(mockRefresh).not.toHaveBeenCalled();
+  });
+
+  it('does not read the permission below Android 12', async () => {
+    mockRelevant.mockReturnValue(false);
+    mockRefresh.mockResolvedValue(false);
+    const tree = await renderProbe(true);
+    expect(noticeState(tree)).toBe('no-notice');
+    expect(mockRefresh).not.toHaveBeenCalled();
+  });
+
+  it('re-reads the permission when the app returns to the foreground', async () => {
+    mockRefresh.mockResolvedValue(false);
+    const tree = await renderProbe(true);
+    expect(noticeState(tree)).toBe('notice');
+    expect(mockRefresh).toHaveBeenCalledTimes(1);
+
+    mockRefresh.mockResolvedValue(true);
+    await act(async () => {
+      appStateListeners.forEach((listener) => listener('active'));
+    });
+
+    expect(mockRefresh).toHaveBeenCalledTimes(2);
+    expect(noticeState(tree)).toBe('no-notice');
+  });
+
+  it('ignores background transitions', async () => {
+    const tree = await renderProbe(true);
+    await act(async () => {
+      appStateListeners.forEach((listener) => listener('background'));
+    });
+    expect(mockRefresh).toHaveBeenCalledTimes(1);
+    expect(noticeState(tree)).toBe('no-notice');
+  });
+
+  it('detaches its listener on unmount', async () => {
+    const tree = await renderProbe(true);
+    expect(appStateListeners).toHaveLength(1);
+    await act(async () => {
+      tree.unmount();
+    });
+    expect(appStateListeners).toHaveLength(0);
+  });
+});
+
+describe('ExactAlarmNoticeRow', () => {
+  it('opens the system screen from its action button', async () => {
+    let tree!: renderer.ReactTestRenderer;
+    await act(async () => {
+      tree = renderer.create(
+        <ExactAlarmNoticeRow label="Late" description="Why" actionLabel="Allow" />
+      );
+    });
+
+    const button = tree.root.findByProps({ testID: 'exact-alarm-allow' });
+    await act(async () => {
+      button.props.onPress();
+    });
+
+    expect(mockOpen).toHaveBeenCalledTimes(1);
+  });
+});

apps/mobile/components/settings/exact-alarm-notice.tsx

@@ -0,0 +1,83 @@
+import React, { useCallback, useEffect, useState } from 'react';
+import { AppState, Text, TouchableOpacity } from 'react-native';
+
+import {
+    isExactAlarmPermissionRelevant,
+    openExactAlarmSettings,
+    refreshExactAlarmPermission,
+} from '@/lib/exact-alarm-permission';
+
+import { SettingRow } from './setting-row';
+import { styles } from './settings.styles';
+
+/**
+ * Tracks whether the OS will let this app set exact alarms, for the settings
+ * screens that own a feature which depends on them.
+ *
+ * Only runs while `enabled` is true — the user has the reminder or pomodoro
+ * alert switched on and is looking at the screen that offers the fix. No
+ * polling and no background work: the state can only change on the system
+ * screen we send them to, so re-reading it when the app comes back to the
+ * foreground is enough.
+ */
+export function useExactAlarmPermission(enabled: boolean): { showNotice: boolean } {
+    const [allowed, setAllowed] = useState(true);
+
+    useEffect(() => {
+        if (!enabled || !isExactAlarmPermissionRelevant()) return;
+        let cancelled = false;
+        const check = () => {
+            refreshExactAlarmPermission()
+                .then((next) => {
+                    if (!cancelled) setAllowed(next);
+                })
+                .catch(() => undefined);
+        };
+        check();
+        const subscription = AppState.addEventListener('change', (state) => {
+            if (state === 'active') check();
+        });
+        return () => {
+            cancelled = true;
+            subscription.remove();
+        };
+    }, [enabled]);
+
+    return { showNotice: enabled && isExactAlarmPermissionRelevant() && !allowed };
+}
+
+export interface ExactAlarmNoticeRowProps {
+    /** Already-translated title, description and button label. */
+    label: string;
+    description: string;
+    actionLabel: string;
+    divider?: boolean;
+}
+
+/** The one row both reminder and pomodoro settings show while exact alarms are denied. */
+export function ExactAlarmNoticeRow({ label, description, actionLabel, divider }: ExactAlarmNoticeRowProps) {
+    const onPress = useCallback(() => {
+        openExactAlarmSettings().catch(console.error);
+    }, []);
+
+    return (
+        <SettingRow
+            divider={divider}
+            label={label}
+            description={description}
+            testID="exact-alarm-notice"
+        >
+            <TouchableOpacity
+                style={[styles.manageEditorButton, styles.manageEditorButtonPrimary]}
+                onPress={onPress}
+                accessibilityRole="button"
+                accessibilityLabel={actionLabel}
+                testID="exact-alarm-allow"
+            >
+                <Text style={[styles.manageEditorButtonText, styles.manageEditorButtonPrimaryText]}>
+                    {actionLabel}
+                </Text>
+            </TouchableOpacity>
+        </SettingRow>
+    );
+}

apps/mobile/components/settings/gtd-settings-screen.tsx

@@ -43,6 +43,7 @@ import {
     useTaskStore,
 } from '@mindwtr/core';
 
+import { ExactAlarmNoticeRow, useExactAlarmPermission } from './exact-alarm-notice';
 import { SettingRow, SettingToggleRow } from './setting-row';
 import type { SettingsScreen } from './settings.constants';
 import { useSettingsLocalization, useSettingsScrollContent } from './settings.hooks';
@@ -137,6 +138,9 @@ export function GtdSettingsScreen({
     // Defaults on: the alert is the point of the timer, and an off-by-default
     // switch is what made #528 read as broken.
     const pomodoroCompletionAlert = settings.gtd?.pomodoro?.completionAlert !== false;
+    const { showNotice: showExactAlarmNotice } = useExactAlarmPermission(
+        screen === 'gtd-pomodoro' && pomodoroCompletionAlert
+    );
     const [pomodoroFocusDraft, setPomodoroFocusDraft] = useState(String(pomodoroCustomDurations.focusMinutes));
     const [pomodoroBreakDraft, setPomodoroBreakDraft] = useState(String(pomodoroCustomDurations.breakMinutes));
     const [defaultScheduleTimeDraft, setDefaultScheduleTimeDraft] = useState(defaultScheduleTime);
@@ -697,6 +701,14 @@ export function GtdSettingsScreen({
                                 value={pomodoroCompletionAlert}
                                 onChange={(value) => updatePomodoroSettings({ completionAlert: value })}
                             />
+                            {showExactAlarmNotice && (
+                                <ExactAlarmNoticeRow
+                                    divider
+                                    label={t('settings.exactAlarmsLabel')}
+                                    description={t('settings.exactAlarmsDesc')}
+                                    actionLabel={t('settings.exactAlarmsAllow')}
+                                />
+                            )}
                         </View>
                     )}
                 </ScrollView>

apps/mobile/components/settings/notifications-settings-screen.tsx

@@ -20,6 +20,7 @@ import {
 } from '@/lib/persistent-capture-notification';
 import { useThemeColors } from '@/hooks/use-theme-colors';
 
+import { ExactAlarmNoticeRow, useExactAlarmPermission } from './exact-alarm-notice';
 import { SettingRow, SettingToggleRow } from './setting-row';
 import { useSettingsLocalization, useSettingsScrollContent } from './settings.hooks';
 import { SettingsTopBar } from './settings.shell';
@@ -37,6 +38,7 @@ export function NotificationsSettingsScreen() {
     const [weeklyReviewDayPickerOpen, setWeeklyReviewDayPickerOpen] = useState(false);
 
     const notificationsEnabled = areTaskRemindersEnabled(settings);
+    const { showNotice: showExactAlarmNotice } = useExactAlarmPermission(notificationsEnabled);
     const startDateNotificationsEnabled = areStartDateRemindersEnabled(settings);
     const dueDateNotificationsEnabled = areDueDateRemindersEnabled(settings);
     const dailyDigestMorningEnabled = settings.dailyDigestMorningEnabled === true;
@@ -238,6 +240,15 @@ export function NotificationsSettingsScreen() {
                         }}
                     />
 
+                    {showExactAlarmNotice && (
+                        <ExactAlarmNoticeRow
+                            divider
+                            label={t('settings.exactAlarmsLabel')}
+                            description={t('settings.exactAlarmsDesc')}
+                            actionLabel={t('settings.exactAlarmsAllow')}
+                        />
+                    )}
+
                     {isPersistentCaptureSupported() && (
                         <SettingToggleRow
                             divider