Merge the block navigation and the document outline in the same popover/panel

[youknowriad]

closes #20719
closes #13587

I find that there's a lot of redunduncy between the document outline panel and block navigation one. I think the minimum we can do here is to unify these two features under the same panel. Also I think the topbar is a bit crowded and less buttons there help a little bit.

This is a very exploratory PR at the moment but I'd love some early feedback. cc @jasmussen @mapk @mtias

[youknowriad]

I was surprised that the "TabPanel" component doesn't include any styling by default. I added basic styling here, I think this is needed regardless of this PR but may require a dev note.

[gziolo]

There is an issue filed: #13587

[youknowriad]

This dropdown won't be used anywhere in Gutenberg. I feel like we can probably safely remove it as I don't think third party developers would need this but since it's part of the public API, I kept it for now.

[jasmussen]

Love this, thanks so so so so much for tackling this.

I will give this a much deeper spin as soon as I can, but judging purely by the screenshot, here are some early vague thoughts to ponder:

• The block navigation is more important than the outline, so its icon should be used, and if we tab this interface it should be the default tab
  -- An additional benefit to using the Block Navigation icon, is that we finally address the "circle / undo / redo / circle" goggle visual that the four buttons made up :)
• Is there a way we can simplify the document outline interface, so that we don't need to tab it? The actual document outline with headings and such seems like it could be integrated into the actual block navigation tree.

I will return with more refined thoughts, but those are early instincts.

[mapk]

Thanks Riad! They both do seem very related.

The actual document outline with headings and such seems like it could be integrated into the actual block navigation tree.

I was thinking the same thing. Here's an idea on bringing them together. It's a first pass and not much to get excited about. But clicking the block would highlight that block in the editor just like the Block Navigation did. I still kept the "Document Outline" title, but just used the Block Navigation icon.

[jasmussen]

I love that, Mark! ƪ(˘⌣˘)┐ ƪ(˘⌣˘)ʃ ┌(˘⌣˘)ʃ

[gziolo]

I like this proposal, it needs to take into account a few more things as it is more complex as it seems at first glance. I'm sharing 3 screenshots to better illustrate them:

When a block with nested blocks is selected:

Block Navigation with a couple of Heading blocks:

Document Outline with the same set of Heading blocks:

[youknowriad]

@mapk Nice proposal, I like it. Maybe we could offer a toggle to switch between the "table of contents" and the block list.

[jasmussen]

Maybe we could offer a toggle to switch between the "table of contents" and the block list.

Is there any reason they cannot be merged?

[youknowriad]

@jasmussen my thinking is that people want to see only the headings (table of contents) of their post without necessarily having to scroll the dozens of paragraph blocks between each heading?

[jasmussen]

my thinking is that people want to see only the headings (table of contents) of their post without necessarily having to scroll the dozens of paragraph blocks between each heading?

That's a fair point. In that case, we'll want to make sure the navigation tab is the default one, as it's the most important.

[mapk]

I wanted to address some of the details pointed out by @gziolo and see if a merged version of these can still work when more complexity is involved.

While I do believe it gets a bit more complex, I think it still works.

---

my thinking is that people want to see only the headings (table of contents) of their post without necessarily having to scroll the dozens of paragraph blocks between each heading?

One solution could be to introduce a toggle to turn off the detail view?

@jasmussen @youknowriad any thoughts? Are you still in favor of keeping them separate tabs?

[jasmussen]

I think that's a clever solution, Mark. Instead of having two interfaces that look virtually identical, with tabs, confusing users which is which, this merging of the two clearly indicates what the difference is.

I'm not totally convinced what the best visual location for that checkbox or switch is — I would defer to good feedback on that, but the primary thing that stands out is that it's on the right there, and usually we have it on the left. But I'm personally flexible on that, just need a sanity check.

[gziolo]

I wanted to address some of the details pointed out by @gziolo and see if a merged version of these can still work when more complexity is involved.

I like it a lot and I would be more than happy to see it implemented this way. I see the vertical line which connects nested blocks which is very important to have a way to distinguish from Heading blocks which can themselves create tree view as well. I think this is the only challenge in this proposal. To make it clear, I'm talking about having H2, H3, H4 at the same nesting level where each of them should have different padding to resemble a table of contents like here:

Unless we ignore it in the detailed view and apply those paddings for heading levels only in the simplified view.

I'm not totally convinced what the best visual location for that checkbox or switch is — I would defer to good feedback on that, but the primary thing that stands out is that it's on the right there, and usually we have it on the left. But I'm personally flexible on that, just need a sanity check.

Yeah, good point. In Block Manager we moved all checkboxes to the left to align with the rest of UI. On the functional side, we should persist the selection of this toggle between page loads.

[youknowriad]

I like the toggle but I'm still uncertain about merging the two panels because of how headings are treated.

In your example, a heading in the columns block is hidden unless you show everything while in reality if you're a user and you want to see a table of contents (headings) of your post, you don't care if these are inside columns or not (these are just "design" elements).

At the same time, in a block hierarchy view, it's important to know that a heading is inside a columns block.

which makes me wonder if the two features are mergeable

[mapk]

I've revised the prototype and worked in the concerns.

I'm talking about having H2, H3, H4 at the same nesting level where each of them should have different padding to resemble a table of contents like here:

I've accounted for this now.

In your example, a heading in the columns block is hidden unless you show everything while in reality if you're a user and you want to see a table of contents (headings) of your post, you don't care if these are inside columns or not (these are just "design" elements).

Very true. I missed that on the first go. Here is the updated version showing ALL heading levels.

Play with the prototype.

[jasmussen]

This feels very compelling.

[gziolo]

@mapk - yes, this is great and addresses all my concerns. Let's ship it 🚀

[tomjn]

I can foresee being able to pin this to the left as a sidebar on large screens might be useful

[jwold]

I really like this change. From a design perspective this feels really easy to use. Great work!

[mapk]

@youknowriad would you be up for making these latest changes in the PR?

[youknowriad]

Yes, I have this on my mind. Hopefully, next week I'll get back to it.

[diggeddy]

With the new Group Block and other 3rd party section blocks it would be a benefit to have a custom block label within the blocks advanced setting that is displayed in the Block Navigation. This would allow 'groups' to be more easily identified especially when viewing the root level of the navigator.

[youknowriad]

@jasmussen Do you have the desired icon at hand?

[jasmussen]

No, and I don't personally think it's necessarily a blocker to have it at hand. So long as we are ready and willing to update the icon when it lands. Which of course we are! Just wanted to explicitly acknowledge the feedback.

[youknowriad]

I think this PR is ready merge soonish.

I'll need this merged to use the TabPanel styles in a follow-up PR.

[mcsf]

For now I'm not super excited about the change, but it's more of a personal impression that Navigation and Content are sufficiently different to keep them separate. This isn't informed criticism, and I don't feel strongly about it. :)

However, this change does highlight something that has been an issue in Navigation for a while: that it can become awkward when Navigation becomes rooted in a nesting block (Columns, Cover, etc.) while Content remains global in scope.

[jasmussen]

I'm a fan of this PR. I think that the two are related enough that they deserve to belong together. Although Miguel has a point with the changing scope of the navigation, that feels like an issue even today before merge, and something that can be solved separately either through never limiting scope, or through finding a way to show an indicator to go "back" to the full scope right in that menu.

Icon wise, we should watch closely the conversation on #20719, and follow up depending on how that ends.

Until we find an agreement on the icon there, though, we should go with this icon:

I would throw my thumbs up to this as a good first step to try in the plugin — if you change to that icon first :)

[mcsf]

that feels like an issue even today before merge, and something that can be solved separately

Definitely! It's bugged me for a while; it just becomes a bit more awkward now. :)

Please keep the ball moving and see what feels best, though.

[mapk]

Here's my current experience.

Seems I'm missing the Document Outline from the Content tab. Is that correct?

[jasmussen]

Seems I'm missing the Document Outline from the Content tab. Is that correct

Do you have more than one heading in the body of the text? It will only show up if you have headings, I made this mistake myself a couple of times.

[paaljoachim]

Any thoughts on testing out a version of @mapk Mark's prototype here?
#14956 (comment)

As it would be nice to have some movement here..:)

[SchneiderSam]

I like it very much. This is related: https://wptavern.com/block-navigation-plugin-provides-missing-context-based-outline-for-the-wordpress-editor

[jasmussen]

CC: @jameskoster

[jameskoster]

I was originally unsure of this idea, but when I tried to come up with a more appropriate place for the word count / document outline I could not, without redesigning the entire Top Bar 😭

This change might align nicely with the block navigation adjustments I shared in #27395

[diggeddy]

Heading and Paragraph count only considers core Text and Heading blocks in the current document outline.
HTML text elements added in a HTML block or 3rd party blocks that add there own Text/Typography blocks are not counted.
How are they being counted and can elements outside of core blocks be considered?

[dynamic-david]

Regarding what @diggeddy said about third party blocks that are h1, h2, etc headers under their hoods are not included in the document outline, I was wondering would it be possible to include them based on the usual html tags for headers eg h2 rather than what I suspect is being currently used eg wp:heading comment.

That would then include those headers both in the counts for headers and in the document outline section as well.

I have also noticed that the paragraph count does not include third party blocks that are paragraphs under their hood. I have noticed at least one third party block that is defined as a "headline" (third party term) that can be specified as a heading (h1, h2, etc) or as a paragraph in that instance.

The counts would need to increment based on the underlying type (h1, h2, etc or paragraph).

[gchtr]

No idea whether this is the right place to comment, because there are quite a few open issues and pull requests about the document outline, but I’m going to respond to @dynamic-david’s comment here.

I was wondering would it be possible to include them based on the usual html tags for headers eg h2 rather than what I suspect is being currently used eg wp:heading comment.

Currently, it’s only a check for core/heading blocks:

gutenberg/packages/editor/src/components/document-outline/check.js

Line 14 in 004a32e

( block ) => block.name === 'core/heading'

I’m not sure if using the actual HTML tags would work. There can be headings that are only used for the UI, but no in the post content itself. Here’s an example for a location post type where I can save data about a location:

The block editor has two blocks areas. One for post data saved in meta or a block attributes and one for typical post content, where you can add your own blocks which will be used for the frontend content of a location:

The headings in Location Post Content would have to be counted, but not the ones for the Location Post, which are only used in the UI.

I would like it very much if there could be a way for heading blocks to tell the block editor that they should be considered in the document outline, possibly through a value that can be passed in the block registration.

[ZebulanStanphill]

@gchtr

I would like it very much if there could be a way for heading blocks to tell the block editor that they should be considered in the document outline, possibly through a value that can be passed in the block registration.

There's been some discussion about this in #22874.