[MVC] - Context switcher

Problem to solve

Users need an easy way to switch between groups, projects, and other sections within GitLab. The current Main Menu provides this capability, but it isn't intuitive what lives within the menu, as well as it is cumbersome to navigate options.

Proposal

Introduce a new "context switcher", which will replace the current context header in the sidebar and act as a convenient way for users to switch between objects and sections within GitLab.

Implementation Guide

Resources

• Figma File
• Prototype
• Codepen example (for animation)

Criteria

• Styling of context switcher should align to designs below
• Include persistent links at the top (Your work, Explore, Admin (if Administrator)) !114945 (merged)
• Utilize the current Frequent Projects/Groups that we store today for users, displayed as options as seen in the design (Projects - max 5, Groups - max 3)
• When there are no Frequent Projects or Groups, include an empty state message (see design)
• Provide a link to "View all projects" and "View all groups" at the end of each "Frequent" listing

When clicking on the context switcher...

• Toggle the menu with animation (see Codepen).
• Toggle the chevron icon based on it's state
• Update the styling of the context switcher (background and chevron color) !114643 (merged)
• If opening the context switcher menu, focus the search field !114643 (merged)

When searching within the context switcher...

• Hide the persistent links at the top !114491 (merged)
• Show results for Projects and Groups under respective headings !114491 (merged)
• [-] Include the result count for Projects and Groups within their heading We have decided to not do this for now.
• Limit the amount of matches for Projects and Groups to each be 20 (same as today in Main Menu) !114491 (merged)
• Allow the Project/Group result sections to be collapsable (for instance, in case a user only cares about Groups) !114945 (merged)
• When there are no matches for Projects or Groups, include a "No matches" message (see design) !114491 (merged)
• Provide a link to "View all projects" and "View all groups" at the end of the associated result groupings/lists !114491 (merged)

Follow-up

• Look into truncating titles and subtitles within the frequent items lists. !114945 (merged)

Note: Designs for the context switcher in the collapsed state as well as mobile are not shown here, as my assumption is that will be handled in the corresponding issues/epics for collapsed state and mobile.

added Category:Navigation & Settings devopscreate sectiondev typefeature workflowdesign labels

added to epic &9045 (closed)

changed epic to &9044

changed title from MVC 2 - Context switcher to [MVC] - Context switcher

changed the description

added UX frontend workflowready for design labels and removed workflowdesign label

mentioned in issue #370618 (closed)

added 2 designs

First of all, apologies if this was answered in the demo/prototype.

I'm not clear on how the context switcher will work in practice in certain cases. In the ideal case, I imagine it'd take you to the equivalent page for the project or group you choose. For instance, if you're on /gitlab-org/gitlab/-/issues, and you switch to the Pajamas Adoption Scanner project, you'll go to /gitlab-org/frontend/pajamas-adoption-scanner/-/issues.

Some cases I'm less clear on:

• You're on a particular merge request, e.g., /gitlab-org/gitlab/-/merge_requests/123456 and you switch context. Where does it take you? Perhaps the merge requests list? Similarly for a particular issue, milestone, board, and so on.
• You might have more access on some projects/groups that others. For instance, say you're a maintainer on Pajamas, but only a developer on GitLab. So, if you're on /gitlab-org/gitlab-services/design.gitlab.com/edit, and you switch to GitLab, where would it take you? It shouldn't 404. Maybe the "default" page for a project or group, like the new overview?

Good question @markrian ! At this point we plan to handle the context switcher similar to how it is handled in the Main Menu today. Meaning that the links to other contexts (groups/projects) would take you to their respective overview pages. We wouldn't be keeping you in the same location within the context (ex: Issues). It's something to consider down the road, though there are problems with an approach like that as you mention which would need to be worked out. For now, we want isolate some of these changes (such as moving where users go to navigate to certain items rather than changing their functionality).

Another thing that was discussed during the sync call was potentially changing the Recent (today Frequently visited) options in the switcher to things like Favorites. This is definitely something we have considered, but again we want to isolate some of the changes for now as well as do some further research into how users are using things like Favorites today. Some may use that functionality to get back to projects they utilize often, while others may simply favorite projects that they like but don't necessarily interact with commonly.

Hopefully that answers your question and all makes sense

More of a technical questions than about the design:

Should we make this a Vue app, or render with Rails together with the rest of the sidebar?

My first idea is to make it a Vue app, because it is not required to have the context switcher's menu items ready on first page load. We can just load it async, latest when the user clicks on the context switcher. This should save us some querying/caching and Haml render time.

WDYT @gitlab-org/manage/foundations/engineering

This is a very good question. There might be some pages though which show the context switcher per default (e.g. pages that have no sidebar as of today). I wonder how much activity the sidebar has in the end. Maybe a tightly coupled ViewComponent / VueComponent hybrid would be the best solution?

Will we continue rendering the sidebar menu itself server-side (not the switcher, but the current in-group/in-project menu)? It's still important at least for discoverability (crawling), right? Sorry to jump out of blue with this

Meanwhile dreaming of Vue SSR 🥰

mentioned in issue gitlab-org/manage/foundations/team-tasks#164

I remember we discussed that the context switcher will be something like a dropdown. But it certainly won't as it would be weird to have the dropdown covering the sidebar. I imagine that clicking the toggle will just replace the content in the sidebar. @nickbrandt how does this transition happen - some kind of animation - skeleton loader maybe? Also as we talk about open/closed states for the context switcher there is no visual indication of that. Should the arrow down be replaced with arrow up when it is open?

@ohoral thanks for the questions! My thoughts below:

I imagine that clicking the toggle will just replace the content in the sidebar.

Yes, that is correct.

how does this transition happen - some kind of animation - skeleton loader maybe?

At the top of the Navigation North Star Path figma file there is a link to the prototype (still a work in progress), which helps show how this work. At this point I'm leaning to there not be much of an animation for this and it being more instant similar to that of our dropdown component. I would propose we don't use a skeleton loader unless necessary. Today, if you click on our Main Menu, the options appear immediately. Since the context switcher would be showing mostly the same items, I had the assumption we may not need to load this information. If we do actually have to fetch it, then absolutely I think a skeleton loader would be great for this in the case it takes some time.

Also as we talk about open/closed states for the context switcher there is no visual indication of that. Should the arrow down be replaced with arrow up when it is open?

Apologies, the design for the open state in the Path file was not correct. The chevron-down is indeed replaced with chevron-up. I've updated this

@ohoral one thing to point out as well is we do plan to display the context switcher in a flyout menu for the collapsed state of the sidebar. I'm currently working through designs for that and will share once complete.

thanks for clarifications @nickbrandt - all clear

we do plan to display the context switcher in a flyout menu for the collapsed state of the sidebar. I'm currently working through designs for that and will share once complete.

that's unexpected. The design will help here

@ohoral from the prototype if you are in the Orange project (overview page), you can collapse the sidebar and see what I'm talking about. Not everything is built out and it's still a work in progress, but something like the experience of what happens there when you click on the project avatar.

Looks great @nickbrandt, thanks for sharing

/cc @leipert as we talked about this today

updated 1 design

mentioned in issue #382325 (closed)

removed 2 designs

assigned to @nickbrandt

added 3 designs

mentioned in epic &9044

added workflowdesign label and removed workflowready for design label

marked this issue as related to #330982 (closed)

mentioned in issue #330982 (closed)

marked this issue as blocked by #385095 (closed)

updated 3 designs

mentioned in issue gitlab-org/manage/foundations/team-tasks#188

mentioned in issue gitlab-org/manage/foundations/team-tasks#198

updated 3 designs

updated 1 design

changed the description

changed the description

added 2 designs

updated 3 designs

changed the description

@cdybenko @samdbeckham I believe this issue is ready for the engineering team to review and provide a weight on. Similar to other issues, I feel this one may need broken down (ex: Searching in context switcher), but wanted to get engineering perspective prior to doing so. Let me know if there are any thoughts/questions! Moving to workflowplanning breakdown

@markrian can you work with @thutterer to weight and refine this one please

@nickbrandt @samdbeckham Thanks for the detailed implementation plan!

Utilize the current Frequent Projects/Groups that we store today for users

This is awesome as it means we can avoid any bigger backend changes for the MVC.

When searching within the context switcher...

I think it should be possible that we just use the existing API endpoints for searching projects and groups, sending one query for each. If that holds true, then this whole MVC wouldn't need any backend changes... if I'm not missing something

I'd leave it up to @markrian to weight the frontend efforts, but I'd suggest we split this in at least two parts, one handling search, one handling the "frequent X from local storage", and maybe a third to get the styling and collapse behavior exactly right.

@markrian WDYT?

I think it should be possible that we just use the existing API endpoints for searching projects and groups

For some reason it didn't occur to me we could just reuse these existing endpoints Thanks for pointing this out, @thutterer! I think this is the right approach, at least for an initial iteration. I think we will want to switch to a better API (probably with Global Search's assistance?) eventually, as these endpoints return results that are not sorted well:

Projects	Groups

collapse behavior

@thutterer As I understand it, collapse will be addressed in [MVC] - Collapsed state for navigation redesign (#378544 - closed) and Tailor the navigation for a mobile breakpoint (#385471 - closed), so I don't think that needs to be handled here.

Limit the amount of matches for Projects and Groups to each be 20 (same as today in Main Menu)

@nickbrandt How should scrolling be handled, here? Is the groups section pushed offscreen if there are lots of projects, or should projects and groups take up equal width in the viewport and have internal scrollbars? (I suspect the answer will be different on small devices, although that's something we'll tackle in Tailor the navigation for a mobile breakpoint (#385471 - closed).)

A similar question applies for frequent projects/groups, although it matters less there since you've limited those to 5 and 3 respectively.

I'd suggest we split this in at least two parts

Overall, I think this issue will amount to a weight of 3. It's not complex, though there's a fair amount to do. It will probably best be implemented in two (or more) MRs along the lines @thutterer already suggested, but I don't think this issue needs to be broken down further. (cc @cdybenko)

I think we will want to switch to a better API (probably with Global Search's assistance?) eventually, as these endpoints return results that are not sorted well

@markrian this has been something that multiple teams have struggled with (including Global Search), and we implemented a change awhile back that made this significantly better (!64342 (merged)). I brought this up to the Organizations group recently, as they also struggled with this in some of their dropdowns, and it seemed like a relatively easy fix. Same is possible for Groups (#332889 (closed)). Maybe this won't work for our instance, but thought I'd at least point you to it!

How should scrolling be handled, here? Is the groups section pushed offscreen if there are lots of projects, or should projects and groups take up equal width in the viewport and have internal scrollbars?

Sorry this wasn't explicit in the details in the description. The idea here is we would not limit the height of these areas (requiring scrollable sections), but instead just offer the ability to collapse sections (say for the case you only care about group results).

A similar question applies for frequent projects/groups, although it matters less there since you've limited those to 5 and 3 respectively.

Exactly, we are not worried about the height of these since we will already be capping them at low numbers.

---

Let me know if that all makes sense or if you have additional questions!

we implemented a change awhile back that made this significantly better (!64342 (merged)

Ah, great! I wasn't aware of that, though there's a slight problem for projects. It is limited to projects that the current user is a member of. It means that if you're not a member of a project (e.g., it's some open source project you want to find), it won't show up. Is that acceptable behaviour? I'm not sure it would be

The idea here is we would not limit the height of these areas (requiring scrollable sections), but instead just offer the ability to collapse sections (say for the case you only care about group results).

That's fine, but I just want to clarify: most searches (unless we use similarity ordering, which restricts the results to the projects you're a member of) will result in more than 20 results, meaning most of the time you won't even be able to see the group results without scrolling down or collapsing the project results. Is that intended?

It means that if you're not a member of a project (e.g., it's some open source project you want to find), it won't show up. Is that acceptable behaviour?

@markrian I was under the impression that this search was already limited to projects you were a member of. For instance, if I look at https://gitlab.com/explore/projects/starred and type most of those into the search today (that I'm not a member of), I get no results. However, for some reason I am seeing Inkscape Is this search currently not supposed to be limited to "Your" projects/groups? If so, how does the functionality work? Because like I mention, I'm not seeing results for a lot of open source projects when I search for them.

The answer to this would impact what I would say we do for your second question. My initial expectation was we were leveraging the current functionality, which I thought limited search results to "Your" projects/groups. If that indeed is the case and we go with that for this initial MVC, we could probably update the placeholder text for our context switcher search to be more clear, something like "Search your projects & groups".

current design

@markrian just wanted to follow up on our discussion here to see what your thoughts are. My knowledge is fairly limited on the logic behind these lists today.

@nickbrandt Sorry for the delay, I've been trying to dig my way out of my To-Do pile

I was under the impression that this search was already limited to projects you were a member of

You're right! I wasn't aware of this. Looking more closely at it, the current project search explicitly limits to those you're a member of (directly or indirectly), if you're logged in.

That's funny, because I don't see how to access that search if you're not logged in:

So unless there's some other way of accessing that search when not logged in, I think that means we only ever display projects and groups you're a member of.

However, for some reason I am seeing Inkscape

Hah, me too It looks like we see that project because it's under the gitlab-org/security-products/tests group, and so we've inherited membership from gitlab-org (I think).

for this initial MVC, we could probably update the placeholder text for our context switcher search to be more clear, something like "Search your projects & groups"

That might be best, but my discovery above does raise the question of what to do for anonymous users. Perhaps to keep things simple for now, we just keep it as Search for projects and groups?

That's funny, because I don't see how to access that search if you're not logged in

Yea, I don't believe it's something offered for anonymous users, similar to how we don't provide a list of Frequent groups/projects. I expect we will continue with how this is handled for the navigation redesign.

It looks like we see that project because it's under the gitlab-org/security-products/tests group, and so we've inherited membership from gitlab-org

Oh, you're right! It's not the main Inkscape project that is showing, it's the one within the GitLab.org group

That might be best, but my discovery above does raise the question of what to do for anonymous users. Perhaps to keep things simple for now, we just keep it as Search for projects and groups?

Like I said above, I think we will probably maintain how we are doing this for anonymous users today (not having Frequent projects/groups as well as searching through this method). The design for anonymous users hasn't been prioritized yet (#389603 (closed)), as it won't be in the Beta (as this will be tied to a user setting, thus requiring you to be signed in to see the redesign). That said, things have come up where it is helpful for us to have an idea of how we will handle it for logged out users, this being one. We've done some exploration into the Logged Out state, and my initial thought is we won't have the context switcher for these users. Instead, I could see context being in more of a read-only state, like in this design. To search for groups and projects, Global Search would be the primary method for these users. These details all need fleshed out, but that's the direction I see this going.

Based off of this, I do think it would probably be best to update the placeholder copy for this search field to be more clear to users that it is only for searching your projects/groups. I'll update the design of this issue to reflect that.

Let me know if you have any additional thoughts/questions. @aregnery tagging you in this too for visibility and in case you have any other feedback related to this.

added workflowplanning breakdown label and removed workflowdesign label

started a discussion on Context_Switcher_-Searching__No_Matches.png

started a discussion on Context_Switcher_-Open__Empty_Frequent.png

added Technical Writing UI text labels

unassigned @nickbrandt

changed the description

added Next Up label

changed milestone to %Next 1-3 releases

added Navigation redesign label

added 1 deleted label

All SUS-impacting issues need to have a proper severity label set. Please add a severity label, remove the automation:ux-missing-labels label, and then reply to this comment briefly explaining your reasoning for providing this severity.

If you are not the DRI for this area and would like help determining the best severity, please @ the appropriate person for assistance.

added automation:ux-missing-labels label

added severity3 label

removed automation:ux-missing-labels label

set weight to 3

mentioned in issue gitlab-org/manage/foundations/team-tasks#203

started a discussion on Context_Switcher_-_Searching.png

changed milestone to %15.9

added workflowready for development label and removed workflowplanning breakdown label

@samdbeckham @markrian thanks, for weighting this! Since the Context Switcher has its weight, I'm moving it into %15.9 as per the rollout spreadsheet. Please verify if this is ok to be a '3`

It's a "big" 3

Moved forward into %15.10

assigned to @leipert

added groupfoundations label

added devopsmanage label and removed devopscreate label

added devopscreate workflowin dev labels and removed devopsmanage workflowready for development labels

added devopsmanage label and removed devopscreate label

mentioned in issue gitlab-org/manage/foundations/team-tasks#204

mentioned in issue gitlab-org/manage/foundations/team-tasks#214

changed milestone to %15.10

mentioned in issue gitlab-com/Product#5409 (closed)

mentioned in issue gitlab-org/manage/foundations/team-tasks#217

added Deliverable label

Setting health status to on track as the milestone has just begun.

Issue participants are welcome to override this by setting the health status to another value.

changed health status to on track

@samdbeckham I will unassign myself for now, as per our 1:1, in order to focus on Grouping / Static Menus / Settings.

The status quo of the context switcher:

1. It still uses mock-data defined in the Frontend
2. I think it can quite comfortably be changed Frontend and just use the same "frequent item" logic we have currently.

unassigned @leipert

mentioned in issue gitlab-org/manage/foundations/team-tasks#222

added workflowready for development label and removed workflowin dev label

assigned to @pgascouvaillancourt

added workflowin dev label and removed workflowready for development label

mentioned in merge request !113588 (merged)

mentioned in issue gitlab-org/manage/foundations/team-tasks#225

mentioned in merge request !113758 (merged)

changed the description

mentioned in issue gitlab-org/manage/foundations/team-tasks#218

marked the checklist item Utilize the current Frequent Projects/Groups that we store today for users, displayed as options as seen in the design (Projects - max 5, Groups - max 3) as completed

marked the checklist item When there are no Frequent Projects or Groups, include an empty state message (see design) as completed

marked the checklist item Provide a link to "View all projects" and "View all groups" at the end of each "Frequent" listing as completed

marked the checklist item Toggle the menu with animation (see Codepen). as completed

marked the checklist item Toggle the chevron icon based on it's state as completed

mentioned in merge request !114491 (merged)

This issue is scheduled for completion in this milestone but is in an early development stage. Changing health status to 'at risk'.

Issue participants are welcome to override this by setting the health status to another value.

changed health status to at risk

mentioned in merge request !114643 (merged)

mentioned in issue #396858 (closed)

mentioned in merge request !114905 (merged)

mentioned in issue gitlab-org/manage/foundations/team-tasks#227

mentioned in merge request !114945 (merged)

changed the description

marked the checklist item When there are no matches for Projects or Groups, include a "No matches" message (see design) !114491 (merged) as completed

marked the checklist item Provide a link to "View all projects" and "View all groups" at the end of the associated result groupings/lists !114491 (merged) as completed

changed the description

added workflowin review label and removed workflowin dev label

mentioned in issue gitlab-org/manage/foundations/team-tasks#231

mentioned in issue gitlab-org/manage/foundations/team-tasks#230

marked the checklist item Update the styling of the context switcher (background and chevron color) !114643 (merged) as completed

marked the checklist item If opening the context switcher menu, focus the search field !114643 (merged) as completed

marked the checklist item Look into truncating titles and subtitles within the frequent items lists. !114945 (merged) as completed

marked the checklist item Allow the Project/Group result sections to be collapsable (for instance, in case a user only cares about Groups) !114945 (merged) as completed

marked the checklist item Include persistent links at the top (Your work, Explore, Admin (if Administrator)) !114945 (merged) as completed

marked the checklist item Styling of context switcher should align to designs below as completed

added workflowverification label and removed workflowin review label

The last 2 MRs have hit Canary where I've verified that everything works as expected. Technically, since we are not targeting self-hosted instances with this, we can consider that this made it in %15.10 so I won't change the milestone here. Let's close this one out.

closed

added workflowcomplete label and removed workflowverification label

@pgascouvaillancourt, the workflow label was automatically updated to workflowcomplete because you closed the issue while in workflowverification.

If this is not the correct label, please update.

To avoid this message, update the workflow label as you close the issue.

mentioned in issue gitlab-org/manage/foundations/team-tasks#232