Nav Unification - Main Issue

[obenland]

Note: this Issue has been updated by @getdave to be focused on the work required to implement the final version of the nav unification project.

This Issue is organised into Issues for two phases of work:

1. The Final version
2. The Prototype (complete - archived).

With the completion of the prototype (see pbAPfg-VL-p2) phase only #1 is relevant. This is further broken down into the key sections that will need to be completed in order for the project to be put into Production.

Version 1 Tasks/Issues

The following sections represent the work that is necessary to be completed in order to launch the final version of the unified navigation. This is based on the sections identified by @Automattic/ajax as posted in pbAPfg-VL-p2. The aim is to provide an "at a glance" overview of where we are with the project at any given time.

As new issues are discovered please add them here and also check them off when complete.

🖼 Design

For v1 the visual appearance will be guided by "Nav Unification Project Design i2" - We aim to implement the "Nav Unification Project Design i2" which closely resembles core wp-admin. Future design explorations will be addressed in a v2 and/or will likely involve a core-first approach.

🙋🏽‍♂️ User Experience Issues

This section is for UX Issues which don't fit nicely into any other section.

• Implement conditionals for static fallback nav data.
• Determine best UX route for managing menu section open/closed state
• Allow sidebar to be scrolled (while maintaining flyout menus)
• Transition from the site-switcher back to the menu animation
• (Re)position flyout menus based on available screen space
• Fix menu-item active state
• Refine positioning of sidebar items so that they are 1:1 between calypso:wp-admin
• Nav Unification: Check domain notices
• Collapse Sidebar, like wp-admin does
• Collapse Sidebar, keep the same state across wp-admin / calypso
• Clicking on sections causes UI to "jump" and triggers other sections to close.
• Feedback: Allow Calypso to change menu icon color
• Texturize menu titles before sending them through the API
• Method to opt out of Calypso links.

🚀 Jetpack

All tasks relating to Jetpack green branded version of Calypso - https://cloud.jetpack.com/. Note that @davemart-in agreed extensive work on this should not form part of our version 1 launch.

• Test that we have not visually broken "green Calypso".

🤖 🕵🏼‍♂️ Quality Assurance and Automated Testing Issues

Only for issues relating to ensuring ease of maintenance and error handling/reporting.

• Add high-level e2e tests to validate expected Navigation behaviour across Calypso and WPAdmin.
• Fix admin-menu so that data layer only accepts numeric values for siteID
• Handle admin-menu request errors via action dispatch in data layer .
• Add full unit test coverage for data-layer and state.
• Add component integration tests for Nav Unification components.
• Visual Regression Testing? Efforts in core Inital setup of visual regression tests. WordPress/wordpress-develop#209. See also p1604327788116600-slack-e2e-testing-discuss and Remove visdiffs from test specs wp-e2e-tests#1425.

🏎 Performance

This section is for Issues relating directly to work to improve the performance of the navigation on both the front and backend.

• Clicking on sections causes UI to "jump" and triggers other sections to close.
• Add REST API endpoint caching.

🎓 WP on Atomic

This section is for Issues relating directly to work on making the navigation work on WoA.

• Move REST API code to Jetpack repo.

📚 Reader integration

This section is for Issues relating directly to work on the navigation shown in the Reader section.

• Improve Reader sidebar markup

👩🏽‍💼 Me integration

This section is for Issues relating directly to work on the navigation shown in the Me section.

🎨 Color Scheme Issues

This section is for Issues relating directly to work on Color schemes. For the approved direction please see #45675 (comment).

• Make new colors available to customers ahead of nav unification launch
• Determine best way to match calypso scheme and wp-admin scheme colors
• add Classic Dark color scheme (default ready); prepare Classic Blue for default theme change
• Port over WP Admin color schemes as new options in Calypso /me section.
  • Ectoplasm - Add ectoplasm color scheme (Method A) #47122
  • Sunrise - Add sunrise color scheme #47171
  • Ocean
    • Rename the Ocean color scheme to Aquatic; update user preferences accordingly
      • Phase 1 Color Schemes: Add Aquatic and hide Ocean #47273
      • Phase 2 D52536-code
      • Phase 3 Add color scheme ocean #47333
  • Midnight - Update Calypso Midnight to match WP-Admin
  • Coffee - Add coffee color scheme from wp-admin #47173
  • Blue - Add blue color scheme from wp-admin #47204
    • Submenu highlight doesn't match; wp-admin only changes text to be brighter, calypso changes background
  • Modern - Add modern color scheme from wp-admin #47208
  • Light - Add light color scheme from wp-admin #47209
  • Default - Not porting. Reference
  • Helper Issues
    • Selected submenu color is chosen by variable Nav-unification: Selected submenu color is chosen by variable #47291
    • Submenu colors are controlled by variable Nav-unification: Submenu colors are controlled by variable #47249
    • Flyout indicator arrow uses submenu background color Nav Unification: Flyout indicator arrow uses submenu background color #47250
    • consolidate color-sidebar-menu-hover and -text variable Nav unification: consolidate color-sidebar-menu-hover and -text variable #47294
    • consolidate color-sidebar-menu-hover-heading-background with non-"heading" version Nav unification: consolidate color-sidebar-menu-hover-heading-background with non-"heading" version #47300
  • Bugs
    • Ported wp-admin schemes issues on site selector badges Nav-Unification: Ported wp-admin schemes issues on site selector badges #47295
    • Nav Unification: Site Switcher Loading Indicators are incorrect color Nav Unification: Site Switcher Loading Indicators are incorrect color #47303
• Hide option to select Admin Color Scheme in profile.php.
  • Waiting on a way to control features inside Atomic sites.
• Add note to WPAdmin profile.php page that points folks to the (new) respective setting in Calypso.
  • Waiting on a way to control features inside Atomic sites.
• Make Color Schemes apply account wide (not site-specific) across WPAdmin and Calypso (remove setting and have WPAdmin inherit from Calypso setting).
• update Calypso color schemes for nav-unification
• Add the necessary wp-admin styles to support all color schemes available in Calypso.
  • Classic Bright
  • Classic Dark
  • Classic Blue
  • Nightfall
  • Sakura
  • Aquatic (i.e. former Calypso Ocean)
  • Sunset
  • Powder Snow
  • Contrast
• Ensure new color schemes apply to Gutenberg

🚦Release Process

• Research internal testing mechanism for within A8c. How will this work without having ?flag=?
• How to sync with Jetpack release process? What's the plan?
• A / B testing - light touch research and confirmation as to whether possible. Can we A/B test nudges only?
• Research incremental rollout mechanic and outline options.
• We’ll also show a modal to customers the first time they log in to help orient them to the change.
• Decision on incremental rollout target user groups.
• Cleanup code after feature is fully released to 100% of users

Documentation

• Write Fieldguide entry on the Unified Navigation.

---

---

---

Version 2 Issues

Following launch of an v1 of this project the following items are known to be issues that will need to be addressed as part of a v2:

• Notices and Nudges - these don't work on WPAdmin.

---

---

---

🗝️ (Old) Prototype Completed Issues

These items were completed during the Prototype phase of work.

• Create data layer integration for /admin-menu endpoint

• Create Redux state tree for admin menu

• Update admin-menu reducer to be keyed by siteID

• Create selectors to retrieve admin-menu data from state

• Decide on sidebar menu fallback experience and implement

• Render my-sites sidebar from data off the /admin-menu endpoint

• Persist menu state to browser storage to ensure quicker render of menu.

• Nav Unification - create visual "loading" state for the menu.

• Reuse existing Nav components where possible ensuring standards compliant markup.

• Refactor Unified Nav to expect API to return data as array

• Fix HTML entities shown in menu items.

• Calypso: Clicking Nav items doesn’t correctly navigate to route. Nav Unification: Improve 'selected' detection #45973

• Calypso: Top level menu items don’t link they only “unfold” the sub menus. Make top level menus redirect to their first children instead of just toggling the dropdown #45963

• API: Testimonials menu item missing from API response - D50275-code

• wp-admin: Include stats “graph” image in stats menu item - D50280-code

• wp-admin: Currently selected site icon - use correct SVGs (p1601306196200900-slack-CJS75TX3R) Show proper icon in current Site #45965

• wp-admin: Flag persistence missing - D50310-code

• Nav Unification: Left Nav submenu hover / active

• Fix layout "jumps" in sidebar as new items load.

• Update Ad Control to AdControl in static admin menu data.

• Multiple admin menu items in "selected" state.

[getdave]

I've updated the Issue with a list of sub tasks as I see them. Please feel free to amend.

[getdave]

@Automattic/ajax Please note that as of this merge ebde236, we are now persisting adminMenu state to IndexDB. Therefore any changes to the shape of the data coming back from the REST API endpoint needs to be updated in the corresponding schema.js file.

I'd recommend a quick read up on this documentation to ensure you're up to speed.

I added r214400-wpcom to WPCom API which adds comments which attempts to make devs aware of this when changing the API endpoint.

[getdave]

I've updated the description of this Issue to catalogue the required work remaining to be able to launch the nav unification feature across WordPress.com.

[getdave]

@Automattic/ajax FYI I added a Version 2 Issues section to this Issue to track any items that have been removed from v1 on the grounds of scope. Please move items there as required.

[frontdevde]

FYI added the following decision (see #45675 (comment)) to the issue to make sure we're all on the same page:

🖼 Design

For v1 the visual appearance will be guided by "Nav Unification Project Design i2" - We aim to implement the "Nav Unification Project Design i2" which closely resembles core wp-admin. Future design explorations will be addressed in a v2 and/or will likely involve a core-first approach.

[obenland]

Let's consider this finished.