After exploring different approaches for suggestion navigation, we’ve aligned on the following direction:

We will use the existing pagination pattern (currently used in the pre-save moment and in the multiple checks) to navigate between suggestions. This will allow us to reuse familiar UI elements and avoid introducing new patterns into the system. We will use the decided solution to navigate both Suggestions and Checks across the article.

mobile	desktop

For what happens after a suggestion is completed or dismissed, there are 2 possible options that will be validated through usability testing in T424677:

	Op.1: No auto-advance after dismissing a suggestion (user manually navigates)
	Op.2: Auto-advance to the next suggestion after dismissing

Moving this task to Blocked until the usability testing in T424677 is completed and we can make an informed decision.

Based on findings from T424677, we will move forward with the following approach:

• We will reuse the pagination element (currently being used in the Pre-save moment in Edit Checks) to navigate between suggestions, showing the total count in the format "1 of 3 suggestions" and arrows to move between suggestions.
• When completing or dismissing a suggestion, the system will automatically advance to the next one. See T424677#11912325 for more context.
• Empty states will guide the users on next actions to do when completing/declining all suggestions in a section and in the full-page (T426062).

mobile	desktop

Check the prototype to see how it works: https://bmartinezcalvo.github.io/suggestion-mode/navigation-suggestions/test/auto/

I think there are some open questions about using a floating navigation control on desktop, specifically what happens when:

• the navigation control overlaps suggestion(s)
• "View suggestions" is visible, or when it becomes visible then invisible again via scrolling
• suggestions are collapsed (no suggestion selected) initially

When completing or dismissing a suggestion, the system will automatically advance to the next one.

I don't think we should do this. Taking the user away from the content they have just fixed and scrolling them possible many sections down seems very disorientating. It also makes it hard for them to visually verify the fix they have just made, for exampe many of our link checks currently deliberately focus the link after it has fixed (fix year link, fix redirect) and add-citation shows the citation preview.

El T417821#11940098, @Esanders escribió:

I think there are some open questions about using a floating navigation control on desktop, specifically what happens when:

• the navigation control overlaps suggestion(s)
• "View suggestions" is visible, or when it becomes visible then invisible again via scrolling
• suggestions are collapsed (no suggestion selected) initially

On desktop, the proposed behavior is:

1. The pagination would appear just when opening the 1st suggestion. This means the pagination would not be visible when the "View suggestions" button appears, since "View suggestions" button appears just to navigate to the 1st suggestion when it's not visible in the viewport.
2. The pagination includes a background to make it visible enough when overlapping with a suggestion

Check the prototype to understand how it would work: https://bmartinezcalvo.github.io/suggestion-mode/navigation-suggestions/test/auto/

When completing or dismissing a suggestion, the system will automatically advance to the next one.

I don't think we should do this. Taking the user away from the content they have just fixed and scrolling them possible many sections down seems very disorientating.

As identified during T424677#11912325, the automatic navigation on mobile allowed users to complete more suggestions sequentially, suggesting auto-advance encourages higher engagement when users are in a suggestion-resolving mode (which starts when they open and act on a suggestion). This is not considered disruptive since users can close the bottom sheet or turn suggestions off at any point if they prefer to focus on editing.

This automatic navigation was proposed on mobile, where navigating through the page and suggestions is more difficult. While, as proposed in the prototype this navigation would keep non-automatic on desktop where users could navigate suggestions either by scrolling or by using the pagination element proposed.

Note that there is also task T416468, focused on improving section navigation when editing full-page articles on mobile. This could help users move more easily between sections, which is currently difficult once they leave their original position.

It also makes it hard for them to visually verify the fix they have just made, for exampe many of our link checks currently deliberately focus the link after it has fixed (fix year link, fix redirect) and add-citation shows the citation preview.

At the moment, suggestions don't include a clear success state, which should be included in T404607. Without it, it is currently difficult for users to see what changed in the text after completing a suggestion — something that was also flagged during the usability testing T424677#11912325. For this reason, automatic navigation on complete should be implemented together with T404607. When suggestions include a completed state, the idea is:

1. If the suggestion was declined, it would automatically navigate to the next one.
2. If the suggestion was completed, the success state and change in the text would be cleary communicated right after completing the suggestion, and then the system would navigate to the next suggestion, making it possible to see the success before moving.

2. If the suggestion was completed, the success state and change in the text would be cleary communicated right after completing the suggestion, and then the system would navigate to the next suggestion, making it possible to see the success before moving.

I don't think we can always do automatic navigation after completing a suggestion, either delayed or instant. There may be a certain run of suggestions where it makes sense for users to step through suggestions like this, e.g. as seen in GrowthExperimnets - but I don't think it works generically for all our checks.

I don't think a success state is a sufficient substitution for showing the user the fixed content, for example in YearLink edit check you want to see the link target and link label after the fix. It would also rule out suggestions that only partially fix the content, for example the limited implementation of AddImage, which requires the user to add a caption after.

The pagination includes a background to make it visible enough when overlapping with a suggestion

I'm not sure about the semi transparent background and not aligning it within the sidebar, it makes for some distracting overlaps:

El T417821#11941236, @Esanders escribió:

2. If the suggestion was completed, the success state and change in the text would be cleary communicated right after completing the suggestion, and then the system would navigate to the next suggestion, making it possible to see the success before moving.

I don't think we can always do automatic navigation after completing a suggestion, either delayed or instant. There may be a certain run of suggestions where it makes sense for users to step through suggestions like this, e.g. as seen in GrowthExperimnets - but I don't think it works generically for all our checks.

I don't think a success state is a sufficient substitution for showing the user the fixed content, for example in YearLink edit check you want to see the link target and link label after the fix. It would also rule out suggestions that only partially fix the content, for example the limited implementation of AddImage, which requires the user to add a caption after.

@Esanders I think we would need to distinguisss between 2 type of suggestions:thanks for the feedback.

• Single-step suggestions: those ones that just need one action to complete a suggestion. In this case, we could use the auto-advance after a brief success state (1-2s), giving the user a moment to see the applied change before moving on.
• Multi-step suggestions (e.g. AddImage): in this case, we could use the auto-advance just when the user has completed all steps required. In the AddImage case, this suggestion would be considered completed just when the full flow is finished (add an image + add its caption). This would also make it clearer that an additional step is needed in the AddImage to fully complete that flow.

The pagination includes a background to make it visible enough when overlapping with a suggestion

I'm not sure about the semi transparent background and not aligning it within the sidebar, it makes for some distracting overlaps:

We could use a background-color-base instead, with a muted border if needed.

Regarding the pagination not aligned with the card, this is an error from the design prototype, but it should be aligned in the final implementation.

As decided during the internal meeting, when completing or dismissing a suggestion, the bottom sheet will close, preserving the scroll position where it is (no automatic scroll to the next suggestion).

Updated task description with decided solution and moving task to implement in the next sprint.

We will additionally need to work later on:

• T404607: Suggestions: share feedback after completing/dismissing a suggestion
• T429693: Suggestions: Implement "Next suggestion" navigation helper

Some questions as I implement this:

1. on mobile, when a user clicks edit on just a section, should the pagination be only throughout the suggestions in that section, or should it be throughout all suggestions in the article (and therefore open up full page editing if they navigate to a suggestion in another section)?
2. to confirm, there are no changes required on desktop?

El T417821#12055326, @medelius escribió:

Some questions as I implement this:

1. on mobile, when a user clicks edit on just a section, should the pagination be only throughout the suggestions in that section, or should it be throughout all suggestions in the article (and therefore open up full page editing if they navigate to a suggestion in another section)?
2. to confirm, there are no changes required on desktop?

1. Yes, pagination should always show the number of suggestions in that section (if you are in a section on mobile) or the entire article if you are editing the full page. If the user loads the full page by using the "Edit full page" button, the pagination would change to show all the suggestions in the article.
2. I initially designed this pagination for desktop, but I think it's better not to include more additional elements on the desktop interface unless we see there is a real need for that. So I would not implement the desktop pagination for now.
   

Thank you!

Once the user completes/dismisses a suggestion: the bottom sheet closes, with no automatic scroll to next suggestion

Is this the case also when the next suggestion is in the same section as the one that was just completed/dismissed? I'm wondering if I should keep the current behavior:

{F91263452}

(My vote would be no, as advancing for some and not for others could be confusing to the user.)

El T417821#12070958, @medelius escribió:

Thank you!

Once the user completes/dismisses a suggestion: the bottom sheet closes, with no automatic scroll to next suggestion

Is this the case also when the next suggestion is in the same section as the one that was just completed/dismissed? I'm wondering if I should keep the current behavior:

{F91263452}

@medelius I cannot see that image. But no, the automatic navigation to next suggestion would not happen in any case.

Change #1306804 had a related patch set uploaded (by Medelius; author: Medelius):

[mediawiki/extensions/VisualEditor@master] Suggestion mode: add pagination across all suggestions on mobile

https://gerrit.wikimedia.org/r/1306804

Test wiki created on Patch demo by CMedelius-WMF using patch(es) linked to this task:
https://34854fdf81.catalyst.wmcloud.org/wiki/Douglas Adams

@bmartinezcalvo , do you think you could review the patch demo when you get a chance?

@medelius reviewed the patch, sharing some things to fix:

1. The format of the pagination text (counter) should be "1 of 5 suggestions", aligning on the left (to be aligned with the title + description)
2. When navigating to next suggestion using the pagination, the highlighted text of that suggestion is so close to the displayed bottom sheet with just the 1st line of the highlighted text visible. Instead, all the highlighted text should be visible above the bottom sheet, or at least big portion of text if it's too long.
3. When a suggestion is declined the scroll position moves, causing to lose the place in the article. The scroll position should remain unchanged after either completing, declining, or closing a suggestion.
4. In the "Adjust heading level" suggestion, the Dismiss doesn't work, closing the bottom sheet but not dismissing that suggestion.
5. Pagination should appear even when there is 1 suggestion to show that just 1 suggestion needs to be completed, disabling the arrow button that doesn't navigate to that suggestion.

current	expected

Thank you, @bmartinezcalvo , I'll look at these.

One clarification though. Currently we show navigation between checks/suggestions within the same paragraph on mobile:

Will we no longer be doing that? That is, the only pagination that will show in mid-edit on mobile will be the "expected" screenshot on the right?

@medelius the idea is that stacked suggestions within the same paragraph are included in the total number of suggestions shown in the pagination. The badge on the icon trigger indicates how many suggestions are in that paragraph, while the pagination counts the overall navigation order.

Test wiki on Patch demo by CMedelius-WMF using patch(es) linked to this task was deleted:

https://34854fdf81.catalyst.wmcloud.org/wiki/Regent's Park

Test wiki created on Patch demo by CMedelius-WMF using patch(es) linked to this task:
https://e2abedeead.catalyst.wmcloud.org/wiki/Regent's Park

Ok, makes sense! I've updated the patch demo. All those are addressed except #4, which has been fixed in T432156.

Because we're having the pagination navigate among all suggestions and checks, it will say "x of y suggestions" even when there are checks. I think this is fine, but just wanted to note that.

@medelius thank you, adding some things we should still review:

1. If the pagination navigates among both suggestions and checks, then the previous format "x of y" made more sense, aligning it to the right (near the arrows) since the label is shorter.
2. Now, when navigating to next suggestion the highlighted text is so too high up, being too separate from the bottom sheet. It would be ideal if highlighted text could be more of less in the center of the screen, or near the bottom sheet without being part of the highlighted text behind.
3. When dismissing a suggestion right after using the pagination to navigate that suggestion, the scroll position still moves, losing the reference of that suggestion you were resolving.
   

1. hmmm, can you clarify: you'd like it to have both formats, depending on what's present (only suggestions vs both suggestions and checks)? or you want to go back to the previous format entirely...?

I'll take a look at 2 and 3!

El T417821#12124839, @medelius escribió:

1. hmmm, can you clarify: you'd like it to have both formats, depending on what's present (only suggestions vs both suggestions and checks)? or you want to go back to the previous format entirely...?

Yes, I meant going back to the previous format so the pagination format is consistent for both suggestions and checks. This includes:

• Removing the "suggestions" word from the "1 of 7"
• Aligning the label to the right (near the arrows)

If you want a fun edge-case, checks and suggestions are mixed together when they overlap, with the gutter section-widget showing the icon for the highest-severity of its contents.

1. If the pagination navigates among both suggestions and checks, then the previous format "x of y" made more sense, aligning it to the right (near the arrows) since the label is shorter.
2. Now, when navigating to next suggestion the highlighted text is so too high up, being too separate from the bottom sheet. It would be ideal if highlighted text could be more of less in the center of the screen, or near the bottom sheet without being part of the highlighted text behind.
3. When dismissing a suggestion right after using the pagination to navigate that suggestion, the scroll position still moves, losing the reference of that suggestion you were resolving.

1. Done
2. Done
3. It seems to be scrolling you back to where your cursor is whenever you close a suggestion. And with the navigation, I guess the cursor isn't updating? This happens in prod but is a lot less obvious given that the navigation doesn't take you through the whole article, the way it does in this patch. I'm not sure if I'm fully characterizing this right. I need to look more into it. Might create another ticket, though I think it's fair for this ticket to stay blocked on that fix.

Change #1312628 had a related patch set uploaded (by Medelius; author: Medelius):

[mediawiki/extensions/VisualEditor@master] Update linear selection after using pagination to navigate

https://gerrit.wikimedia.org/r/1312628

Change #1312628 merged by jenkins-bot:

[mediawiki/extensions/VisualEditor@master] Update linear selection after using pagination to navigate

https://gerrit.wikimedia.org/r/1312628

In T417821#12126451, @medelius wrote:

3. It seems to be scrolling you back to where your cursor is whenever you close a suggestion. And with the navigation, I guess the cursor isn't updating? This happens in prod but is a lot less obvious given that the navigation doesn't take you through the whole article, the way it does in this patch. I'm not sure if I'm fully characterizing this right. I need to look more into it. Might create another ticket, though I think it's fair for this ticket to stay blocked on that fix.

This has been resolved and I've updated the patch demo! Let me know if you notice any other issues, otherwise it's ready for code review.

@medelius it seems the scroll position still moves when resolving some suggestions. This is just happening when resolving the Fix year link, while it's not happening when resolving/dismissing the rest of suggestions:

Change #1306804 merged by jenkins-bot:

[mediawiki/extensions/VisualEditor@master] Suggestion mode: add pagination across all suggestions on mobile

https://gerrit.wikimedia.org/r/1306804