taler-android

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

action-buttons-have-no-accessible-name.md (6525B)


      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 # Unnamed controls: the seven action buttons, and the way out of selection mode
     18 
     19 Found while teaching the simulator to tap them: the taps did nothing, because
     20 the label a sighted user reads is not part of the button at all. A screen
     21 reader has the same problem.
     22 
     23 **Severity: moderate, and it affects release builds** — these are the wallet's
     24 primary actions, and they are unusable with TalkBack.
     25 
     26 All seven buttons on the main screen are the same `ActionButton`: Send,
     27 Request, Withdraw, Deposit, and -- further down -- Discounts, Passes and
     28 Donation statements (`balances/BalancesPagerComposable.kt`, seven call sites).
     29 Every other floating action button in the app does set a
     30 `contentDescription`, so this one composable is the whole defect.
     31 
     32 ## What happens
     33 
     34 On the main screen the balance card shows four buttons. Each one is a
     35 `FloatingActionButton` holding only an icon, with the text in a *sibling*
     36 `Text` below it:
     37 
     38 ```
     39 Button    clickable=true   text=''  content-desc=''   bounds=[332,887][479,1034]
     40 TextView  clickable=false  text='Request'             bounds=[338,1050][473,1103]
     41 ```
     42 
     43 So the clickable element has no name and the name is not clickable. TalkBack
     44 announces the button as just "Button, double tap to activate"; the label is
     45 read separately as static text, with nothing tying the two together.
     46 
     47 Seven clickable nodes on the main screen have no accessible name of their own
     48 *and* no labelled descendant to inherit one from — these four among them. (A
     49 clickable wrapper whose label is a child is fine: Compose merges the semantics
     50 and TalkBack reads the child. Only a label that is merely a *neighbour*, as
     51 here, is lost.)
     52 
     53 ## The same omission on the transactions screen
     54 
     55 Found later, while driving the dedicated transactions screen's selection mode:
     56 the button that leaves selection mode is unnamed too.
     57 
     58 ```kotlin
     59 // wallet/src/main/java/net/taler/wallet/transactions/TransactionsScreen.kt:111
     60 navigationIcon = if (selectionMode) {
     61     {
     62         IconButton(onClick = { selectionMode = false; selectedItems.clear() }) {
     63             Icon(imageVector = Icons.Rounded.Close, contentDescription = null)
     64         }
     65     }
     66 } else null,
     67 ```
     68 
     69 It is the only way out of selection mode and the only thing inside the button,
     70 and it sits where the back arrow normally is — so a screen reader user is told
     71 there is a button, not what it does or that it has replaced the back arrow.
     72 "Select All" beside it *is* described, which is what makes the omission look
     73 like an oversight rather than a decision.
     74 
     75 The simulator had to find it by position for the same reason:
     76 
     77 ```
     78 - 1 unnamed clickable(s) in the app bar: [(12, 150, 138, 276)]
     79 ```
     80 
     81 The patch gives it `R.string.transactions_leave_selection`
     82 ("Leave selection mode"), beside the existing `transactions_select_all`.
     83 
     84 ## Reproduce by hand
     85 
     86 With TalkBack, as a user would hit it:
     87 
     88 1. Install the wallet and get a balance into it (withdraw once — against the
     89    local stack, or `Settings → Withdraw demo KUDOS` on a debug build).
     90 2. Enable TalkBack (Settings → Accessibility → TalkBack on the device).
     91 3. Go to the wallet's main screen and swipe right repeatedly to move the
     92    accessibility focus along the balance card.
     93 4. Focus lands on four buttons in a row. Each is announced as an unnamed
     94    button; the words "Send", "Request", "Withdraw", "Deposit" are announced as
     95    separate text, after or before the button they belong to.
     96 
     97 Without TalkBack, from a shell — the same thing, in the accessibility tree:
     98 
     99 ```bash
    100 adb shell uiautomator dump /sdcard/ui.xml
    101 adb exec-out cat /sdcard/ui.xml | tr '>' '>\n' | grep -E 'Button|Request'
    102 ```
    103 
    104 The `android.widget.Button` nodes carry `text=""` and `content-desc=""`, while
    105 the `Request` text sits in a non-clickable `TextView` underneath.
    106 
    107 ## Reproduce with the simulator
    108 
    109 ```bash
    110 ssh root@tripwire.taler.net
    111 cd /opt/taler-sim/driver
    112 python3 ../findings/repro_action_buttons_no_a11y_name.py --fund
    113 ```
    114 
    115 Prints each label, the button it really belongs to and that button's
    116 accessible name, then `reproduced: True`.
    117 
    118 ## Why
    119 
    120 `compose/ActionButton.kt:47` builds a `Column` of a `FloatingActionButton` and
    121 a label, and every caller passes an icon with no description
    122 (`BalancesPagerComposable.kt:651` and the three below it):
    123 
    124 ```kotlin
    125 ActionButton(
    126     icon = { Icon(Icons.AutoMirrored.Default.ArrowForward, contentDescription = null) },
    127     label = { Text(stringResource(R.string.transactions_send_funds)) },
    128     ...
    129 )
    130 ```
    131 
    132 `contentDescription = null` is right for a decorative icon *inside* a named
    133 control, but here it is the only thing in the control, so the control ends up
    134 nameless.
    135 
    136 ## Suggested fix
    137 
    138 Merge the column's semantics so the label names the button, in `ActionButton`
    139 itself rather than in each of the four call sites:
    140 
    141 ```kotlin
    142 Column(
    143     modifier.semantics(mergeDescendants = true) {},
    144     horizontalAlignment = Alignment.CenterHorizontally,
    145 ) {
    146 ```
    147 
    148 That gives the whole column one accessibility node named after the label, which
    149 also makes the much larger column the touch target. Passing the label string as
    150 the icon's `contentDescription` would fix the announcement too, but leaves the
    151 label as a second, redundant focus stop.
    152 
    153 One change covers all seven, which is why it belongs in `ActionButton`: the
    154 Discounts / Passes / Donation statements row is built from the same composable,
    155 and the main screen's QR scanner FAB, the exchange list's, the contact list's
    156 and the bank account list's all set a `contentDescription` already.
    157 
    158 The second half of the patch is the one-line omission on the transactions
    159 screen, with `transactions_leave_selection` ("Leave selection mode") added
    160 beside `transactions_select_all` in `strings.xml`. Verified together:
    161 `:wallet:compileFdroidDebugKotlin` and `:wallet:lintFdroidDebug` clean, and all
    162 nineteen patches still apply together and build.