Navigation modal

[smashwilson]

We have a common architectural element emerging among several features we'd like to add. I'd like to solve it in a consistent way so we can make different parts of the package feel familiar. Specifically:

• Navigating among merge conflicts: Navigation between merge conflicts #812
• Navigating between review comments on a review

Both of these fit the general pattern: "Given a set of markers on the files within a project, quickly jump from one to any other."

Some other characteristics they share:

• The sets of markers are ordered, but you may not wish to visit them in that exact order. You often want to jump to the next one, but not always.
• Each marker may be "resolved" or "unresolved." You may wish to revisit "resolved" markers after the fact, but it is less important than visiting a new "unresolved" one.

[smashwilson]

At the moment I'm thinking that we could have a button with a common icon - a map or a compass rose? - that triggers an atom-select-list modal. The select list's elements would be filename:row pairs, greyed out and sorted to the bottom if resolved. Navigate among the markers with up and down keys; choose one with core:confirm or cancel with core:cancel.

[smashwilson]

@simurai: I'd ❤️ to get your thoughts on what our options may be here 😄

In both your original mocks and in my old merge-conflicts package, we had next-previous arrows on the decorations at each navigable location that let you jump to the immediately adjacent places. I'm open to going that route too, but I feel like it has some drawbacks:

• You can only navigate if you're looking directly at a merge conflict location. If you've scrolled away to check something, you have to hunt for it again to get back into the navigation zone.
• You're limited to jumping to the two immediately adjacent conflicts; you can't easily go out of order.
• You don't have a good way to tell where you're going to end up if you click them - you could scroll down two lines, or jump to a completely different file.
• It doesn't give you any context about where you are in the overall merge conflict-slash-review. (This is less of a big deal, you get that from the progress bars elsewhere.)

[simurai]

Maybe both? A modal and prev/next buttons? Then you can quickly navigate to the next/prev or open the modal to get an overview and jump to a specific item.

[simurai]

Here another idea from talking to @donokuda. Clicking on the 🍔 button would show a "popover" to get a quick overview and to use as navigation. But you could also click the "expand" icon in the top-right corner. Then the content of the popover gets added to a dock item. Great of many reviews/conflicts that you want to keep more permanently in sight.

[kuychaco]

Some quick thoughts... drawing inspiration from Git, what about folding the text between the markers so that it's easy to get a quick overview of all of the conflicts to resolve or review comments to address. This would make general navigation easier because all of the markers are adjacent to each other. If people want to see more context, we can offer a way to unfold a few additional context lines like we do on dotcom.

And thinking about how I would personally want to navigate around, I think what I would want most is a simple keyboard shortcut that allows me to easily jump up and down, and maybe skip resolved comments/conflicts by holding down a modifier key.

The navigation modal could be cool and handy for getting an overview of everything, as well as how many items are left to address/resolve. But if we do the folded context thing, along with some progress indication then I think that could offer a good enough overview. That said, if we use a modal we could offer a way to filter decorations based on a fuzzy search which might be useful, say if you only want to look at comments pertaining to a certain person's review.

If we did have a modal, then the user would first have to open the modal, navigate to the entry they want, and then click enter. That's a lot of key presses. I personally would rather just jump around a bit with up/down arrow keys until I landed on what I wanted. But maybe that's just me!

The other interaction that came to mind is something akin to the "Find" results. The way I have my Atom configured, when I search for a term the search results open in a new pane on the right, and I scroll through them to get an overview of all of the results, and then as I click through them, the editor in the left pane jumps to the corresponding location. I could imagine having a dock item with an overview of all of the decorators, indicating which are resolved and which are not. Much like what @simurai has above ☝️

[smashwilson]

Some quick thoughts... drawing inspiration from Git, what about folding the text between the markers so that it's easy to get a quick overview of all of the conflicts to resolve or review comments to address. This would make general navigation easier because all of the markers are adjacent to each other. If people want to see more context, we can offer a way to unfold a few additional context lines like we do on dotcom.

Interesting!

For merge conflicts, I'm not sure if I'd prefer that kind of view, personally... I feel like resolving conflicts correctly often involves a lot of introspection in the surrounding file, like making sure the right things are imported, seeing how non-local methods were resolved, things like that. It's easiest for me to have confidence when I can see the full file with the conflicts marked within "the big picture." For review comments I think that makes a lot of sense because you can have comments that are interconnected and refer to one another.

I think what I kind of want to do is have markers on a folded-changes "all together" diff view which is its own pane item, to give a quick birds-eye perspective on the merge/review as a whole, and do some kind of navigation among them in the editors themselves? For merge conflicts that "all together" view can be a special "pending" commit pane item, like #1655 that shows up when you focus the commit message editor, which shows you all of the staged changes; for a pull request review, we could present this in a tab of the pull request's pane item.

That gives you different ways to see both perspectives: the size and scope of the conflicts / the full narrative flow of the review, and the merge conflict markers / review comment in its "native habitat" with the full file. We could also provide a quick way to jump between the two without losing your place, maybe.

In terms of implementation - the last time I looked at doing something like this with folding, I believe you can't currently fold arbitrary TextEditor regions, only ones derived from indentation or tree-sitter syntax nodes. So I'm not sure if we could use folds per se to implement this. We could either do what I ended up doing in the FilePatch editor work, where I'm building a distinct buffer to hold the modified text with custom line-number gutters, or we could enhance the TextEditor gutter API to allow arbitrary folds.

And thinking about how I would personally want to navigate around, I think what I would want most is a simple keyboard shortcut that allows me to easily jump up and down, and maybe skip resolved comments/conflicts by holding down a modifier key.

Yeah.

What should we do if you trigger the keyboard shortcuts when you're in an editor that has no conflicts/comments? Jump to the first or the first unresolved maybe? Or we could track the state of the last one you jumped to or interacted with, and either return there or use it as the starting point to find the next/previous?

Should we default to skipping resolved and require a modifier to include them, or the other way around?

If we did have a modal, then the user would first have to open the modal, navigate to the entry they want, and then click enter. That's a lot of key presses. I personally would rather just jump around a bit with up/down arrow keys until I landed on what I wanted. But maybe that's just me!

I'm leaning this way myself 😄 It seems like a lot of indirection. And in both cases we already have another place that gives you the full progress overview - the "merge conflicts" section of the git tab and the reviews tab of the pull request pane item.

The other interaction that came to mind is something akin to the "Find" results. The way I have my Atom configured, when I search for a term the search results open in a new pane on the right, and I scroll through them to get an overview of all of the results, and then as I click through them, the editor in the left pane jumps to the corresponding location. I could imagine having a dock item with an overview of all of the decorators, indicating which are resolved and which are not.

Hmmm 🤔 I like the idea of a bottom dock instead of the select modal. That's consistent with the way that you jump between linter errors and stuff in atom-ide, too.

---

Maybe both? A modal and prev/next buttons? Then you can quickly navigate to the next/prev or open the modal to get an overview and jump to a specific item.

👍 Sure, best of both worlds. Next / previous buttons are small 😄

One nit - maybe we could add the current keyboard shortcut to the button labels as a hint... ?

Clicking on the 🍔 button would show a "popover" to get a quick overview and to use as navigation. But you could also click the "expand" icon in the top-right corner.

Based on what @kuychaco said I'm not feeling the popover -- it's a few too many clicks to get around... -- but I am feeling an overview dock item 😄

One thing is that we do already have places where we show the "overview" for both cases: for conflicts, the git tab list; for reviews, the pull request pane item tab. Maybe clicking the hamburger could just reveal and focus the lists we already have, instead of creating a new one?

[Aerijo]

@smashwilson

I believe you can't currently fold arbitrary TextEditor regions, only ones derived from indentation or tree-sitter syntax nodes.

It’s not clean, but it’s possible. See https://github.com/bsegraves/custom-folds or https://github.com/Aerijo/latex-folding

[maxbrunsfeld]

You can fold arbitrary ranges of an editor with TextEditor.foldBufferRange and .foldBufferRowRange.

[smashwilson]

@maxbrunsfeld Oh! Neat. Good to know 👍

[GitMurf]

I posted in the other similar thread. Any updates on this? It seemed to just "drop dead" in conversation?

#812 (comment)