feat(uss): Add navigation history and commands to traverse it

[JWaters02]

Proposed changes

Continuation of #3519 by adding the ability to navigate forwards and backwards through a "temporary" history for any given profile on the USS tree. "Temporary" means only filters added in the current session. This is seperate to persistence history.

Joe said he's been really wanting this for a long time, which is great as it adds on to the stuff added in #3519.

These buttons only appear when there are 2 or more items in the navigation history. This is because if there is no or one item, there is still nothing to navigate "through".

The buttons work as they do on any other file explorer as far as I am aware (honestly I did not look it up but just looked at Windows file explorer and my own intuition and coded it that way). I think it makes sense but there may still be some quirks or edge cases I have not thought about. So please have a play and lmk if you find any issues. Actually watching the demo video below I recorded, when I filtered on bin/dbx31, then went up a level, then pressed back button, I'd expect it to navigate back to bin/dbx31 but actually it navigated back to the previous filter on my userid, so that is unexpected.

2025-04-16.20-08-05.mp4

Release Notes

Milestone:

Changelog:

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• Enhancement (non-breaking change which adds or improves functionality)
• Breaking change (a change that would cause existing functionality to not work as expected)
• Documentation (Markdown, README updates)
• Other (please specify above in "Proposed changes" section)

Checklist

General

• I have read the CONTRIBUTOR GUIDANCE wiki
• All PR dependencies have been merged and published (if applicable)
• A GIF or screenshot is included in the PR for visual changes
• The pre-publish command has been executed:
  • v2 and below: yarn workspace vscode-extension-for-zowe vscode:prepublish
  • v3: pnpm --filter vscode-extension-for-zowe vscode:prepublish

Code coverage

• There is coverage for the code that I have added
• I have added new test cases and they are passing
• I have manually tested the changes

Deployment

• I have added developer documentation (if applicable)
• Documentation should be added to Zowe Docs
  • If you're an outside contributor, please post in the #zowe-doc Slack channel to coordinate documentation.
  • Otherwise, please check with the rest of the squad about any needed documentation before merging.
• These changes may need ported to the appropriate branches (list here):

Further comments

How do we feel about now having up to 5 buttons on the USS tree bar? In "normal" zoom levels I found it to be just about on the edge of not being too annoying blocking the path shown - but only for short paths. Longer paths are definately cut off. And when zoomed in a bit (e.g. for demo video so you can see better) it is cut off easily. So what do we want to do for that? Options:

1. Keep forward/back buttons on bar
2. Move them onto nodes "in the tree" maybe as the first nodes of the tree, kind of like trae's pagination arrow nodes
3. Make the buttons into context menu commands only

Something else this video doesn't show is the right click menu command "Reset Navigation History" which also only shows up when there are 2 or more items in the navigation history for a profile and when clicked removes the forward and backward buttons and deletes the "temporary" filter history. I feel like this would be a "nice to have" command but please do say if you think it is not necessary/useless (say NO! to command creep 😄)

Finally, there are messages that appear when you reach the "end" of navigation history to say there is no going forward or backward. Currently these are placeholder - I don't like how it works currently, so I feel like there are a few options when reached end:

1. Do nothing - user clicks on arrow but there is no feedback (ew from UX perspective, but is simple)
2. Hide or disable arrows when respective ends are reached & show or enable when there is new history (nicer UX but getting into a bit overengineered territory)
3. Keep some notification message but in a more subtle way somehow
4. "These messages are fine, stop overthinking it!" 😄

Docs: I looked at the USS tree docs and honestly the gifs there looks super duper old, they clearly need updating regardless! So maybe use this PR (and the previous one) as an oppurtunity to update those gifs as well as the text!

[zFernand0]

Hey @JWaters02,

I'll try to address some of the comments/questions and I'll love for others to chime in as well.

---

Docs: I looked at the USS tree docs and honestly the gifs there looks super duper old, they clearly need updating regardless! So maybe use this PR (and the previous one) as an oppurtunity to update those gifs as well as the text!

I believe @anaxceron expressed interest in possibly removing them for various reasons. I definitely see the burden (in storage and maintenance) that GIFs tend to cause.

---

I hope to have addressed most/all comments/questions 🙏

[zFernand0]

Options:

1. Keep forward/back buttons on bar
2. Move them onto nodes "in the tree" maybe as the first nodes of the tree, kind of like trae's pagination arrow nodes
3. Make the buttons into context menu commands only

In the past, we used to have 4+ icons at all times and people complained that it was a bit hard to remember their purposes (if they were not often used).

So, if we plan to keep them, I rather give people the ability to customize which icons they want to keep inline.

Otherwise, I'd vote for option 3: Make the buttons into context menu commands only

[zFernand0]

a few options when reached end:

1. Do nothing - user clicks on arrow but there is no feedback (ew from UX perspective, but is simple)
2. Hide or disable arrows when respective ends are reached & show or enable when there is new history (nicer UX but getting into a bit overengineered territory)
3. Keep some notification message but in a more subtle way somehow
4. "These messages are fine, stop overthinking it!" 😄

I believe that we have made some efforts to reduce the number of notifications/pop-up messages that show up in order to minimize distractions. I understand that there need to be some sort of feedback for these buttons, but I'd personally prefer to gray-out/disable them instead of a pop-up saying that we didn't do anything. If we must keep a subtle message, perhaps we could use the status bar (e.g. same thing as uploading content).

I'd vote for option 2. Perhaps we can replace the icon (or overlay a 🚫 icon to it) if we know they are already at the root 😋

If that ends up being too complex, then option 3 with a status bar message. 🙏

[zFernand0]

Something else this video doesn't show is the right click menu command "Reset Navigation History" which also only shows up when there are 2 or more items in the navigation history for a profile and when clicked removes the forward and backward buttons and deletes the "temporary" filter history. I feel like this would be a "nice to have" command but please do say if you think it is not necessary/useless (say NO! to command creep 😄)

While this may be nice for those who might use the back and forward commands a lot, I don't think this is necessary (or even common) since I don't think there is such a thing in other File explorer (MacOS Finder, Windows File Explorer).

For that reason, I'd vote to remove this 😅
But I'm fine if everyone else wants to keep it 😋

[Joe-Winchester]

I like the back and foward butons, you're right they aren't in File explorers, but they do occur in browsers.
One point I did notice is that the arrow buttons act on the filter/search criteria so I'm wondering if there is a way they can be moved to the right of the icons and have the refresh contents on the left.
My vote would be not to have the navigate as menu actions and leave as buttons to make point and shoot easier.
Q: For accessiblity and keyboard warriors, is there a way to execyte these with a key action ?

Two other questions ?
Is there a way to make the hover help dynamic, so that for a button that navigates to a new top level folder show what that folder is/will be ?

[JWaters02]

Thanks for the feedback @zFernand0 somehow I only just noticed this! 😅

With some feedback from Joe in slack, I want to just outline the changes I think I should make (pending also the standup later today):

• Remove "Reset navigation history" command - I agree it is a bit of a useless feature
• Keep the arrows in the profile bar as they are super obvious what they do and useful to have - but perhaps allow users to select what they want to be inline
• Change the order of the icons on the bar, maybe group together the arrows with the search and have refresh on its own?
• Enable/disable the arrows if there is/is not history to navigate through (can be done by editing node.context)
• Currently the up arrow hides itself until necessary, so just switch that to also enable/disable to be consistent
• Add keybinds for all 3 navigation arrows for power users
• Add hover info to the arrows that show which path would be navigated to if clicked
• Rename "Search by directory" command to something better, e.g. what Billie suggested Step into directory, Set filter or Set top level path etc.
• Maybe also add Add double-click action to search into a USS folder #3666 but that should be in a future PR
• Rewrite USS docs page and remove gifs from it

Keep the arrows in the profile bar as they are super obvious what they do and useful to have

Joe pointed out that using the arrows for switching back and forth between different locations is basically the same as just adding those locations to your favourites. So would this feature even be necessary if that is what users actually use it for? It's hard to tell without getting more end-user feedback.

Change the order of the icons on the bar, maybe group together the arrows with the search and have refresh on its own?

Remember that USS is more like a file explorer than a browser - i.e. in a browser, refresh button is most important as contents are super dynamic, while in a file explorer, refresh button is not that important as contents don't change much.
Windows File Explorer:

MacOS Finder:

Chrome: