refund-form-unusable-on-a-phone.md (6215B)
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, a form with a text field loses its buttons to the keyboard 18 19 > **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it. 20 21 On a phone-sized screen the refund form opens, focuses its amount field, and 22 raises the keyboard -- and everything between the order summary and the 23 keyboard disappears. No amount field, no reason field, no **Approve refund**, 24 no **Abort**. 25 26  27 28 That is the whole screen. "Regular order" is the order summary, the band below 29 it is empty, and the keyboard is up for a field that is not on screen: the 30 cashier is typing a refund amount they cannot see, into a form they cannot 31 submit. The only way out is Back. 32 33 It is not a scrolling problem. The form does not scroll -- there is nothing to 34 scroll to -- and the controls are not merely below the fold: they are absent 35 from the view hierarchy entirely, which is how the harness noticed. 36 37 ## Why it happens 38 39 `merchant-terminal/src/main/java/net/taler/merchantpos/refund/RefundFragment.kt`: 40 41 ```kotlin 42 Column( 43 modifier = Modifier 44 .fillMaxSize() 45 .imePadding() 46 .padding(20.dp), 47 verticalArrangement = Arrangement.spacedBy(16.dp), 48 ) { 49 Text(item.summary) 50 OutlinedTextField(value = amountText, …) // focused by a LaunchedEffect 51 OutlinedTextField(value = reason, …) 52 Button(onClick = { submitRefund() }) { Text(…refund_confirm…) } 53 OutlinedButton(onClick = onAbort) { Text(…refund_abort…) } 54 Spacer(modifier = Modifier.weight(1f)…) 55 } 56 ``` 57 58 Three things combine: 59 60 * **The column cannot scroll.** There is no `verticalScroll`, so what does not 61 fit is not reachable. 62 * **`imePadding()` takes the keyboard's height off the column.** In landscape 63 on a 411 dp-high screen the numeric keyboard leaves a couple of hundred dp, 64 and the fixed children -- two text fields at 56 dp each, two buttons, and 65 40 dp of padding -- need more than that. 66 * **The amount field focuses itself** in a `LaunchedEffect(Unit)`, so the 67 keyboard is up before the cashier has touched anything. The screen is never 68 shown in its usable state. 69 70 The `Spacer` at the bottom carries a `detectTapGestures` that dismisses the 71 keyboard, which would be the way out -- but it is the weighted child, so it is 72 the first thing squeezed to zero height, and by the time the keyboard is up 73 there is nothing left of it to tap. 74 75 ## How it was found 76 77 The harness drives a phone-sized emulator as well as a tablet -- 1920x1080 at 78 420 dpi, which is 731x411 dp -- because five of the terminal's screens pick 79 their layout on `smallestScreenWidthDp`. `refund_full` and 80 `refund_amount_edges` pass on the tablet and fail on the phone, four runs each 81 way, and `order_custom_product_invalid_amount` typed a letter into the price 82 field where it meant to press Add. 83 84 What took three rounds to pin down is *where* it fails. `Pos.start_refund` 85 finds the form fine, because it puts the keyboard away before looking; the 86 failure lands later, on the tap for "Approve refund", after the amount has 87 been typed and the keyboard is back. A list of labels cannot tell "the app 88 clipped its controls" from "the driver is looking in the wrong place", so 89 `Pos._reach_approve_refund` now photographs the screen in that state before 90 doing anything about it. The picture above is that photograph. 91 92 ## Severity 93 94 High on a phone, none on a tablet. A merchant running the terminal on a phone 95 cannot refund anything through the UI at all. The terminal is landscape-locked, 96 so turning the device is not a workaround; dismissing the keyboard with Back 97 is, and nothing on the screen suggests it. 98 99 ## The same thing in the custom-product dialog 100 101 It is not one screen. The order screen's **Add custom product** dialog puts two 102 text fields above its Add and Abort buttons, and on a phone the keyboard covers 103 the buttons: 104 105  106 107 Here the dialog is clipped at the keyboard's top edge, with Add and Abort below 108 it. This one is worse than it looks from a hierarchy dump, because the 109 *buttons are still reported* at their layout coordinates -- the dialog is its 110 own window and knows nothing about the keyboard -- so a tap aimed at Add lands 111 on the key underneath. In the picture the field reads `nonsenseu`: the "u" is 112 the letter the harness pressed while trying to press Add. 113 114 A cashier does the same thing: the button they can see is a keyboard key. The 115 difference from the refund form is only that a `Material3 AlertDialog` is 116 dismissible by tapping outside it, so there is a way out. 117 118 ## Suggested fix 119 120 Let the column scroll, so nothing can be squeezed out of reach: 121 122 ```kotlin 123 Column( 124 modifier = Modifier 125 .fillMaxSize() 126 .imePadding() 127 .verticalScroll(rememberScrollState()) 128 .padding(20.dp), 129 … 130 ) 131 ``` 132 133 and consider not focusing the amount field on open, or keeping the buttons 134 outside the scrolling area so they are always on screen. The dialog wants the 135 same treatment: its `text` slot should scroll, so that the `confirmButton` and 136 `dismissButton` keep their place. 137 138 ## Reproducer 139 140 ```bash 141 POS_AVD_DEVICE=medium_phone POS_LCD_WIDTH=1920 POS_LCD_HEIGHT=1080 \ 142 POS_LCD_DENSITY=420 emu/emu.sh create 3 143 emu/emu.sh boot 3 && emu/emu.sh prepare 3 144 POS_WORKER=3 python3 driver/suite.py refund_full 145 ``` 146 147 The screenshot lands in `$POS_SIM_ROOT/out/refund-form-without-its-buttons.png`.