Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add some docs for pattern B #10321

Merged
merged 3 commits into from
Aug 17, 2022
Merged

Add some docs for pattern B #10321

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6b5c657
Add some docs for pattern B
iwiznia Aug 9, 2022
5dfe0cc
Fix docs
iwiznia Aug 9, 2022
6614ebc
Update contributingGuides/OFFLINE_UX.md
iwiznia Aug 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions contributingGuides/OFFLINE_UX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,13 +61,28 @@ 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.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
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NAB: reads better with the bullet above if you switch this sub-bullet around to:

  • removes the data altogether, if the pendingAction was delete

- 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 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.
Expand Down