Note: if this is considered out of scope for the prototype, this task can be declined

Overview

We may want to introduce support for basic history navigation for the Image Browsing feature. Consider the use-case of someone skimming an article via the Visual TOC component. Once they click a "view in article" button here, the overlay will close and they'll be scrolled down on the page to wherever the given image is embedded.

Once a user does this, there is no way for them to easily get back to the previous state. If they click the relevant image in the article text that they just scrolled to, that will launch the traditional MediaViewer UI (not our new ImageBrowsing prototype). And if a user clicks the "back" button to try to restore where they just were (something which does work in MMV), they will be dumped on whatever previous web page they were looking at prior to landing on the current Wiki article.

Users may find this jarring or frustrating. Any intra-article navigation using the VTOC is a one-way trip.

A production version of this feature would implement support for URL fragments and history navigation. In this hypothetical scenario, launching the image browser would add a URL fragment to the page URL and would be recorded as a history entry. Changing the image in the detail view would probably update that URL fragment and add a new history entry; closing the image browsing overlay would remove the url fragment, and using the "forward" and "backwards" controls built into most Web browsers would allow users to move back and forth between previous UI states. Pasting an appropriate URL fragment into the browser's address bar would immediately trigger the UI in its appropriate state.

MVP scope

Doing all of the above is likely out-of-scope for our initial prototype. However, we may find it beneficial to the experience of users (even during early testing) to add some basic support for history navigation, without also introducing URL fragments for now.

This would mean that users who navigated to a specific part of the article page by clicking "view in article" in the VTOC would gain the ability to go back to where they were via the browser's "Back" button.

The simplest possible approach here would involve only adding a single entry to the browser history when the Image Browsing UI is opened, as well as another new one when it is closed. If desired, each update to the Detail View image could also be treated as a new history entry. No URLs would change, but using the forwards / backwards buttons would allow the user to move between history entries (however many we decide to define here).

Requirements

Assuming we want to support some basic version of this feature now, here are the requirements:

• Opening the Image Browsing UI (by clicking on a Carousel image) should cause an entry to be added to the Browser History via history.pushState. Key parts of UI state like the current active image should be serialized and stored as part of the state object this method receives as an argument.
  • Optional Each update to the Detail View image should also be stored this way if we wish to record changes here
• Closing the Image Browsing UI should also be recorded as a history entry
• When the user leaves the page entirely, the state should be stashed in LocalStorage so that backwards-navigation from elsewhere will restore the appropriate state of the Image Browsing UI
• Event listeners for popstate and pagehide events should be added (likely in the top-level App component)
• When the app first initalizes, it should check for prior history state that needs to be restored and handle it accordingly

Note: The code here could likely be adapted quickly as a starting point

QA

1. Navigate to an article page where the Image Browsing feature shows up
2. Trigger the UI (and change the detail view a few times if we are recording that event), and then:
   • Navigate to other parts of the article (using the VTOC "view in article" buttons), then hit "Back" to ensure the previous UI state restores successfully
   • Navigate to a new page entirely (by clicking a link in caption or paragraph text) and then click "back" to return to this article page; confirm that the previous UI state restores successfully
   • Move backwards and forwards through browser history in various ways and ensure the UI always restores itself successfully

BDD

Feature: Basic history navigation for Image Browsing

  Scenario: Opening and closing Image Browsing UI
    Given I am on an article with Image Browsing enabled
    When I open the Image Browsing UI from a carousel image
    Then a browser history entry is added with current UI state
    When I close the Image Browsing UI
    Then another browser history entry is added

  Scenario: Navigating inside article and back
    Given I have opened the Image Browsing UI and changed images
    When I click a VTOC “view in article” button
    And I press the browser Back button
    Then the previous Image Browsing UI state is restored

  Scenario: Navigating to a different page and back
    Given I have opened the Image Browsing UI
    When I click a link to navigate to a different article
    And I press the browser Back button
    Then the previous Image Browsing UI state is restored

  Scenario: Browser history navigation
    Given I have opened the Image Browsing UI and changed images multiple times
    When I move backwards and forwards using the browser history buttons
    Then the Image Browsing UI restores the correct state for each entry

Test Steps

Test Case 1: History entry on open/close

1. Open https://30eaa87caa.catalyst.wmcloud.org/wiki/Paris.
2. Click a carousel image to open Image Browsing UI.
3. AC1: A history entry is added.
4. Close the Image Browsing UI.
5. AC2: Another history entry is added.

Test Case 2: Navigate inside article and back

6. Open Image Browsing UI and navigate between detail images.
7. Click a “view in article” button in the VTOC.
8. Press browser Back.
9. AC3: The Image Browsing UI reopens with the same image shown as before.

Test Case 3: Navigate to new page and back

10. With Image Browsing UI open, click a text link to another article.
11. Press browser Back.
12. AC4: The Image Browsing UI reopens in the same state as before navigation.

Test Case 4: Move through history entries

13. Open Image Browsing UI and switch between several images if supported.
14. Use the browser Back and Forward buttons.
15. AC5: The UI restores to the correct state at each history step (open/closed and image selection).

QA Results - Patchdemo