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  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 ```