Nav Unification - add scaffolding for admin menu experience from static data

[getdave]

The aim of this PR is to ensure that users always see a menu appear immediately in the sidebar without any noticeable delay. To do this, if the menu state is not populated we render a basic menu from a static JSON snapshot. Once the REST API request returns we then hydrate the state and update the UI to use the dynamic data.

This is very much an edge case experience, as once the endpoint data is cached in browser storage users will rarely see the fallback experience. Nonetheless this is an important safe guard to ensure a user never receives an empty menu.

Changes proposed in this Pull Request

• Update getAdminMenu selector useSiteMenuItems hook to return static data from JSON in the event the getAdminMenu() selector returns a falsey value due to the state is not yet beingpopulated with menu data from the REST API.
• Add static fallback data to represent the structure in the approved spreadsheet with translations.

Testing instructions

• Checkout this PR.
• Open client/state/admin-menu/fallback-data.json and amend the title prop of the first menu item from Feedback to Testing 123 (or similar). Save the file.
• Apply D49005-code
• Apply blog sticker
• Build calypso - yarn && yarn start.
• Visit http://calypso.localhost:3000/?flags=nav-unification.
• You should see a two stage render - initially the Nav will render with the first item as Testing 123 (or whatever you modified it to be in the .json file). Then as the REST API request resolves you should see the Nav update to match the data from the API as generated by D49005-code.
• Also check the static fallback nav confirms to the structure shown in the spreadsheet.

Fixes #45487

Screenshots

Notice how the menu changes from Testing 123 (static fallback data) to Feedback (dynamic data from REST API).

[matticbot]

Test live: https://calypso.live/?branch=add/scaffolding-for-admin-menu-fallback-experience

[matticbot]

Here is how your PR affects size of JS and CSS bundles shipped to the user's browser:

Async-loaded Components (~1522 bytes added 📈 [gzipped])

name                                          parsed_size           gzip_size
async-load-my-sites-sidebar-unified-switcher      +9131 B  (+4.5%)    +1522 B  (+2.8%)

React components that are loaded lazily, when a certain part of UI is displayed for the first time.

Legend

What is parsed and gzip size?

Parsed Size: Uncompressed size of the JS and CSS files. This much code needs to be parsed and stored in memory.
Gzip Size: Compressed size of the JS and CSS files. This much data needs to be downloaded over network.

Generated by performance advisor bot at iscalypsofastyet.com.

[cpapazoglou]

Thanks Dave for working on this! Works great.

The menu links need some auditing though as commented. Also, it seems that this will clash with the loading status? I would prefer to serve fallbackResponse on error of the api which is not transparent now. We could then:
a) on initial load, show loading state and fetch menu
b) save the menu to localStorage (either the real or the fallbackResponse)
c) on subsequent loads, serve the menu from localStorage while waiting for the Api Response to hydrate.

We can surely iterate it though on new PR!

[marekhrabe]

I think I would strongly prefer to never show empty/loading state even in this case:

a) on initial load, show loading state and fetch menu

We know what the menu would roughly look like. I'd rather show 90% of the menu right away and fetch updates from the backend than leave user hanging without the ability to use the main nav.

The current situation in Calypso is very similar - it shows as much menu as is common for different sites and configs and in the background it fetches data to determine if it should display some additional items (like Testimonials when enabled).

b) and c) are awesome additions - let's plan accordingly to include them

[marekhrabe]

Should we have a different fallback for jetpack only connected sites as they will have a smaller set of menus eg import / export are redirecting to wp-admin

I think that would be great. But I'm not opposed to start with the most common denominator which are the basic wp-admin menus and maybe we can branch them later per site type. Possibly also per wp version, per known list of installed plugins…

[getdave]

Ok @cpapazoglou @marekhrabe thanks for your input. Very much appreciated.

I agree with @marekhrabe that we need to show the most simple nav immediately for uncached page loads. This means we render the nav structure from static default data as shown in this PR.

That said, I was also planning on implementing the browser storage approach suggested by @cpapazoglou so I totally agree with that.

Please note that once we implement the withSchemaValidation higher order reducer on the reducer then we will get browser storage of this slice of state for free in IndexDB (as I understand it). That will mean that we will end up with following experience

1. User visits WordPress.com admin area uncached for first time.
2. We immediately show an approximate menu from static data.
3. We make a API request to get the exact nav for the site in question.
4. Once the API returns, assuming we have items, we update the state with the dynamic data from the API.
5. The UI re-renders to reflect the dynamic data from the API.
6. The results of the API request are cached in browser storage.
7. User closes browser and then reopens it on the exact same site on WordPress.com.
8. We grab the cached menu data from browser storage and hydrate the state from that immediately.
9. We grab a fresh copy of the data from the API endpoint and update the cached data.

This way the only time the user ever sees the static data versoin is on an initial uncached request.

Benefits are that user never sees a missing nav. Consider that on slow connections it could take quite a while to retrieve the data from an API endpoint and therefore it's greatly preferable to render something immediately.

I appreciate this may make #45831 obsolete, but I still think it is worth having that UI state available as a fallback....just in case.

[getdave]

Generally the URLs need some auditing. Happy to help if you need!

@cpapazoglou Any help you can provide here would be awesome.

@obenland The strings are now translatable via translate().

[obenland]

I think for this stage of development it's fine to use the full menu as a fallback. Later on we'll have to add a capability check to make sure the various user roles get the right menu items

Outdated - needs new review.

[getdave]

In future I expect that these options will need to be passed into the function as args with defaults specified. This will make the function more testable and avoid building into too many dependencies.

[cpapazoglou]

@getdave Thanks for your great work on this! It looks and works great! I just have an issue that when clicking to a link it reloads the pages instead of loading in place. But let's move forward with this and we can iterate.

[a8ci18n]

This Pull Request is now available for translation here: https://translate.wordpress.com/deliverables/4521234

Thank you @getdave for including a screenshot in the description! This is really helpful for our translators.

[dlind1]

@getdave
Sorry for bringing that up, but I've noticed that the actual menu entry for 'AdControl' doesn't have a space in it and is also not translated (in wordads-userdash), while the placeholder data has 'Ad Control' in it, which our translators are now translating. The effect of this would be that the users who see the fallback data would see something like 'Gestión de anuncios' for Spanish and then 'AdControl' when the actual menu would be loaded.
It's possible to switch to using 'AdControl' in the fallback data and not translate it, in case that it's a product name and it'd appear the same in all the languages. Or translate 'AdControl' both in the placeholder data and the actual menu entry and have some guidelines on how it should be translated so that it'd be consistent across all languages.

[getdave]

@getdave
Sorry for bringing that up, but I've noticed that the actual menu entry for 'AdControl' doesn't have a space in it and is also not translated (in wordads-userdash), while the placeholder data has 'Ad Control' in it, which our translators are now translating. The effect of this would be that the users who see the fallback data would see something like 'Gestión de anuncios' for Spanish and then 'AdControl' when the actual menu would be loaded.
It's possible to switch to using 'AdControl' in the fallback data and not translate it, in case that it's a product name and it'd appear the same in all the languages. Or translate 'AdControl' both in the placeholder data and the actual menu entry and have some guidelines on how it should be translated so that it'd be consistent across all languages.

I discussed this with @dlind1 and we agreed to:

• Match static data to canonical reference (see wordads-userdash/wordads-info.php#39) for the AdControl menu item - change Ad Control to be AdControl within the static data.
• We agreed to retain the existing translate() wrapper around AdControl in the static data even though the canonical version in PHP is not yet translated.

[a8ci18n]

Translation for this Pull Request has now been finished.