From 6b5c657077b46b7fef6e9dbe65753c7d1bc9472b Mon Sep 17 00:00:00 2001 From: Ionatan Wiznia Date: Tue, 9 Aug 2022 17:29:57 +0200 Subject: [PATCH 1/3] Add some docs for pattern B --- contributingGuides/OFFLINE_UX.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/contributingGuides/OFFLINE_UX.md b/contributingGuides/OFFLINE_UX.md index ea61fac8a5b8..dc119dce92a9 100644 --- a/contributingGuides/OFFLINE_UX.md +++ b/contributingGuides/OFFLINE_UX.md @@ -61,13 +61,27 @@ This is the pattern where we queue the request to be sent when the user is onlin **How to implement:** Use [`API.write()`](https://github.com/Expensify/App/blob/3493f3ca3a1dc6cdbf9cb8bd342866fcaf45cf1d/src/libs/API.js#L7-L28) to implement this pattern. For this pattern we should only put `optimisticData` in the options. We don't need successData or failData as we don't care what response comes back at all. # B - Optimistic WITH Feedback Pattern -This pattern queues the API request, but also makes sure that the user is aware that the request hasn’t been sent yet **when the user is offline**. When the user is online, the feature should just look like it succeeds immediately (we dont want the offline UI to flicker on and off when the user is online). +This pattern queues the API request, but also makes sure that the user is aware that the request hasn’t been sent yet **when the user is offline**. +When the user is online, the feature should just look like it succeeds immediately (we don't want the offline UI to flicker on and off when the user is online). +When the user is offline: +- Things pending to be created or updated will be shown greyed out (0.6 opacity) +- Things pending to be deleted will have strikethrough **Used when…** - the user needs feedback that data will be sent to the server later This is a minority use case at the moment, but INCREDIBLY HELPFUL for the user, so proceed with cautious optimism. -**How to implement:** Use API.write() to implement this pattern. Optimistic data should include some pending state for the action that is reflected in the UI. Success/failure data should revert the pending state and/or set a failure state accordingly. +**How to implement:** +- Use API.write() to implement this pattern +- Optimistic data should include `pendingAction` ([with these possible values](https://github.com/Expensify/App/blob/15f7fa622805ee2971808d6bc67181c4715f0c62/src/CONST.js#L775-L779)) +- To ensure the UI is shown as described above, you should enclose the components that contain the data that was added/updated/deleted with the OfflineWithFeedback component + +**Handling errors:** +- The OfflineWithFeedback component already handles showing errors too, as long as you pass the error field in the errors prop +- When dismissing the error, the onClose prop will be called, there we need to call an action that either: + - If the pendingAction was `delete`, it removes the data altogether + - Otherwise, it would clear the errors and pendingAction properties from the data +- We also need to show a Red Brick Road (RBR) guiding the user to the error. We need to manually do this for each piece of data using pattern B. Some common components like `MenuItem` already have a prop for it (`brickRoadIndicator`) # C - Blocking Form UI Pattern This pattern greys out the submit button on a form and does not allow the form to be submitted. We also show a "You appear offline" message near the bottom of the screen. Importantly, we _do_ let the user fill out the form fields. That data gets saved locally so they don’t have to fill it out again once online. From 5dfe0ccd5ee9cdbfb88442f9080e8583ed988c90 Mon Sep 17 00:00:00 2001 From: Ionatan Wiznia Date: Tue, 9 Aug 2022 18:05:22 +0200 Subject: [PATCH 2/3] Fix docs --- contributingGuides/OFFLINE_UX.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributingGuides/OFFLINE_UX.md b/contributingGuides/OFFLINE_UX.md index dc119dce92a9..972f77a5a028 100644 --- a/contributingGuides/OFFLINE_UX.md +++ b/contributingGuides/OFFLINE_UX.md @@ -64,8 +64,8 @@ This is the pattern where we queue the request to be sent when the user is onlin This pattern queues the API request, but also makes sure that the user is aware that the request hasn’t been sent yet **when the user is offline**. When the user is online, the feature should just look like it succeeds immediately (we don't want the offline UI to flicker on and off when the user is online). When the user is offline: -- Things pending to be created or updated will be shown greyed out (0.6 opacity) -- Things pending to be deleted will have strikethrough +- Things pending to be created or updated will be shown greyed out (0.5 opacity) +- Things pending to be deleted will be shown greyed out and have strikethrough **Used when…** - the user needs feedback that data will be sent to the server later From 6614ebc8d7ce3f60ec8cece63af9f8571f2b5a1c Mon Sep 17 00:00:00 2001 From: Ionatan Wiznia Date: Fri, 12 Aug 2022 06:02:06 -0600 Subject: [PATCH 3/3] Update contributingGuides/OFFLINE_UX.md Co-authored-by: Puneet Lath --- contributingGuides/OFFLINE_UX.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/contributingGuides/OFFLINE_UX.md b/contributingGuides/OFFLINE_UX.md index 972f77a5a028..5e0e5748f052 100644 --- a/contributingGuides/OFFLINE_UX.md +++ b/contributingGuides/OFFLINE_UX.md @@ -81,7 +81,8 @@ When the user is offline: - When dismissing the error, the onClose prop will be called, there we need to call an action that either: - If the pendingAction was `delete`, it removes the data altogether - Otherwise, it would clear the errors and pendingAction properties from the data -- We also need to show a Red Brick Road (RBR) guiding the user to the error. We need to manually do this for each piece of data using pattern B. Some common components like `MenuItem` already have a prop for it (`brickRoadIndicator`) +- We also need to show a Red Brick Road (RBR) guiding the user to the error. We need to manually do this for each piece of data using pattern B Optimistic WITH Feedback. Some common components like `MenuItem` already have a prop for it (`brickRoadIndicator`) + - A Brick Road is the pattern of guiding members towards places that require their attention by following a series of UI elements that have the same color # C - Blocking Form UI Pattern This pattern greys out the submit button on a form and does not allow the form to be submitted. We also show a "You appear offline" message near the bottom of the screen. Importantly, we _do_ let the user fill out the form fields. That data gets saved locally so they don’t have to fill it out again once online.