Navigation markup – overview issue

[draganescu]

We have a few competing problems around the navigation block’s markup, structure and use cases and it seems that it’s hard to find a good implementation.

Here is a list of the problems in no special order.

1. The navigation block has an improper wrapper element UL and it should be a NAV.
2. Users should be able to add links and nest lists of links as a first class action.
3. We want the block to be a canvas for navigation patterns.
4. We want the evolution of a simple navbar (horizontal or vertical) to a drop down (or fly out) menu to a tabbed navigation with custom content in each tabs to be seamless.
5. We don't want to introduce new terminology such as navigation item, or submenu block, or megamenu, instead relying on the normal immediate terms: link, image, logo, list.

I think all these things together are putting the block in a bad place. Let's try to advance the work by taking some unbinding decisions.

Discussion 1: the block's markup (1, 2)\

The problem with the wrapper element for the navigation block stems from how block html works plus the expectation to be able to insert a link as a top level element. If we default to showing menu items as LI elements then the default wrapper should be an UL, but if this wrapper can contain other blocks we'll end up with invalid markup, for example the wrapping FORM of a search block as a direct child of the UL wrapper element of the navigation block.

To mitigate this a few paths have been proposed so far:

• Drop the UL > LI requirement for navigation. This has the problem that screen readers use list markup to announce the number of links available to navigate, parents and available nested lists. We could mitigate this with roles and aria-labels, but: it's unclear if the block API has enough to allow us to build these correct labels, it's unclear if the screen readers really will work similarly.
• Use only DIVs in the editor and render semantic accessible markup on the front end only. This is possible, at render time we can detect if we have lists of links and render those with list markup. The problem is that we're generally striving to not have different markup between the editor and the front end.
• Use functional individual blocks such as links list, pages list, submenu to allow the navigation block to have a canvas wrapper (like NAV). The problem is that we need to mind the user experience where by crowding the top level available blocks with abstractions the building of a menu will not be intuitive enough, It could be solved by good initial states (e.g. I add a links list and the initial display tells me to add a link). This approach also has the problem that nesting makes movers not work at parent "border".
• Create a passthrough block. This idea is to take the idea above and instead of making visible blocks make invisible blocks that handle wrapping. The user adds a link but the system automagically add it to a links list block that wraps it into the proper list markup.
• Make the navigation block do some work behind the scenes and transform its inner link blocks depending on the situation. The wrapper of the navigation block is a NAV element. the user should be able to add a Link block which would be rendering an A element. This link block allows the user to add a "submenu" from he block toolbar like it does today. That is when we transform the Link into a Links List and move to an UL > LI markup just for that tree. This way the movers work and the markup is the same in the editor and the front end and we use the most accessible and semantic option we have.

Discussion 2: the power of the navigation block (3, 4, 5)

Here is a list of questions that always come up and have not had a clear answer:

• Why do we want to allow certain blocks in the navigation block (spacer, image, site title, social icons etc.)?
• Why is making a navigation pattern inside the navigation block better than just having a block pattern made from these blocks?
• What is the difference between using a navigation block or to build a complex menu (complex meaning a menu that contains more than links) compared to building it with group, columns and a navigation block that only supports nested lists of links?
• What is the problem if initially the navigation block only supports link blocks and nested link blocks? How is that blocking us to develop the block further?
• Is it realistic to assume we'll build megamenus without introducing complexity for simple menus?

That's about it for a summary of the problems that keep the navigation block, well ... blocked.

[draganescu]

Make the navigation block do some work behind the scenes and transform its inner link blocks depending on the situation. The wrapper of the navigation block is a NAV element. the user should be able to add a Link block which would be rendering an A element. This link block allows the user to add a "submenu" from he block toolbar like it does today. That is when we transform the Link into a Links List and move to an UL > LI markup just for that tree. This way the movers work and the markup is the same in the editor and the front end and we use the most accessible and semantic option we have.

I personally quite like this approach.

For the situation where the user will add a few adjacent links we'll end up with a nav and some anchor children, a good pattern for navbars. If the user creates nesting we'll end up with a nav and some ul children plus other elements from the other blocks.

[draganescu]

What is the difference between using a navigation block or to build a complex menu (complex meaning a menu that contains more than links) compared to building it with group, columns and a navigation block that only supports nested lists of links?

Using patterns removes some options such as:

• reusable menus that are ported over when switching themes
• importing from current menus (and syncing)
• menu specific things like the responsive menu variants

[priethor]

Regarding the power of the navigation block, I believe it might be helpful to take a step back and reevaluate what we are trying to achieve with a single block. Do we want a single block to handle all those use cases and the complexity you mentioned above?

What is the difference between using a navigation block or to build a complex menu (complex meaning a menu that contains more than links) compared to building it with group, columns and a navigation block that only supports nested lists of links?

Given that Gutenberg already supports semantic template parts, I think we could try exploring a semantic Navigation template part approach, similar to how Header and Footer work, as groups can be converted into reusable blocks but lack semantic meaning. This would reduce the complexity of the Navigation block to a list of links, and would allow building more complex navigation layouts with a better UX to handle them while keeping them semantically meaningful.

[mtias]

I think there's a few things to clarify because we are going a bit in circles!

• Navigation is one of the most complex and diverse expression of websites. We should always be referring to patterns and design references we want to unlock for users or we risk solving abstract problems with loose resemblance to reality. So let's see a couple examples:

• • Here we are dealing with an overlay and an interesting display of sub-menus, but is otherwise a fairly standard representation. But we also need to see it from an editor interaction point of view since this is an overlay menu (behind a toggle) and the sub-menu has some distinct visual qualities (smaller font size, a large gap on the left).

• • These two menus have a site logo or title in the middle of the menu. It's no longer clear if it should be a single list, two split lists, or no list at all. The one below also has search and social icons laid out in a way that could be debatable whether they are part of the navigation structure or outside of it. How should a user be building this? Is there a single way to accomplish this layout? It'd be easy to offer patterns that look like this and call it done, but from a pattern builder perspective we still need to answer those questions.

• • Here the four corner navigation structure is interesting in that it's restrictive — it doesn't make sense to have more than four items. A list is probably not the best markup to represent this structure. If a theme was building this nav we'd need a mechanism to ensure a user can assign the links / pages they care to the four corners, it would be hard to do automatically on theme switch because we don't know the right content to lay out. How would a theme declare this in a template?

• • As an example of mega menus, here there are many structural units that make sense as list and others that don't. The image, for example, should not be part of a list. The columns that lay out the three broad sections may also not be lists but just columns.

• Gutenberg encourages separating three dimensions for how content is presented: how it's rendered, how it's edited, how it's saved. Block authors need to make nuanced decisions for each dimension. We should save the most ergonomic and clean representation of what a users has created. In the case of navigation, the list markup is a detail of rendering, not of the data structure. The same way a spacer is an indication of intention but should not force us to render a spacer on the front if we can turn it into margins of the sibling elements.

• • We should take the effort of saving the leanest representation and build at render time the extra affordances and semantic markup when it's justified.
• • We generally want to have markup in the editor and the front be the same but this is not a requirement nor a design guideline. There are various reasons why markup would be different in the editor (it needs extra UI, like resizers, etc). The markup on the front has to be the best representation we can muster for visitors.
• • We need functions that can represent the data side of the navigation menu. That was the spirit behind this issue: https://github.com/WordPress/gutenberg/issues/30674. We should be able to identify what items could or should be wrapped in lists at render time.

• We don't want to overtly complicate block APIs because we need to allow our block builders to create simple blocks that could be used in navigation structures, with or without lists. (For example, a WooCommerce Cart widget.)

Do we want a single block to handle all those use cases and the complexity you mentioned above?

I don't think this is the right frame of mind because we are already employing various child blocks. The important part is how users would experience it vs how it works. It's already a bit confusing from a user perspective to see so many options without much context on which one is right to use.

So far I believe from a user perspective we need to make it simple to understand — if a user needs to choose among various navigation types in the inserter, we would have offloaded a design problem onto the user because it's easier for us to reason and develop as separate blocks.

We should embrace the flexibility that we can optimize the three contexts (render, editing, saving) for what we need them to accomplish, and to have flexibility in the future to alter markup decisions, improve accessibility, etc.

[tellthemachines]

In view of this discussion, I've updated #30551 as it seems the best way forward for now.

[gwwar]

If I understand correctly, we're aiming for a solution where:

1. The user experience is simple but still robust enough to create many types of navigation menus. Some of which may not have an obvious structure when looking at the published view.
2. Published menus remain accessible

Did we rule out https://github.com/WordPress/gutenberg/pull/31827 as a possibility? For me, the main question there was if ULs needed to be used for accessible navigation links.

The approach in https://github.com/WordPress/gutenberg/pull/30551 would be my next preference if we don't mind diverging the editor and published view representation, which as noted in this discussion is an ideal but not a hard rule.

[draganescu]

diverging the editor and published view representation

Yes. This whole discussion was started to make sure alternatives to diverging the two representation have been explored as much as possible. I think this is the most important direction that this thread has boosted:

Gutenberg encourages separating three dimensions for how content is presented: how it's rendered, how it's edited, how it's saved. [...] We generally want to have markup in the editor and the front be the same but this is not a requirement nor a design guideline.

In light of the above both #31827 and #30551 should move forward and:

• In the editor, improve the block's wrapping HTML for the outer container and for its children to be valid, but to not require any block API changes - drop the UL > LI requirement, give up on a links list/passtrough/autowrapping block and rely on InnerBlocks to work normally for the navigation link block. Briefly, in the editor we should use generic elements that do not need to belong to a specifc parent element. This is where #31827 is going.
• On the front end, improve the block's rendered HTML for the container and it's children to be semantic and to follow best practices, but to not require any block API changes and solve instead through a block specific implementation. This is where #30551 is.

cc @tellthemachines @ellatrix

The change of the blocks editor markup will affect the navigation editor and it will require great consideration for making the creation and editing accessible without relying on the affordances of the markup.

cc @getdave @talldan

[tellthemachines]

In light of the above both #31827 and #30551 should move forward

I'm confused. These approaches are incompatible, so we can only move one of them forward, not both. The first removes the list markup altogether, while the second removes that markup in the editor and adds it only in the front end. Which is it to be?

[priethor]

Taking into account @mtias' insightful comment above, I believe we should move forward with #30551 and handle the frontend representation on render time, clearly differentiating how the block is rendered, how it's edited, and how it's saved.

As @tellthemachines points out, once we head in this direction we won't need to remove the list markup as in #31827 but generate an appropriate, valid markup depending on the inner blocks added: this could perfectly be a <ul> wrapping links, followed by a <div> wrapping a search block and a spacer, and another <ul> wrapping more links, as discussed in #29036.

[draganescu]

Yes, I missed that #30551 ALSO removes the editor markup :) So in this case #31827 should be closed in favor of #30551 .

[draganescu]

This is a solved overview / discussion so closing.