FSE: Add transform + upgrade nudge from A8c Nav Block to Core Nav Block

[getdave]

Gutenberg now has a native Nav Block core/navigation. As a result we can start to deprecate the a8c/navigation-menu block from FSE.

To do this we are going to add a transform to the a8c block and then prompt the user to run the upgrade manually.

For more see paYJgx-lF-p2

Screenshots

Testing instructions

It is...complicated.

• Follow paAmJe-Nv-p2 and have the sync from FSE to Dotcom up and running.
• From Calypso root run npx lerna run dev --scope='@automattic/full-site-editing' --stream to watch and build FSE files.
• On Dotcom, active Alves FSE Theme.
• Add a new Page.
• Edit the Header template part.
• See the a8c nav Block upgrade nudge.
• Click the update button.
• See the block transformed to the core/navigation Block.

[matticbot]

Test live: https://calypso.live/?branch=add/fse-nav-block-upgrade-nudge

[matticbot]

This PR does not affect the size of JS and CSS bundles shipped to the user's browser.

Generated by performance advisor bot at iscalypsofastyet.com.

[getdave]

@shaunandrews Heads up that I'd appreciate a review on this just as soon as I have a working implementation. It could be tricky to test so it might need to be screenshot based unless you have a working FSE sync setup (see paAmJe-Nv-p2).

[getdave]

Feature Mapping

Font Size

• Attribute: fontSize
• Maps to: [nothing]

There is no equivalent on the new block.

Text Align

• Attribute: textAlign
• Maps to: itemsJusitifcation

This feels like the closest match.

Align

• Attribute: align
• Maps to: align

Alignment should map 1:1 with the setting on the new Block.

The only oddity is that the old Block supports alignLeft and alignRight and the new one doesn't. Raises the question of whether it should.

Text Color

• Attribute: textColor
• Maps to: ?

We don't support text colour which is a problem...

Background Color

• Attribute: backgroundColor
• Maps to: ?

We don't support background colour. We can however, wrap the Block in a Group block and apply the setting there. Might be a little odd though? We'd also have to account for mirroring the alignment settings on the Group Block (as happens when you "Group" using the toolbar).

Text Color

• Attribute: textColor
• Maps to: ?

We don't support text colour which is a problem.

[obenland]

Let's make sure all attributes are mapped correctly, too, including block alignment please

[getdave]

Let's make sure all attributes are mapped correctly, too, including block alignment please

Agreed. That's what I was meaning by the features really. See above.

[WunderBart]

It would be good to extract the notice to a separate component / PR. It already gets duplicated here.

[getdave]

Agreed. If this is something that can be shared across FSE then that's a good idea. I'd be inclined to ship "as is" and then unify in a separate PR.

[shaunandrews]

It could be tricky to test so it might need to be screenshot based

Any chance you (or someone) can add screenshots?

[getdave]

It could be tricky to test so it might need to be screenshot based

Any chance you (or someone) can add screenshots?

Yes apologies.

Here's one show the flow as it stands. Notice I can dismiss the notice.

Next step will be to automatically add the Nav items.

Here's a still of the upgrade notice:

[shaunandrews]

There's some spacing issues, and overall the message is way too verbose. Lets try something like this:

An improved version of this block is now available.
[Update Block]

I think we should avoid the term "Upgrade" as it could have confusing implications related to upgrading a paid plan. I'd love to know what @obi2020 thinks here, as well.

[obi2020]

Big +1 for using update here @shaunandrews I also agree that there are more words than necessary - for what's currently being said. It would be worth using the space if you gave some concrete info on what's improved about the block. Sometimes people avoid upgrading things because "if it ain't broke..."

If there's something concrete like "This version will stop working..." or "Upgrading will add [this functionality / performance improvement]"

Are there any repercussions if they don't upgrade?

[shaunandrews]

Are there any repercussions if they don't upgrade?

Great question. I'd assume we'd want to remove the old block, but I'm not sure its realistic. I also don't think we could explain the value in updating to the new block in a few words, which is why I tried to just say "improved block" and hope people click the button.

[getdave]

@shaunandrews @obi2020 Thanks for feedback.

I'd assume we'd want to remove the old block, but I'm not sure its realistic

Correct, we can basically never remove this Block now or at least until Gutenberg Core offers an automated way to migrate between different Blocks. Even then it might not be a good idea.

The current wording for the Notice has something to indicate that the upgrade may not result in a 1:1 experience visually. There's no way for us to guarantee the same results.

Happy to amend it to whatever we feel is best.

[getdave]

🛑 Update - Blocking Issue - cannot accurately map Nav Items between Blocks

This PR is currently blocked and unable to move forward. This is because of the following problem.

Navigation is comprised of a set of navigation items. Upon "upgrade", we should be mapping these 1:1 between the two blocks.

To understand why this isn't possible, we need to understand how the two blocks differ in their approach to determining which Nav Items are included in the Block.

The existing a8c block uses server-side render of the Navigation. It uses wp_nav_menu() to look for a user defined WP Menu and if found renders the nav items from that Menu.

If this isn't found then it falls back to using wp_page_menu() which gets the top-level pages and uses those as nav items.

By contrast, the new Core block creates nav items from top-level Pages retrieved via the REST API. It does not look at WP Menus because there is not a current REST API endpoint for Menus.

Therefore we have a scenario where a user could have created a WP Menu on their site via the Customizer. With the old a8c Block this Menu would be what is rendered as the Nav Items. If that user then upgrades to the new block then they would see (potentially) different Nav Items. This is because the new block doesn't take account of their custom WP Menu but rather just adds all top-level pages. This means the user loses their carefully crafted navigation.

Finally, it's important to note that transforms cannot be async. Therefore even if we have the Menus endpoint we cannot call this during a transform to auto create the nav items in the target block. A potential solution might be to do the transform, insert the block and then use some attribute on the inserted block to auto-create from Menus instead of going to the placeholder state. This requires investigation however.

@apeatling @obenland This issue is currently blocking. I see a few possible options to allow this to move forward:

1. We accept that the Block cannot offer a 1:1 mapping under all scenarios and therefore some users may have to remake their Navigation upon upgrade. This allows us to launch albeit with a compromised solution. We'd need to be extremely proactive in prepping support here.

2. We work to bring the Core REST API team's feature Plugin for an API Menu endpoint onto WPCom as a testing ground. We could then try and see if it's possible to extend the core/navigation Block from Core so that it supports creation from Menus. This is conceptual only as I'm not sure this is actually possible without forking the core/navigation Block (@youknowriad might have some insight here).

3. We wait for the Core REST API team's feature Plugin for an API Menu endpoint to land in WP Core and then update the core/navigation Block to support Menus.

4. We see if there might be an appetite to add an API Menu endpoint to Gutenberg Core and then update the core/navigation Block to support Menus.

If there are other options I'm not aware of then I'd be happy to hear them.

I would say that none of the above are simple and its likely this runs past the end of our Iteration.

As things stand, I would greatly value a discussion of options and direction on next steps. Many thanks.

UPDATE

Note as of this comment, the Block is now also able to parse and use WP Menu items as well so the issue above may no longer be a problem.

[getdave]

An update. Having discussed with @marekhrabe we've looked at our options.

We've come up with trying another route which is to pase a inlined JSON object alongside the server side rendered Nav Menu response. We can then parse the JSON out of the DOM generated by the SSR and use that to create the Nav items during the transform.

Working up a POC now...

Done. POC in place.

[getdave]

@shaunandrews @obi2020 I've updated the visual spacing and text. Also made some tweaks as I felt necessary

[shaunandrews]

The visuals look better. I'll repeat what I said previously about the use of the word "Upgrade":

I think we should avoid the term "Upgrade" as it could have confusing implications related to upgrading a paid plan.

I still think the message is too long, and can be summed up in a single sentence:

An improved version of this block is now available.
[Update]

[getdave]

@shaunandrews Sorry just after I did that screenshot @marekhrabe reminded me about Update vs Upgrade. That's been amended now 👍

[obenland]

I didn't follow your testing instructions and instead monkey-patched FSE to be loaded on my local install. When trying to update the block threw:

Probably not too important to investigate at this point, but I thought I'd bring it up in case it happened before.

[apeatling]

Is not being able to map text/background color and font size settings on the a8c block to the core block a blocker for launching this upgrade flow?

@obenland curious why you believe this one isn't a blocker?

[obenland]

The Core block doesn't offer background or fonts size customization so I'm not sure how we'd keep that the same without adding that support. Font color I'd expect to be mappable?

[getdave]

I didn't follow your testing instructions and instead monkey-patched FSE to be loaded on my local install. When trying to update the block threw:

Good spot @obenland. I tested on my Dotorg install and turns out I was missing two guard clauses. Now we guard against empty JSON response in markup and also always ensuring we return some data even if there are no menu locations. All fixed.

[Copons]

I'm not familiar with the block upgrade flow, but I wonder if, to work around the missing background color, we could wrap the Nav block with a Group block with the background color attribute.

Though, we'd still be missing the text color, which might prove problematic if the user, for example, "inverted" the Nav colors.

E.g.
the theme text color is black, and the user sets the Nav as a black background with white text.
A "Group with black background" solution wouldn't solve the fact that the Nav would inherit the black theme text color (unless the theme defines a different default color for blocks wrapped by custom background (Varia themes should do this, but I haven't tried).

[getdave]

I've tracked down that the many of the styles on the a8c Nav Block are being applied via the Theme styles (eg: /wp-content/themes/maywood/style.css). Therefore @allancole @iamtakashi we need to update the Theme styles to improve the consistency between the rendering of the two Blocks on a per theme basis.

However, as @apeatling, @obenland and @Copons have mentioned, due to the lack of ability to alter the text color on the Core Nav Block we cannot guarantee a smooth transition between the two Blocks (even if we go for the "wrap with Group block" approach).

Update: this was wrong. The Core Nav Block now has text color support. So we just need to see if the Group Block route works for us.

Therefore, I feel we need direction from @apeatling on whether we:

1. Work to upgrade Core Nav with text colour and font size abilities and then continue in this PR once that is available.
2. Launch anyway and accept that some users may experience a change when upgrading if they have adjusted text or background colours or font size.

See also @Copons 's point about usage in current Themes:

On the other hand, imho the actual blockers here are the style attributes, specifically b palette and font sizes. All FSE-ready themes rely on them to somehow achieve visual parity (never perfect anyway) with the theme demo site (which has been our target).

Lastly, bear in mind we still need to add support for nested levels of Nav items during the transform so this isn't ready to go yet anyway.

[getdave]

@Copons Sorry to delay response to your thoughtful comment. Please allow me to address:

I think this is less of a blocker and more of a minor issue! 🙂

I think @apeatling confirmed that the inability to transform Navs created from WP Menus would be considered a Blocker. However as you indicate it is extremely unlikely this will ever have occurred (not your fault but I wish I'd had this insight earlier).

The work to solve this has been completed now anyway so it doesn't matter. Moreover, it was partly necessary to allow us to achieve the "auto create" functionality and bypass the placeholder state on the Core Nav so it wasn't all wasted time.

Updating a deprecated block is undoable.

This is a good point. Indeed I've been using this mechanic for testing. However it doesn't set a good precedent if you upgrade on a prompt given by us only to find a completely substandard experience. As a user once I've been "bitten" by such an experience am I ever likely to update any of the other blocks? Probably not. Therefore I think it's worth getting this right.

imho we can live without them, and map them [alignLeft / alignRight] to itemsJusitifcation (unless already mapped from textAlign).

I think the only way we can know for sure is to test against usage in Themes.

On the other hand, imho the actual blockers here are the style attributes, specifically color palette and font sizes. All FSE-ready themes rely on them to somehow achieve visual parity (never perfect anyway) with the theme demo site (which has been our target).

Agreed. This will be important for @apeatling and @obenland to know.

[getdave]

Update

We're going to put this on hold whilst @apeatling considers next steps and whether we can enhance Core to gain feature parity with the a8c Nav Block.

[apeatling]

Next steps after discussing with the team:

1. Support background color on the navigation block because many of our users are using this based on going through sites.
2. Open a conversation about supporting font sizes, this is used far less but is supported in our existing block.
3. Once background color support is merged, we can merge the upgrade flow. 👍

Relevant: WordPress/gutenberg#19108

[davipontesblog]

I am closing this in favor of the current efforts with core FSE.

[obenland]

@getdave This still has merit, right? We still want to deprecate the custom navigation block?

[davipontesblog]

@obenland feel free to reopen as needed! This was closed as part of bug triaging we are doing.

[noahtallen]

We still want to deprecate the custom navigation block

I think so. I think we'll need to do quite a few things to facilitate the transition to the core site editor from dotcom FSE, so it could be worth waiting until then to do all the work