android: make back button actually go back

**Behavior**

Before it would always prompt to quit the app. Now, the back button
behavior is:

- if a frontend component is using `useBackButton(handler)`, then
handler is executed. If the handler returns false, stop. This is
useful for dialog components to inhibit the Android back button or
make it close the dialog.

- If there is no active frontend back button handler, or a handler was
executed and returns true, then the default behavior kicks in:
  - if we can go back in browser history, we go back
  - if we can't we prompt exiting the app

This commit contains this with a few frontend components modified to
use the useBackButton hook:
- wait dialogs make the back button do nothing, so user can't exit
  blocking dialogs when e.g. input on the BitBox02 is required
- close normal dialogs if they can be closed

**Future work to fix history back behavior everywhere**

There are many places where we need to fix navigate()/history.back()
behavior to make history.back() work as expected. This commit contains
one such fix in the BB02 passphrase flow. In general we want to
navigate(-1) instead of navigate forward on a back/abort click, and
navigate(-1) afte a flow finished instead of navigating forward, so
the back button does bring you back into the previous process.

Future PRs should fix it everywhere, e.g. "Back" buttons should mostly
just do `navigate(-1)`.

**webdev**

In webdev, the history back button has the same behavior as on Android
except for where useBackButton() is used, which is basically only in
dialogs, so one can test the back button behavior almost completely in
webdev. One can call `window.onBackButtonPressed()` in the console
invoke an active useBackButton hook handler like Android does if one
needs to test that, e.g. in a dialog.

**ALTERNATIVE dimsmissed**:

I spent an obscene amount of time trying to solve intercepting
"history back" in the frontend only using a combination of
history.pushState() and window.onpopstate(), and made it work, but
with downsides: - navigate() or history.pushState() could not be
called until the useBackButton hook became incative, which is
difficult to get right, e.g. `navigate()` after a blocking BB02
operation would happen while the useBackButton hook was still active
to inhibit the back button, leading to chaos.  - onpopstate() only
fires after history back was executed and cannot be prevented, so the
common workaround is to first do a pushstate(), then intercept it in
onpopstate() and pushState() again immediately. Since
history.pushState() and history.back() are asynchronous operations,
and useCallBack() could be rapidly remounted, it would fall out of
sync, so a queue processor was needed.

Generally the code complexity of the frontend-only solution was huge
and added requirements for how to use it correctly made me abandon the
approach.

**Code of alternative solution that was abandoned for the record**:

```backbutton.ts
import { useContext, useEffect, useRef } from 'react';
import { BackButtonContext, THandler } from '@/contexts/BackButtonContext';

export const useBackButton = (handler: THandler) => {
  const { pushHandler, popHandler } = useContext(BackButtonContext);

  // We don't want to re-trigger the handler effect below when the handler changes, no need to
  // repeat the push/pop pair unnecessarily.
  const handlerRef = useRef<(() => void)>(handler);
  useEffect(() => {
    handlerRef.current = handler;
  }, [handler]);

  useEffect(() => {
    pushHandler(handlerRef.current);
    return popHandler;
  }, [handlerRef, pushHandler, popHandler]);
};

// A convenience component that makes sure useBackButton is only used when the component is rendered.
// This avoids complicated useEffect() uses to make sure useBackButton is only active depending on
// rendering conditions.
// This also is useful if you want to use this hook in a component that is still class-based.
export const UseBackButton = ({ handler }: { handler: THandler }) => {
  useBackButton(handler);
  return null;
};
```

```BackButtonContext.ts
import { ReactNode, useContext, createContext, useEffect, useState, useCallback } from 'react';
import { usePrevious } from '@/hooks/previous';
import { runningOnMobile } from '@/utils/env';
import { AppContext } from './AppContext';

export type THandler = () => void;

type TProps = {
  pushHandler: (handler: THandler) => void;
  popHandler: () => void;
}

export const BackButtonContext = createContext<TProps>({
  pushHandler: () => {
    console.error('pushHandler called out of context');
    return true;
  },
  popHandler: () => {
    console.error('popHandler called out of context');
    return true;
  },
});

let queue: {
  action: 'pushState' | 'back';
  invoke?: () => void;
}[] = [];
let isProcessing = false;
let ignoreNext = 0;

function processQueue() {
  if (isProcessing || queue.length === 0) {
    return;
  }
  isProcessing = true;

  const item = queue.shift();
  if (!item) {
    return;
  }
  if (item.action === 'pushState') {
    console.log('QUEUE PUSH');
    window.history.pushState('BLOCKED', '', window.location.href);
  } else {
    console.log('QUEUE POP');
    window.history.back();
  }
  if (item.invoke) {
    item.invoke();
  }

  // Ensure the browser has time to process each navigation
  setTimeout(() => {
    isProcessing = false;
    processQueue();
  }, 100); // Adjust delay based on testing
}

type TProviderProps = {
  children: ReactNode;
}

export const BackButtonProvider = ({ children }: TProviderProps) => {
  const [handlers, sethandlers] = useState<THandler[]>([]);
  const { guideShown, setGuideShown } = useContext(AppContext);
  const previousGuideShown = usePrevious(guideShown);

  const callTopHandler = useCallback(() => {
    console.log('CALL TOP', handlers.length);

    if (handlers.length > 0) {
      const topHandler = handlers[handlers.length - 1];
      topHandler();
      return true;
    }
    return false;
  }, [handlers]);

  useEffect(() => {
    const handler = () => {
      if (ignoreNext > 0) {
        console.log('IGNORED', ignoreNext);
        ignoreNext--;
        return;
      }

      if (callTopHandler()) {
        queue.push({ action: 'pushState' });
        processQueue();
      }
    };
    window.addEventListener('popstate', handler);
    return () => {
      window.removeEventListener('popstate', handler);
    };
  }, [callTopHandler]);

  const pushHandler = useCallback((handler: THandler) => {
    console.log('pushHandler');
    sethandlers((prevStack) => [...prevStack, handler]);
    queue.push({ action: 'pushState' });
    processQueue();
  }, []);

  const popHandler = useCallback(() => {
    console.log('popHandler');
    sethandlers((prevStack) => prevStack.slice(0, -1));
    queue.push({ action: 'back' });
    ignoreNext++;
    processQueue();
  }, []);

  // On mobile, the guide covers the whole screen.
  // Make the back button remove the guide first.
  // On desktop the guide does not cover everything and one can keep navigating while it is visible.
  useEffect(() => {
    if (!runningOnMobile) {
      return;
    }
    if (guideShown && !previousGuideShown) {
      pushHandler(() => setGuideShown(false));
    }
    if (!guideShown && previousGuideShown) {
      popHandler();
    }
  }, [pushHandler, popHandler, guideShown, previousGuideShown, setGuideShown]);

  return (
    <BackButtonContext.Provider value={{ pushHandler, popHandler }}>
      {children}
    </BackButtonContext.Provider>
  );
};
```

Author: benma

frontends/android/BitBoxApp/app/src/main/java/ch/shiftcrypto/bitboxapp/MainActivity.java

@@ -582,12 +582,17 @@ public void onRequestPermissionsResult(int requestCode, String[] permissions, in
         }
     }
 
-    // The app cannot currently handle the back button action to allow users
-    // to move between screens back and forth. What happens is the app is "moved"
-    // to background as if "home" button were pressed.
-    // To avoid unexpected behaviour, we prompt users and force the app process
-    // to exit which helps with preserving phone's resources by shutting down
-    // all goroutines.
+    // Handle Android back button behavior:
+    //
+    // By default, if the webview can go back in browser history, we do that.
+    // If there is no more history, we prompt the user to quit the app. If
+    // confirmed, the app will be force quit.
+    //
+    // The default behavior can be modified by the frontend via the
+    // window.onBackButtonPressed() function. See the `useBackButton` React
+    // hook. It will be called first, and if it returns false, the default
+    // behavior is prevented, otherwise we proceed with the above default
+    // behavior.
     //
     // Without forced app process exit, some goroutines may remain active even after
     // the app resumption at which point new copies of goroutines are spun up.
@@ -601,20 +606,37 @@ public void onRequestPermissionsResult(int requestCode, String[] permissions, in
     // https://developer.android.com/guide/components/activities/tasks-and-back-stack
     @Override
     public void onBackPressed() {
-        new AlertDialog.Builder(MainActivity.this)
-            .setTitle("Close BitBoxApp")
-            .setMessage("Do you really want to exit?")
-            .setPositiveButton(android.R.string.yes, new DialogInterface.OnClickListener() {
-                public void onClick(DialogInterface dialog, int which) {
-                    Util.quit(MainActivity.this);
-                }
-            })
-            .setNegativeButton(android.R.string.no, new DialogInterface.OnClickListener() {
-                public void onClick(DialogInterface dialog, int which) {
-                    dialog.dismiss();
-                }
-            })
-            .setIcon(android.R.drawable.ic_dialog_alert)
-            .show();
+        runOnUiThread(new Runnable() {
+            final WebView vw = (WebView) findViewById(R.id.vw);
+            @Override
+            public void run() {
+                vw.evaluateJavascript("window.onBackButtonPressed();", value -> {
+                    boolean doDefault = Boolean.parseBoolean(value);
+                    if (doDefault) {
+                        // Default behavior: go back in history if we can, otherwise prompt user
+                        // if they want to quit the app.
+                        if (vw.canGoBack()) {
+                            vw.goBack();
+                            return;
+                        }
+                        new AlertDialog.Builder(MainActivity.this)
+                                .setTitle("Close BitBoxApp")
+                                .setMessage("Do you really want to exit?")
+                                .setPositiveButton(android.R.string.yes, new DialogInterface.OnClickListener() {
+                                    public void onClick(DialogInterface dialog, int which) {
+                                        Util.quit(MainActivity.this);
+                                    }
+                                })
+                                .setNegativeButton(android.R.string.no, new DialogInterface.OnClickListener() {
+                                    public void onClick(DialogInterface dialog, int which) {
+                                        dialog.dismiss();
+                                    }
+                                })
+                                .setIcon(android.R.drawable.ic_dialog_alert)
+                                .show();
+                    }
+                });
+            }
+        });
     }
 }

frontends/web/src/components/alert/Alert.tsx

@@ -18,6 +18,7 @@
 import { useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { MultilineMarkup } from '@/utils/markup';
+import { UseBackButton } from '@/hooks/backbutton';
 import { View, ViewButtons, ViewHeader } from '@/components/view/view';
 import { Button } from '@/components/forms';
 
@@ -62,6 +63,9 @@ const Alert = () => {
 
   return (active && message) ? (
     <form onSubmit={() => setActive(false)}>
+      <UseBackButton handler={() => {
+        setActive(false); return false;
+      }} />
       <View
         key="alert-overlay"
         dialog={asDialog}

frontends/web/src/components/dialog/dialog.tsx

@@ -17,6 +17,7 @@
 
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { CloseXDark, CloseXWhite } from '@/components/icon';
+import { UseBackButton } from '@/hooks/backbutton';
 import { useEsc, useKeydown } from '@/hooks/keyboard';
 import style from './dialog.module.css';
 
@@ -156,6 +157,13 @@ export const Dialog = ({
     }
   }, [deactivateModal]);
 
+  const closeHandler = useCallback(() => {
+    if (onClose !== undefined) {
+      deactivate(true);
+      return false;
+    }
+    return true;
+  }, [onClose, deactivate]);
 
   useEsc(useCallback(() => {
     if (!renderDialog) {
@@ -192,6 +200,7 @@ export const Dialog = ({
 
   return (
     <div className={style.overlay} ref={overlayRef}>
+      <UseBackButton handler={closeHandler}/>
       <div
         className={[style.modal, isSmall, isMedium, isLarge].join(' ')}
         ref={modalRef}>

frontends/web/src/components/wait-dialog/wait-dialog.tsx

@@ -15,12 +15,13 @@
  * limitations under the License.
  */
 
-import { Component, createRef, ReactNode } from 'react';
+import React, { Component, createRef, ReactNode } from 'react';
 import { translate, TranslateProps } from '@/decorators/translate';
 import approve from '@/assets/icons/hold.png';
 import reject from '@/assets/icons/tap.png';
 import style from '@/components/dialog/dialog.module.css';
-import React from 'react';
+import { UseDisableBackButton } from '@/hooks/backbutton';
+
 
 interface WaitDialogProps {
     includeDefault?: boolean;
@@ -140,6 +141,7 @@ class WaitDialog extends Component<Props, State> {
         className={style.overlay}
         ref={this.overlay}
         style={{ zIndex: 10001 }}>
+        <UseDisableBackButton />
         <div className={[style.modal, style.open].join(' ')} ref={this.modal}>
           {
             title && (

frontends/web/src/contexts/BackButtonContext.tsx

@@ -0,0 +1,92 @@
+/**
+ * Copyright 2024 Shift Crypto AG
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+*
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { ReactNode, useContext, createContext, useEffect, useState, useCallback } from 'react';
+import { runningOnMobile } from '@/utils/env';
+import { AppContext } from './AppContext';
+
+export type THandler = () => boolean;
+
+type TProps = {
+  pushHandler: (handler: THandler) => void;
+  popHandler: (handler: THandler) => void;
+}
+
+export const BackButtonContext = createContext<TProps>({
+  pushHandler: () => {
+    console.error('pushHandler called out of context');
+    return true;
+  },
+  popHandler: () => {
+    console.error('popHandler called out of context');
+    return true;
+  },
+});
+
+type TProviderProps = {
+  children: ReactNode;
+}
+
+export const BackButtonProvider = ({ children }: TProviderProps) => {
+  const [handlers, sethandlers] = useState<THandler[]>([]);
+  const { guideShown, setGuideShown } = useContext(AppContext);
+
+  const callTopHandler = useCallback(() => {
+    // On mobile, the guide covers the whole screen.
+    // Make the back button remove the guide first.
+    // On desktop the guide does not cover everything and one can keep navigating while it is visible.
+    if (runningOnMobile() && guideShown) {
+      setGuideShown(false);
+      return false;
+    }
+
+    if (handlers.length > 0) {
+      const topHandler = handlers[handlers.length - 1];
+      return topHandler();
+    }
+    return true;
+  }, [handlers, guideShown, setGuideShown]);
+
+  const pushHandler = useCallback((handler: THandler) => {
+    sethandlers((prevStack) => [...prevStack, handler]);
+  }, []);
+
+  const popHandler = useCallback((handler: THandler) => {
+    sethandlers((prevStack) => {
+      const index = prevStack.indexOf(handler);
+      if (index === -1) {
+        // Should never happen.
+        return prevStack;
+      }
+      return prevStack.slice(index, 1);
+    });
+  }, []);
+
+  // Install back button callback that is called from Android/iOS.
+  useEffect(() => {
+    window.onBackButtonPressed = callTopHandler;
+    return () => {
+      delete window.onBackButtonPressed;
+    };
+  }, [callTopHandler]);
+
+
+  return (
+    <BackButtonContext.Provider value={{ pushHandler, popHandler }}>
+      {children}
+    </BackButtonContext.Provider>
+  );
+};

frontends/web/src/contexts/providers.tsx

@@ -17,6 +17,7 @@
 import { ReactNode } from 'react';
 import { DarkModeProvider } from './DarkmodeProvider';
 import { AppProvider } from './AppProvider';
+import { BackButtonProvider } from './BackButtonContext';
 import { WCWeb3WalletProvider } from './WCWeb3WalletProvider';
 import { RatesProvider } from './RatesProvider';
 import { LocalizationProvider } from './localization-provider';
@@ -28,15 +29,17 @@ type Props = {
 export const Providers = ({ children }: Props) => {
   return (
     <AppProvider>
-      <DarkModeProvider>
-        <LocalizationProvider>
-          <RatesProvider>
-            <WCWeb3WalletProvider>
-              {children}
-            </WCWeb3WalletProvider>
-          </RatesProvider>
-        </LocalizationProvider>
-      </DarkModeProvider>
+      <BackButtonProvider>
+        <DarkModeProvider>
+          <LocalizationProvider>
+            <RatesProvider>
+              <WCWeb3WalletProvider>
+                {children}
+              </WCWeb3WalletProvider>
+            </RatesProvider>
+          </LocalizationProvider>
+        </DarkModeProvider>
+      </BackButtonProvider>
     </AppProvider>
   );
 };

frontends/web/src/globals.d.ts

@@ -25,6 +25,8 @@ export declare global {
         onMobileCallResponse?: (queryID: number, response: unknown) => void;
         onMobilePushNotification?: (msg: TPayload) => void;
         runningOnIOS?: boolean;
+        // Called by Android when the back button is pressed.
+        onBackButtonPressed?: () => boolean;
         webkit?: {
           messageHandlers: {
             goCall: {

frontends/web/src/hooks/backbutton.ts

@@ -0,0 +1,65 @@
+/**
+ * Copyright 2024 Shift Crypto AG
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { useContext, useEffect, useRef } from 'react';
+import { BackButtonContext, THandler } from '@/contexts/BackButtonContext';
+
+/**
+ * The Android back button will call this handler while this hook is active.
+ * The handler can perform an action and:
+ * - return false to stop any further action
+ * - return true for Android to perform the default back operation, which is going back in browser
+ * history if possible, or prompting to quit the app.
+*/
+export const useBackButton = (handler: THandler) => {
+  const { pushHandler, popHandler } = useContext(BackButtonContext);
+
+  // We don't want to re-trigger the handler effect below when the handler changes, no need to
+  // repeat the push/pop pair unnecessarily.
+  const handlerRef = useRef<THandler>(handler);
+  useEffect(() => {
+    handlerRef.current = handler;
+  }, [handler]);
+
+  useEffect(() => {
+    const handler = handlerRef.current;
+    pushHandler(handler);
+    return () => popHandler(handler);
+  }, [handlerRef, pushHandler, popHandler]);
+};
+
+/**
+ * A convenience component that makes sure useBackButton is only used when the component is rendered.
+ * This avoids complicated useEffect() uses to make sure useBackButton is only active depending on
+ * rendering conditions.
+ * This also is useful if you want to use this hook in a component that is still class-based.
+ * MUST be unmounted before any calls to `navigate()`.
+ */
+export const UseBackButton = ({ handler }: { handler: THandler }) => {
+  useBackButton(handler);
+  return null;
+};
+
+/**
+ * Same as UseBackButton, but with a default handler that does nothing and disables the Android back
+ * button completely.
+ */
+export const UseDisableBackButton = () => {
+  useBackButton(() => {
+    return false;
+  });
+  return null;
+};

frontends/web/src/routes/device/bitbox02/passphrase.tsx

@@ -20,6 +20,7 @@ import { useNavigate } from 'react-router';
 import { useEffect, useState } from 'react';
 import { getDeviceInfo, setMnemonicPassphraseEnabled } from '@/api/bitbox02';
 import { MultilineMarkup, SimpleMarkup } from '@/utils/markup';
+import { UseDisableBackButton } from '@/hooks/backbutton';
 import { Main } from '@/components/layout';
 import { Button, Checkbox } from '@/components/forms';
 import { alertUser } from '@/components/alert/Alert';
@@ -62,7 +63,7 @@ export const Passphrase = ({ deviceID }: TProps) => {
     try {
       const result = await setMnemonicPassphraseEnabled(deviceID, enabled);
       if (!result.success) {
-        navigate(`/settings/device-settings/${deviceID}`);
+        navigate(-1);
         alertUser(t(`passphrase.error.e${result.code}`, {
           defaultValue: result.message || t('genericError'),
         }));
@@ -75,7 +76,7 @@ export const Passphrase = ({ deviceID }: TProps) => {
     }
   };
 
-  const handleAbort = () => navigate(`/settings/device-settings/${deviceID}`);
+  const handleAbort = () => navigate(-1);
 
   if (isEnabled === undefined) {
     return null;
@@ -114,6 +115,7 @@ export const Passphrase = ({ deviceID }: TProps) => {
                 : 'passphrase.progressEnable.message')} />
           </ViewHeader>
           <ViewContent>
+            <UseDisableBackButton />
             <PointToBitBox02 />
           </ViewContent>
         </View>