Merge branch 'main' into korytko/ecuk/3ds/implement-native-hooks

Author: JakubKorytko

.claude/agents/code-inline-reviewer.md

@@ -410,7 +410,7 @@ function UserProfile({ userId }) {
 
 ---
 
-### [PERFORMANCE-12] Prevent memory leaks in components and plugins
+### [PERF-12] Prevent memory leaks in components and plugins
 
 - **Search patterns**: `setInterval`, `setTimeout`, `addEventListener`, `subscribe`, `useEffect` with missing cleanup
 
@@ -770,7 +770,7 @@ useEffect(() => {
 
 ---
 
-### [CONSISTENCY-5] Ensure proper error handling
+### [CONSISTENCY-6] Ensure proper error handling
 
 - **Search patterns**: `try`, `catch`, `async`, `await`, `Promise`, `.then(`, `.catch(`
 
@@ -1189,6 +1189,261 @@ function SaveButton({ getSiblingFormData }: { getSiblingFormData: () => FormData
 
 ---
 
+### [CLEAN-REACT-PATTERNS-4] Avoid side-effect spaghetti
+
+- **Search patterns**: Multiple `useEffect` in single component, large component bodies mixing data access/navigation/UI state/lifecycle, hooks or utilities handling several unrelated responsibilities
+
+- **Condition**: Flag when a component, hook, or utility aggregates multiple unrelated responsibilities in a single unit, making it difficult to modify one concern without touching others.
+
+  **Signs of violation:**
+  - Component has several `useEffect` hooks handling unrelated concerns (e.g., telemetry, deep linking, audio, session management all in one component)
+  - A single `useEffect` or hook handles multiple distinct responsibilities
+  - Unrelated state variables are interdependent or updated together
+  - Logic mixes data fetching, navigation, UI state, and lifecycle behavior in one place
+  - Removing one piece of functionality requires careful untangling from others
+
+  **What counts as "unrelated":**
+  - Group by responsibility (what the code does), NOT by timing (when it runs)
+  - Data fetching and analytics are NOT related — they serve different purposes even if both run on mount
+  - Session management and audio configuration are NOT related — different domains entirely
+
+  **DO NOT flag if:**
+  - Component is a thin orchestration layer that ONLY composes child components (no business logic, no effects beyond rendering)
+  - Effects are extracted into focused custom hooks with single responsibilities (e.g., `useDebugShortcut`, `usePriorityMode`) — inline `useEffect` calls are a code smell and should be named hooks
+
+- **Reasoning**: When multiple unrelated responsibilities are grouped into a single component, hook, or utility, if any one concern changes, then unrelated logic must be touched as well, increasing coupling, regression risk, and cognitive load. This is the single responsibility principle for React: extract small units that do very little, very well. A component with several unrelated effects is a code smell - even a single effect can benefit from extraction to something with a good name, proper description, and isolated tests.
+
+  **Bucketing questions for refactoring:**
+  1. Does this logic need the React render loop? YES → Extract to a focused custom hook. NO → Extract out of React entirely (e.g., Onyx migration, global initialization).
+  2. Does this logic need to be in this component? YES → Keep it, but use a focused hook. NO → Extract to a separate component that owns this concern.
+
+  **Hook granularity guidance:**
+  - Group effects that serve the same purpose into one hook (e.g., all telemetry setup in `useTelemetry`)
+  - Group effects that can be reused together across components
+  - Don't create 15 separate single-effect hooks if 5 well-named grouped hooks make more sense
+
+Good (separated concerns):
+
+- Each piece of logic is extracted to a focused hook or component
+- Parent component only orchestrates what to render
+- State subscriptions in smaller components don't cause re-renders in parent
+- Component-scoped hooks can be co-located in the same directory for maintainability
+
+```tsx
+function DebugMenu() {
+    useDebugShortcut();
+
+    return (
+        // Debug menu UI
+    );
+}
+
+function ParentComponent({ reportID }: { reportID: string }) {
+    return (
+        <View>
+            {/* Each child owns its own concerns */}
+            <ReportView reportID={reportID} />
+            <DebugMenu />
+        </View>
+    );
+}
+```
+
+```tsx
+// Focused hook that does one thing well
+function useDebugShortcut() {
+    useEffect(() => {
+        const debugShortcutConfig = CONST.KEYBOARD_SHORTCUTS.DEBUG;
+        const unsubscribeDebugShortcut = KeyboardShortcut.subscribe(
+            debugShortcutConfig.shortcutKey,
+            () => toggleTestToolsModal(),
+            debugShortcutConfig.descriptionKey,
+            debugShortcutConfig.modifiers,
+            true,
+        );
+
+        return () => {
+            unsubscribeDebugShortcut();
+        };
+    }, []);
+}
+```
+
+Bad (side-effect spaghetti):
+
+- Component mixes session management, deep linking, telemetry, navigation, splash screen, audio, and other startup logic
+- Several unrelated `useOnyx` calls and `useEffect` hooks in a single component
+- Changing one concern risks breaking others
+
+```tsx
+function Expensify() {
+    // Session & auth
+    const [account] = useOnyx(ONYXKEYS.ACCOUNT);
+    const [session] = useOnyx(ONYXKEYS.SESSION);
+    
+    // Navigation & routing
+    const [lastRoute] = useOnyx(ONYXKEYS.LAST_ROUTE);
+    const [lastVisitedPath] = useOnyx(ONYXKEYS.LAST_VISITED_PATH);
+    const [isNavigationReady, setIsNavigationReady] = useState(false);
+    
+    // App state
+    const [updateAvailable] = useOnyx(ONYXKEYS.UPDATE_AVAILABLE);
+    const [updateRequired] = useOnyx(ONYXKEYS.UPDATE_REQUIRED);
+    const [isSidebarLoaded] = useOnyx(ONYXKEYS.IS_SIDEBAR_LOADED);
+    
+    // Splash screen
+    const {splashScreenState, setSplashScreenState} = useContext(SplashScreenStateContext);
+    
+    // ... 10+ more useOnyx calls for unrelated concerns ...
+
+    // Telemetry effect
+    useEffect(() => {
+        bootsplashSpan.current = startSpan(CONST.TELEMETRY.SPAN_BOOTSPLASH.ROOT, {...});
+        // ...
+    }, []);
+
+    // Public room checking effect
+    useEffect(() => {
+        if (isCheckingPublicRoom) return;
+        endSpan(CONST.TELEMETRY.SPAN_BOOTSPLASH.ONYX);
+        // ...
+    }, [isCheckingPublicRoom]);
+
+    // Splash screen effect
+    useEffect(() => {
+        if (!shouldHideSplash) return;
+        startSpan(CONST.TELEMETRY.SPAN_BOOTSPLASH.SPLASH_HIDER, {...});
+    }, [shouldHideSplash]);
+
+    // Deep linking effect
+    useEffect(() => {
+        Linking.getInitialURL().then((url) => {
+            if (url) {
+                openReportFromDeepLink(url, ...);
+            }
+        });
+        // ...
+    }, []);
+
+    // Audio mode effect
+    useEffect(() => {
+        Audio.setAudioModeAsync({playsInSilentModeIOS: true});
+    }, []);
+
+    // ... 10+ more useEffects mixing concerns ...
+}
+```
+
+In this example:
+- The component handles telemetry, deep linking, audio, session, navigation, splash screen, and more
+- Each concern is interleaved with others, making it hard to modify one without risking regression in another
+- Effects could be extracted to focused hooks: `useTelemetrySpans`, `useDeepLinking`, `useAudioMode`, etc.
+- Entry points don't get special treatment — extracting effects into named hooks improves clarity and makes it possible to understand what each effect does and how to safely modify it
+
+---
+
+### [CLEAN-REACT-PATTERNS-5] Keep state and subscriptions narrow
+
+- **Search patterns**: Contexts/hooks/stores exposing large bundled objects, providers with many unrelated `useOnyx` calls, state structures mixing unrelated concerns
+
+- **Condition**: Flag when a state structure (context, hook, store, or subscription) bundles unrelated concerns together, causing consumers to re-render when data they don't use changes.
+
+  **Signs of violation:**
+  - State provider (context, hook, or store) that bundles unrelated data (e.g., navigation state + list data + cache utilities in one structure)
+  - State object where properties serve different purposes and change independently
+  - Multiple unrelated subscriptions (`useOnyx`, `useContext`, store selectors) aggregated into a single exposed value
+  - Consumers of a state source that only use a subset of the provided values
+
+  **DO NOT flag if:**
+  - State values are cohesive — they change together and serve the same purpose (e.g., `keyboardHeight` + `isKeyboardShown` both relate to keyboard state)
+  - The state structure is intentionally designed as an aggregation point and consumers use most/all values
+  - Individual `useOnyx` calls without selectors — this is covered by [PERF-11]
+
+- **Reasoning**: When unrelated pieces of data are grouped into a single state structure, if an unused part changes, then all consumers re-render unnecessarily. This silently expands render scope, increases coupling, and makes performance regressions hard to detect. Structuring state around cohesive concerns ensures render scope stays predictable and changes remain local.
+
+**Distinction from PERF-11**: PERF-11 addresses individual `useOnyx` selector usage. This rule addresses state structure — how multiple values are grouped and exposed to consumers via contexts, hooks, or stores.
+
+**Distinction from CLEAN-REACT-PATTERNS-2**: PATTERNS-2 addresses data flow direction — parent shouldn't fetch data just to pass to children. This rule addresses how state is structured and grouped within any state provider.
+
+Good (cohesive state — all values serve one purpose):
+
+- All state relates to one concern (keyboard)
+- Values change together — no wasted re-renders
+- Derived state computed inline, not stored separately
+
+```tsx
+type KeyboardStateContextValue = {
+    isKeyboardShown: boolean;
+    isKeyboardActive: boolean;
+    keyboardHeight: number;
+};
+
+function KeyboardStateProvider({children}: ChildrenProps) {
+    const [keyboardHeight, setKeyboardHeight] = useState(0);
+    const [isKeyboardActive, setIsKeyboardActive] = useState(false);
+
+    useEffect(() => {
+        const showListener = KeyboardEvents.addListener('keyboardDidShow', (e) => {
+            setKeyboardHeight(e.height);
+            setIsKeyboardActive(true);
+        });
+        const hideListener = KeyboardEvents.addListener('keyboardDidHide', () => {
+            setKeyboardHeight(0);
+            setIsKeyboardActive(false);
+        });
+        return () => {
+            showListener.remove();
+            hideListener.remove();
+        };
+    }, []);
+
+    const contextValue = useMemo(() => ({
+        keyboardHeight,
+        isKeyboardShown: keyboardHeight !== 0,  // Derived, not separate state
+        isKeyboardActive,
+    }), [keyboardHeight, isKeyboardActive]);
+
+    return <KeyboardStateContext.Provider value={contextValue}>{children}</KeyboardStateContext.Provider>;
+}
+```
+
+Bad (grab-bag state — bundles unrelated concerns):
+
+- State provider subscribes to many unrelated Onyx collections
+- Exposed value mixes navigation state, list data, membership data, and cache utilities
+- Any consumer re-renders when ANY subscribed value changes
+
+```tsx
+function SidebarOrderedReportsContextProvider({children}) {
+    // ❌ Many unrelated Onyx subscriptions bundled together
+    const [priorityMode] = useOnyx(ONYXKEYS.NVP_PRIORITY_MODE);
+    const [chatReports] = useOnyx(ONYXKEYS.COLLECTION.REPORT);
+    const [policies] = useOnyx(ONYXKEYS.COLLECTION.POLICY);
+    const [transactions] = useOnyx(ONYXKEYS.COLLECTION.TRANSACTION);
+    const [transactionViolations] = useOnyx(ONYXKEYS.COLLECTION.TRANSACTION_VIOLATIONS);
+    const [reportNameValuePairs] = useOnyx(ONYXKEYS.COLLECTION.REPORT_NAME_VALUE_PAIRS);
+    const [reportsDrafts] = useOnyx(ONYXKEYS.COLLECTION.REPORT_DRAFT_COMMENT);
+    const [betas] = useOnyx(ONYXKEYS.BETAS);
+    const [reportAttributes] = useOnyx(ONYXKEYS.DERIVED.REPORT_ATTRIBUTES);
+
+    // ❌ Context value mixes unrelated concerns
+    const contextValue = {
+        orderedReports,         // List data
+        orderedReportIDs,       // List data
+        currentReportID,        // Navigation state
+        policyMemberAccountIDs, // Policy membership
+        clearLHNCache,          // Cache management utility
+    };
+
+    return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}
+
+// A component needing only currentReportID re-renders when orderedReports changes
+// A component needing only policyMemberAccountIDs re-renders when navigation changes
+```
+
+---
+
 ## Instructions
 
 1. **First, get the list of changed files and their diffs:**

Mobile-Expensify

@@ -114,8 +114,8 @@ android {
         minSdkVersion rootProject.ext.minSdkVersion
         targetSdkVersion rootProject.ext.targetSdkVersion
         multiDexEnabled rootProject.ext.multiDexEnabled
-        versionCode 1009031201
-        versionName "9.3.12-1"
+        versionCode 1009031502
+        versionName "9.3.15-2"
         // Supported language variants must be declared here to avoid from being removed during the compilation.
         // This also helps us to not include unnecessary language variants in the APK.
         resConfigs "en", "es"

android/app/build.gradle

@@ -1,32 +1,77 @@
 ---
-title: Personal Cards
-description: Learn how to track and manage your personal credit card expenses in Expensify through automatic imports or manual uploads.
-keywords: [New Expensify, personal cards, credit card import, CSV upload, SmartScan, eReceipts, reimbursements]
+title: Manage personal cards in New Expensify
+description: Learn how to view and manage personal credit cards in New Expensify.
+keywords: [personal cards, Wallet, reimbursable, credit card import, Expensify Classic, New Expensify, assigned cards, card details]
+internalScope: Audience is members with personal credit cards already connected to their account. Covers viewing and managing existing personal cards in the Wallet, including reimbursable settings. Does not cover adding new personal cards or company card programs.
 ---
 
+# Manage personal cards in New Expensify
 
-Tracking personal credit card expenses in Expensify is simple and flexible. Whether you're getting reimbursed or just organizing your spending, you can connect a personal card or upload transactions manually.
+Expensify lets you view and manage your personal credit cards in one place, making it easier to track spending, submit reimbursable expenses, and stay organized for tax time.
+
+If you previously connected a personal card in Expensify Classic, you can now manage that card directly in Expensify on both web and mobile.
+
+---
+
+## Who can manage personal cards
+
+You can manage personal cards if you have a personal credit card that was already connected to your account. You can manage these cards on both web and mobile, alongside any company cards on your account.
+
+---
+
+## Where to find personal cards in the Wallet
+
+1. Navigate to **Account > Wallet** on web or mobile.
+2. Under **Assigned cards**:
+   - Personal cards imported from Expensify Classic will appear here.
+   - You'll see the card name, bank icon, and last 4 digits.
+3. Tap the personal card you want to manage.
+
+If you have both company and personal cards, you'll see them separated into **Company cards** and **Personal cards** sections.
+
+![Tap a personal card to open card details]({{site.url}}/assets/images/personal-card-01.png){:width="100%"}
 
 ---
 
-# Overview
+## What you can do with personal cards
+
+You can: 
+- View all personal cards imported from Expensify Classic
+- Automatically import transactions from your linked personal cards
+- Generate IRS-compliant eReceipts for eligible USD purchases
+- Update personal card settings
+- Filter expenses by card in the **Expenses** tab on the **Reports** page
+
+---
 
-Once available in **New Expensify**, personal card connections will allow you to:
+## How to update personal card settings
 
-- **Automatically import transactions** from your linked card
-- **Manually upload CSV files** with your expense history
-- **Merge imported transactions with SmartScanned receipts**
-- Generate **IRS-compliant eReceipts** for eligible USD purchases
+1. Navigate to **Account > Wallet** on web or mobile.
+2. Under **Assigned cards**, select a personal card.
+3. On the **Card details** page, you can:
+   - Rename the card
+   - Update the card to pull in new transactions (if not CSV-imported)
+   - Unassign the card if it's no longer needed
+   - Toggle **Mark transactions as reimbursable**
+     - The reimbursable setting applies only to **new** transactions and is turned on by default.
 
-These features make it easy to capture personal expenses for reimbursement, tax reporting, or budgeting.
+**Note:** Unassigning a personal card permanently deletes any unreported expenses or expenses on draft reports from that card.
+
+![Update personal card settings from the card details page]({{site.url}}/assets/images/personal-card-02.png){:width="100%"}
 
 ---
 
-# Feature Status
+# FAQ
+
+## Can I add another personal card?
+
+Not yet. Only cards connected to your account in Expensify Classic are available to manage in New Expensify. Support for adding new personal cards will be available in a future update.
+
+## Can I change the reimbursable setting for past transactions?
 
-We’re currently building the personal card connection functionality for New Expensify. This feature is not yet available but will be released soon.
+No. Changes to the reimbursable setting only apply to transactions imported after the change. 
 
-Once it's live, we’ll update this article with full setup instructions, screenshots, and tips for managing your imported expenses.
+## Why don’t I see my personal card in the Wallet?
 
-**Stay tuned!** You can follow product announcements or contact Concierge for updates on availability.
+Personal cards appear in the Wallet only if they were previously connected to your account in Expensify Classic. If your card doesn’t show up, it means it wasn’t connected before and isn’t available to manage yet.