taler-android

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

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 ![The refund form on a phone, with the keyboard up](images/refund-form-on-a-phone.png)
     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 ![The custom-product dialog on a phone](images/custom-product-dialog-on-a-phone.png)
    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`.