taler-android

Android apps for GNU Taler (wallet, PoS, cashier)
Log | Files | Refs | README | LICENSE

login-form-collapses-under-the-keyboard.md (6083B)


      1 <!--
      2   This file is part of GNU Taler
      3   (C) 2026 Taler Systems S.A.
      4 
      5   GNU Taler is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU General Public License as published by the Free Software
      7   Foundation; either version 3, or (at your option) any later version.
      8 
      9   GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
     12 
     13   You should have received a copy of the GNU General Public License along with
     14   GNU Taler; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 -->
     16 
     17 # On a phone, the login form disappears the moment you tap a field
     18 
     19 Tap the **Merchant portal URL** field on a phone-sized screen and the whole
     20 form goes away. Not scrolled out of reach -- gone. What is left is the title,
     21 the two tabs, and the keyboard:
     22 
     23 ![The login form on a phone, one tap after opening it](images/login-form-on-a-phone.png)
     24 
     25 The cashier is typing into a field that is not on the screen, cannot see what
     26 they have typed, cannot reach **Username**, **Password**, **Remember
     27 password** or **Connect**, and cannot scroll: nothing on the screen scrolls.
     28 The only way out is the Back key, which dismisses the keyboard and brings the
     29 form back -- and then the next tap on a field does it again.
     30 
     31 A terminal on a phone therefore cannot be provisioned by hand at all. The only
     32 route left is a `taler-pos://` setup URI.
     33 
     34 Look closely at the tab row as well: **"Manual config"** and **"QR config"**
     35 are sliced off along the bottom. That is the same squeeze seen from the other
     36 side -- the row is being measured into less height than its text needs.
     37 
     38 ## Why it happens
     39 
     40 `merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFragment.kt`:
     41 
     42 ```kotlin
     43 Box(
     44     modifier = Modifier
     45         .fillMaxSize()
     46         .systemBarsPadding()
     47         .imePadding(),                      // <- the whole screen shrinks
     48     contentAlignment = Alignment.TopCenter,
     49 ) {
     50     Column(
     51         modifier = Modifier
     52             .widthIn(max = if (isTabletLayout) 960.dp else 640.dp)
     53             .fillMaxSize()
     54             .padding(20.dp),
     55         verticalArrangement = Arrangement.spacedBy(16.dp),
     56     ) {
     57         RowButtons(mode = mode, …)          // the two tabs, a fixed height
     58         if (mode == ConfigMode.Manual) {
     59             ManualConfigScreen(
     60                 modifier = Modifier.fillMaxWidth().weight(1f),   // <- the form
     61                 …
     62             )
     63         }
     64     }
     65 }
     66 ```
     67 
     68 `imePadding()` takes the keyboard's height off the *whole screen*, and the
     69 form is the weighted child of what is left. On a phone in landscape -- 411 dp
     70 high -- the keyboard leaves about 150 dp. The system bars and the 20 dp
     71 padding take some, the tab row takes about 48 dp and the 16 dp arrangement
     72 takes 16 more, and the weighted child is measured at roughly nothing. A
     73 `LazyColumn` with no height composes no items, which is why the fields are
     74 absent from the view hierarchy rather than merely off screen, and why there is
     75 no scrollbar to drag: the list that would scroll has nothing in it.
     76 
     77 The tab row is clipped for the same reason, one step earlier: it is measured
     78 against a maximum height smaller than it asked for.
     79 
     80 On a tablet the same code is fine. 800 dp less a keyboard still leaves enough
     81 for three fields and a button, and what does not fit scrolls, because the
     82 `LazyColumn` is then big enough to exist.
     83 
     84 ## How it was found
     85 
     86 Every scenario that provisions through the form -- the whole `mock` set, and
     87 the login scenarios -- failed on the phone workers at the first field with
     88 
     89 ```
     90 PosError: no text field on screen at all;
     91     screen: ['QR config', 'Manual config', 'Merchant settings']
     92 ```
     93 
     94 eleven times out of eleven, in 19 seconds each. "No text field on screen at
     95 all" is a strange thing for a login form to say, so it was photographed rather
     96 than worked around, and the photograph is the bug.
     97 
     98 The same sequence by hand, with no harness in it: open the terminal
     99 unprovisioned, tap the URL field, look.
    100 
    101 ## Severity
    102 
    103 High on a phone, none on a tablet. It is the first screen of the app and it
    104 is the one screen a merchant cannot skip. There is no error, nothing blinks,
    105 and the keyboard behaves normally -- the form simply is not there, which reads
    106 like the app has crashed into a blank page.
    107 
    108 ## Suggested fix
    109 
    110 `login-form-collapses-under-the-keyboard.diff`, verified on the emulator the
    111 screenshot came from. Two changes, both in `ConfigScreen`:
    112 
    113 * **Put the tab row inside the form's own list** in Manual mode, so that it
    114   scrolls away instead of standing on the part of the screen the keyboard
    115   left. It is passed in as a `tabs: @Composable () -> Unit` and becomes the
    116   list's first item; QR mode keeps the row where it is, because it has nothing
    117   to type and a camera preview that wants a fixed height.
    118 * **Spend less of a short screen on padding**: 8 dp vertical rather than 20 dp
    119   where the layout is not a tablet.
    120 
    121 With both, the list is no longer measured at nothing, so it composes its items
    122 again: the fields are back in the hierarchy, `LazyColumn` scrolls the focused
    123 one above the keyboard, and the keyboard's own Next key walks the form the way
    124 it was meant to. The tab labels stop being clipped as well, because the row is
    125 no longer squeezed.
    126 
    127 What the patch does *not* do is make the whole form visible at once on a 411 dp
    128 landscape phone. The keyboard leaves about 150 dp, the app bar takes a third of
    129 that, and one text field is 56 dp -- so the form shows one field at a time and
    130 is walked with Next. That is a usable form rather than a good one; collapsing
    131 the app bar while the keyboard is up would be the next thing to try, and it is
    132 a design decision rather than a bug fix, so it is not in the patch.
    133 
    134 ## Reproducer
    135 
    136 ```bash
    137 POS_AVD_DEVICE=medium_phone POS_LCD_WIDTH=1920 POS_LCD_HEIGHT=1080 \
    138   POS_LCD_DENSITY=420 emu/emu.sh create 1
    139 emu/emu.sh boot 1 && emu/emu.sh prepare 1
    140 POS_WORKER=1 python3 driver/suite.py login_form_fits_a_phone
    141 ```