path: root/design-documents/053-wallet-ui.rst

DD 53: Wallet UI Design
#######################

Summary
=======

This document proposes designs wallet UI. It defines what Android, iOS and
WebExtension should follow in order to have a coherent UI between platforms.

Motivation
==========

We want user to be able to help each others independent of the implementation
they are using.
We want user to be able to capitalize the effort of learning how to use one
wallet and be able to use a different one without the need to learn
anything new.
Currently development of different platform specific implementation are independent
and every developer needs to choose the layout, texts and buttons and navigation.

Requirements
============

Every screen MUST be defined in a document with the following information:

* **Identifiable UI screens**: every UI should have an unique identifier that will
  be use for development discussion and bug reports. There should be an option
  in the application to enable an active rendering of the id.

* **Description**: the reason to be of the screen, should help to define what will
  be included into, what is going to left for other screens and when and from
  where should be linked.

The screen MAY also have:

* **Predefined assets**: every implementation should resue the same icons, images,
  fonts and sounds.

Additionaly the document COULD defined the components of the UI. If one of this
properties is defined in the spec the implementation must implement it. The specification
should be minimal to achieve the objective in the description.

* **Info**: Spec of information that the user should have access. The type of info
  could be a field (id and value) or a banner (information and instructions).
  The spec will help to reuse the text for i18n across apps and defined

* **Inputs**: Spec of information need to provide in current screen. The type of input,
  range of values and validation should be defined if necessary.

* **Actions**: Spec of buttons and interactable elements that will have a significant
  change in the current state. It should also mention navigation when applicable.

* **Layout**: Spec position of elements when needed. The spec should be "soft" in a sense
  that elements should be easy to find following directions like "close to X" or
  "at the start/end of the screen".

Screen should be defined using the most relaxed definition that are good enough to
be clear for the user. Platform will use this definition and adapt to the differences
on the platform taking advantange of platform API and screen sizes.

When a screen have multiple uses for the same purpose, a substate section should be
included with the difference with the main definition.

Part of the screens that are reused shoud also be defined in this document as screen.

Common definition:
 * navigation between screen should not happen if the user didn't take any action


Proposed Solutions
==================

List of all screens with the defined properties.

cta-withdraw
------------

``Description``: this screen is used for the confirmation of a manual withdrawal,
bank-integrated witdrawals and exchange withdrawals.
the success of this operation will be an increase of the balance in the wallet.
fee, restrictions and ETA should be clear for the user.

``Info``:
 * exchange to be used showing the URL
 * table of details of the operation: use the ``operation-table-details`` screen
 * starting currency: if the exchange has the currency conversion service enabled user should be able to the details based on the wire transfer currency
 * taler URI: show copy button or QR to complete the operation with another device

``Inputs``:
 * age restriction: allow the selection of the restriction in the age group possible by the exchange
 * service provider: allow the selection of different exchange

``Actions``:
 * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
 * review and confirm ToS: if the current selected exchange has a version  of ToS that the user didn't yet accepted, use the ``accept-tos`` screen
 * cancel: user will be redirected to ``balance``

.. attention::
  User should be able to play with the amount, not possible in the current design

cta-wire-transfer
-----------------

``Description``: this screen is used to show the user the information for
the wire transfer to complete a manual withdrawal operation.

``Info``:
 * wire transfer subject to be used (first, most important)
 * target bank account to transfer funds to (e.g. IBAN)
 * total amount to transfer in the wire transfer currency
 * button to copy ``payto://`` URI with the information to clipboard

``Actions``:
 * abort: aborts the withdrawal operation
 * menu: go back to the main balances list (operation continues in background)
 * automatic: screen changes to "cta-withdraw-done" upon completion

.. image:: ../screenshots/cta-wire-transfer-firefox-latest.png

cta-withdraw-done
-----------------

``Description``: this screen is used to show the user the information for
a completed withdraw operation (bank-integrated or manual)

``Info``:
 * amount wired  (hidden if no fees)
 * fees paid (hidden if no fees)
 * total amount withdrawn into wallet (effective balance change)
 * exchange base URL
 * date

``Actions``:
 * delete: deletes information about the withdrawal operation

.. image:: ../screenshots/cta-withdraw-done-firefox-latest.png


cta-url-entry
-------------

``Description``: this screen allows the user to scan a QR code, scan an NFC
tag, or enter a taler://-URL.  Its implementation may differ significantly
between platforms. For example, scanning NFC tags may be fully automated,
scanning QR codes may involve some system applications, and maybe the dialog
only allows the URL entry *or* the camera but not both at the same time,
depending on implementation specifics.

``Info``:
 * camera with current image to enable user to focus on QR code
 * current URL, with information if it is not well-formed for GNU Taler
 * possibly status information on NFC reader (if available)

``Actions``:
 * open: if entered manually, open URL as-entered (otherwise open is automatic)
 * back: return to previous view

.. image:: ../screenshots/cta-url-entry-firefox-latest.png


cta-payment
-----------

``Description``: this screen is used for the confirmation of a payment to a merchant.
the success of this operation will be an decrease of the balance in the wallet
and save a ticket/invoice of the purchase.
fee, restrictions and ETA should be clear for the user.

``Info``:
 * merchant offering the order showing the URL
 * order summary
 * table of details of the operation: use the ``operation-table-details`` screen
 * receipt: order id
 * payment deadline: absolute time before the claimed order expires
 * taler URI: show copy button or QR to complete the operation with another device
 * cant pay desc: if the user has enough balance but unable to use it
 * payment status: if the

``Actions``:
 * confirm operation: if the payment is possible, on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
 * get more cash: if there is not enough balance, it will be redirected to ``cta-witddraw``
 * cancel: user will be redirected to ``balance``

.. image:: ../screenshots/cta-payment-firefox-latest.png

cta-payment-paid
----------------

``Description``: this screen is used to show information with details
about a historic payment.

``Info``:
 * merchant offering the order showing the URL
 * order summary
 * table of details of the operation: use the ``operation-table-details`` screen
 * receipt: order id
 * payment status: if the order was refunded

``Actions``:
 * delete: delete information about the transaction
 * back: user will be redirected to ``balance``

.. image:: ../screenshots/cta-payment-paid-firefox-latest.png

cta-deposit
------------

``Description``: this screen is used for the confirmation of a deposit.
the success of this operation will be an decrease of the balance in the wallet
and save a deposit ticket for reference.
fee, restrictions and ETA should be clear for the user.

``Info``:
 * bank account where the money is going to
 * table of details of the operation: use the ``operation-table-details`` screen

``Actions``:
 * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
 * cancel: user will be redirected to ``balance``

.. attention::
  User should be able to play with the amount, not possible in the current design


cta-peer-pull-initiate
----------------------

``Description``: this screen is used for the confirmation of the creation of
a peer pull transaction or invoice to request money from another wallet.
the success of this operation will not change the balance immediately in the wallet
and allow the user to share a taler URI to the payer.
fee, restrictions and ETA should be clear for the user.

``Info``:
 * exchange to be used showing the URL
 * table of details of the operation: use the ``operation-table-details`` screen

``Inputs``:
 * subject: short description of the transaction
 * expiration: absolute time/date after which the invoice is not valid anymore
 * service provider: allow the selection of different exchange

``Actions``:
 * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
 * review and confirm ToS: if the current selected exchange has a version  of ToS that the user didn't yet accepted, use the ``accept-tos`` screen
 * cancel: user will be redirected to ``balance``

.. attention::
  Is the invoice creation always free of charge or does the exchange have a mechanism
  to impose a fee to pay on creation?


cta-peer-pull-confirm
---------------------

``Description``: this screen is used for the confirmation of the payment of
a peer pull transaction or invoice to send money from another wallet.
the success of this operation will be an will decrease the balance in the wallet.
fee, restrictions and ETA should be clear for the user.

``Info``:
 * exchange to be used showing the URL
 * subject: short description of the transaction
 * table of details of the operation: use the ``operation-table-details`` screen
 * expiration: absolute time/date after which the invoice is not valid anymore

``Actions``:
 * confirm operation: if the payment is possible, on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
 * get more cash: if there is not enough balance, it will be redirected to ``cta-witddraw``
 * cancel: user will be redirected to ``balance``

cta-peer-push-initiate
----------------------

``Description``: this screen is used for the confirmation of the creation of
a peer push transaction or transfer money to another wallet.
the success of this operation will reduce the balance immediately in the wallet
and allow the user to share a taler URI to the receiver.
fee, restrictions and ETA should be clear for the user.

``Info``:
 * table of details of the operation: use the ``operation-table-details`` screen

``Inputs``:
 * subject: short description of the transaction
 * expiration: absolute time/date after which the transfer is not valid anymore

``Actions``:
 * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
 * cancel: user will be redirected to ``balance``

cta-peer-push-confirm
---------------------

``Description``: this screen is used for the confirmation of the acceptance of
a peer push transaction or transfer money to this wallet.
the success of this operation will be an will decrease the balance in the wallet.
fee, restrictions and ETA should be clear for the user.

``Info``:
 * subject: short description of the payment
 * expiration: absolute time/date after which the invoice is not valid anymore
 * table of details of the operation: use the ``operation-table-details`` screen

``Actions``:
 * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
 * review and confirm ToS: if the current selected exchange has a version of ToS that the user didn't yet accepted, use the ``accept-tos`` screen
 * cancel: user will be redirected to ``balance``


operation-table-details
-----------------------

``Description``: with the table it should be clear how much the operation will cost,
the initial amount and the final amount with all the items related to the operations (like fee)

``labels``: initial amount of the operation, and final amount are always shown.
Fee should be shown as an extra row in the table if it is non-zero.
Converted amount should be shown as an extra row if initial amount currency is not the same
as the final amount currency.

Initial amount label by operation:

 * payment -> Price
 * deposit -> Send
 * peer-pull-credit -> Invoice
 * peer-pull-debit -> Invoice
 * peer-push-debit -> Send
 * peer-push-credit -> Transfer
 * withdrawal -> Transfer
 * refund -> Refund


accept-tos
----------

``Description``: this screen can be use everytime that the user is going to interact
with an exchange. since at any moment wallet may find that ToS changed the user needs
to be prevented from continue before reading/accepting new rules. If possible, this
screen should be used inplace of other actions and hidden if not required (for example,
user already accepted ToS)

``Inputs``:
 * format: allow the selection of a ToS format
 * languange: allow the selection of a languange different from system lang

``Actions``:
 * accept tos: will mark this version as accepted in wallet core and redirect the user to the screen from where it was invoked
 * save/print tos: will save the ToS outside of the wallet

.. image:: ../screenshots/cta-accept-tos-firefox-latest.png


Q / A
=====