Show the content of the paragraph and list items in the list view.

[juanfra]

What?

I've recently found myself using the blocks list a lot. I find it super helpful. But I ended up experiencing that it was challenging to identify essential elements like paragraphs and list items for more complex layouts. I started looking around and found some conversations about having custom naming/labeling. That would probably be the ultimate solution for group blocks or other blocks.

For text content-oriented blocks, more precisely the paragraph block and the list items, I feel that the default solution would be using the actual content in the list view. And this PR addresses that change.

Why?

The paragraph and list-item (<li>) blocks will be better represented in the list view. It should enhance its functionality by adding an instant visual representation of the block content.

Testing Instructions

1. Create a post or page.
2. Open the list view.
3. Add a new paragraph or a list and see how the changes in the content are reflected in the list view.

Screenshots or screencast

paragraph-list-item.mov

[apeatling]

cc @andrewserong since you also experimented with this.

[andrewserong]

Thanks for working on this PR @juanfra! This is testing very nicely for me, and follows the same logic as that used by the Heading block. Personally I really like this approach, and for me, it makes the content easier to find within the list view, especially for longer posts.

Code-wise this is looking good to me, I'll just add some other reviewers. It'd be good to confirm with designers and / or folks working in accessibility as to whether or not this is a preferred change, but it has my vote!

[jasmussen]

Thanks for the PR!

I will say that I'm a little reluctant on expanding this beyond the heading block. The list view is meant to be a utilitarian overview of the content, and by showing the content it can potentially get a little noisy. This is not at all a strong opinion, and I can genuinely see the value too, of additional context showing in the list view.

I do think that it would be good to boost the confidence and get a somewhat wider take on this before landing, though. It might seem an inconspicuous change, but it touches a very often used interface.

CC: @WordPress/gutenberg-core

[getdave]

Thank you for working on this. It's a great experiment and one that's it's good to discuss.

My view is that this adds unwanted additional noise to the List View experience. I feel like the motivation behind this work is so that it's easier to identify certain items within the List View. If that's the case then perhaps the ability to add custom labels/names to the items might be preferable as it's more targeted and "opt in" behaviour?

[paaljoachim]

Taking a look.

Before:

After:

Heck yeah!

Going from:

Paragraph
Paragraph
Paragraph

List item
List item
List item

To actually showing the content is very helpful. As it shows the unique content of each block. Making it a much better List view overview of the content on the page/post. Being able to easier select the correct block to which one wants to adjust.

[paaljoachim]

Being able to customize the label is very nice to have for the parent block. Such as a Group and probably other parent blocks as well. Being able to automatically view 5-10 etc Paragraph blocks in List view and right away understand which Paragraph block is which makes List view even more valuable. The same goes for the List block content as well. Needing to customize the label of every Paragraph block by adding some of the content to it is more cumbersome. Having the option to have the content seen in Paragraph/List block and clicking into it to rename the label is also one way to go which would be even more helpful.

This means see the content in the List view label or rename. The choice is up to the user.

[jameskoster]

I suspect this is going to be quite subjective but I like the change. One of the main purposes of list view (imo) is to make selecting blocks easier, and this helps a lot. I no longer have to look back and forth between canvas / panel to know if I'm hovering the right item.

[juanfra]

Thanks for the feedback :)

When I started looking at this, I was exploring ideas to add utility to the list view, which I find super helpful.

My initial thought as a user was that, with how things are right now, I could have quick access to the structure, but for some layouts, it was really difficult to identify the contents. Looking right-left-right-left to identify the correlation between list view and content layout was challenging and I thought we could improve it.

I felt that being able to rename these things would be super helpful, so I started looking for issues related to that and found #33583

Although I see a lot of value in being able to rename things in the list view, I think for some blocks, the naming should automatically adjust to the content. After going through all blocks, I felt these two (paragraph and list item) were good candidates.

As a blogger, or site owner, I wouldn't see myself renaming a paragraph to identify it better. It would be super cool and helpful to have the option, but I feel there's a lot of value in having that coming "for free" initially. I also saw some comments in #33583 that were in line with these changes, so I took the chance to experiment and open a PR.

[ntsekouras]

Thank you for the PR @juanfra! I agree with @jameskoster that this seems quite subjective, so maybe it could be wrapped under a preference? 🤔

Most importantly though how could this scale easily in other blocks and other places, besides the list view, if there is the need in the future. I believe an API like @getdave 's PR could be a more flexible way to scale(besides the value of metadata), and could be augmented probably by some options to do that - show the content.

[paaljoachim]

If it is added to preference do please automatically have it on as preferences for many users can be hard to locate.

[paaljoachim]

Can we try out the approach that @juanfra has created and see how it goes? (As in get final reviews and merge the PR.) @annezazu can perhaps bring it into a FSE call for testing to get feedback on the approach.

[richtabor]

I will say that I'm a little reluctant on expanding this beyond the heading block. The list view is meant to be a utilitarian overview of the content, and by showing the content it can potentially get a little noisy. This is not at all a strong opinion, and I can genuinely see the value too, of additional context showing in the list view.

I agree with this sentiment. Here's a screenshot running this PR with one of my posts for context. It's a bit much, but maybe it can work if they truncate quite a bit earlier?

[paaljoachim]

Here's a screenshot running this PR with one of my posts for context. It's a bit much, but maybe it can work if they truncate quite a bit earlier?

It would be helpful to show less text directly in List View. As it will become less distracting.

[richtabor]

It's a bit much, but maybe it can work if they truncate quite a bit earlier?

Worth a try? Maybe truncate after 12 characters or so?

[paaljoachim]

Worth a try? Maybe truncate after 12 characters or so?

That seems like a good idea! Let's give it a go and try this out in the Gutenberg plugin.

[paaljoachim]

@jasmussen and @jameskoster
Let's land this alongside the PR from @getdave
#42605

We then have a PR for the Paragraph and List block from @juanfra and the PR for renaming the Group block by @getdave

[paaljoachim]

An option in this PR can be as mentioned from @getdave is autorenaming of Paragraph blocks and an optional renaming of the items in the List block. Anyhow it would be helpful to get movement in this PR.

[BrunoAHVincent]

That sounds good, but how do I implement that? I clicked on commit, then download zip, I installed it but still now working...

[paaljoachim]

Hey @BrunoAHVincent
A Pull Request (PR) is a work in progress file. After a PR has been merged it is set to be included in an upcoming Gutenberg plugin.

It is possible to test PR's being worked on. You can use http://gutenberg.run/ or example this method: https://make.wordpress.org/design/2021/03/03/testing-a-gutenberg-pull-request-pr/

[juanfra]

Hey there, sorry for the delay. I took a look at this one, and this is the result:

Screen.Recording.2023-06-16.at.11.27.57.mov

I'm not entirely convinced about it. I believe it won't be consistent to have a heading taking the whole space of the list item, and right after the paragraph truncating after X chars. Maybe something like this ends up making more sense in the end.

What do you think?

[paaljoachim]

I really liked the video! It really showcased how well truncation works.

I believe that all List View items should be truncated after a certain amount of characters. There is no need to have icon + Paragraph and then the text. As it is easy to understand which block one is in based on what one is writing in document view in relation to what one sees in List View.

[jameskoster]

Nik's suggestion above seems like a good one to me:

1. Add the API for block naming via Custom labelling/naming of blocks in List View #42605.
2. Explore a toggle in preferences to display either the block name or contents in List View. Displaying block contents would utilise that API.

[richtabor]

Perhaps headings and paragraphs should be truncated the same length. Worth a try.

[richtabor]

Explore a toggle in preferences to display either the block name or contents in List View. Displaying block contents would utilise that API.

@jameskoster Would this be applied to the heading block as well? Or should it be specific to the paragraph?

[getdave]

Add the API for block naming via #42605.

I've already restarted work to get this landed.

[jameskoster]

Would this be applied to the heading block as well? Or should it be specific to the paragraph?

Perhaps it should apply to all text blocks?

[draganescu]

Howdy! I know this is a long running PR and I am a bit late to it.

I like the "effect" the PR creates, feels very dynamic and responsive to have the list view self update like that, but while I love this for headings, I too find it's a bit much for paragraphs and lists.

The main question in my head is what part of the editor UX is this UI feature helping with?

• Skimming through content? It's rarely done vertically on one side (e.g. reading the beginning of the 1st lines only) - it's usually a side to side zig zag to grasp context.
• Showing structure? Neither paragraphs nor lists are splitting content into structural parts. This results in what Rich shows in the post screenshot.
• Finding the right list item to select? How is that easier than scrolling the whole document?

it was challenging to identify essential elements like paragraphs and list items for more complex layouts.

If the goal is to improve quick finding of blocks and general block list navigation, maybe we should think of the list view supporting some filter functionality, one that also does a sort of spotlight in the canvas on what it finds, based on your search? Isn't for long text content a classic search better than visual shape recognition?

For text content-oriented blocks, more precisely the paragraph block and the list items, I feel that the default solution would be using the actual content in the list view.

The difference between this PR and the one labeling blocks is that labeling is not happening automatically, it is an on purpose action to anchor something one finds themselves coming back to. This PR automagically creates labels out of x first chars. This seems not optimal even as a preference to me.

In a long text, properly structured, document, one with multiple heading levels, the noise of paragraphs and list items labeled with first x chars in the list view is potentially preventing even the benefit of having heading content visible in the list view, by adding lots of noise.

In a layout document, if a paragraph is important it should be labeled: USP, main_testimonial, benefit_A. The first letters have meaning for the one creating initially but for future editors, the first letters mean not so much compared to labels.

The work is great 👏🏻 and I even like it as eye candy - I can't see it adding to the UX compared to labeling or even nothing.

[getdave]

Just noting that the PR for custom labelling is ready to merge pending a final approval from @WordPress/gutenberg-design

[richtabor]

It comes down to what's more helpful (don't mind the color difference):

I think paragraph content could work fine, but with more truncation.

Then we pull in block naming/labeling (#53735) to the paragraph block, so you can label them specifically if you'd like— i.e. name, role, website for a testimonial pattern, etc.

[draganescu]

The first image is not more helpful, that's what my argumentation tries to convey :)

[juanfra]

Thanks for sharing, @draganescu!

I believe, as James mentioned earlier, that this is subjective. There are many, many use cases for the editor and content creation. And that's what makes all this more subjective.

In my years of creating WP products, I've seen several ways to create content, and a constant pattern I've started seeing over the years is "duplication" of elements (can be a whole CPT, or even a site) as a starting point, and then editing that. I strongly believe it is one of the things that served as a big booster for WP itself (i.e.: one-click demo install, etc). I actually created this PR after duplicating elements for a Knowledge Base article I had to edit for work, and struggling with it.

This is probably one of many use cases, but probably the most important for the proposed changes IMO. Site creators or website owners with 13-inch screens where there's not much space, duplicating content, and later editing and re-arranging things to have their websites. I've tried dragging and dropping things in that environment for a really long document (with elements with different hierarchies) and it was really complicated.

The list view is more reliable for drag-and-drop (the longer the document, the more difficult it is to drag and drop things in the editor), and it's easier to read the tree for more complex layouts.

I think block naming/labelling is definitely the best solution, although I still see value on this happening automatically at least on some elements and probably behind a setting.

[afercia]

While I do recognize that adding part of the content to the text blocks greatly help users with understanding which is which (especially for paragraphs) I'm not sure this is going in the right direction. Specifically, removing the block type name is lless than ideal, both from a visual perspecitve and a semantic persepctive.

Similarly to the case ot icon buttons, we can't rely on icons alone to provide meaningful information.

This is a list of block types, with additional information. The block type name is fundamental and I'd strongly recommed to keep it visible. A new design with some good typography hierarchy could greatly help here. What I'd like to see is the block type bame always visible, followed by an extract of the content on a new line.

Additionally, as often happens in this project, the changes I see in this PR touch only the visuals. Semantics and ARIA patterns aren't taken into great consideration, unfortunately.

The List View has been implemented as a ``role="treegrid"`. More information on this ARIA design pattern is available here:

https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/
https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/examples/treegrid-1/

I'd strongly recommend to get into this ARIA pattern before proceeding with any further change.

The important bit here is that each item needs a proper labeling. Right now, there's an aria-label attribute on each item, and its vlaue is the block type name. So each item accessible name is, for example:
Paragraph
Paragraph
Heading
etc.

Visually, this PR removes the block type name and uses its content instead, truncated via CSS. This is less than ideal as each item will still have the block type as accessible name, but the visible text is the content. This would be a full mismatch between accessible name and visible text, which is a violation of WCAG Label in Name success criterion.

What I'd suggest to implement here is:

• Keep the visible block type name
• Leep the aria-label for each item e.g. aria-label="Paragraph"
• Since the aria-label attribute overrides any other content of the items, the block content must be the accessible description of each item.
• This can be implemented by referencing each item with an aria-describedby attribute that points to the ID of the content container.
• The content needs to be truncated via code, not only with CSS. Potentially, the content could be thousands of words. It's not ok to have all that text within thei tems, as it would be perceived and announced by assistive technology.

Two screenshot to better illustrate:

If we keep only the aria-label, only the block type name would be announced, while the visible text is the content:

If we remove the aria-label, accessible name and visible text would match but that wouldn't help much users to understand what the block type is: that information is only visual and only provided by the icon:

Lastly, I'm not sure what happens with Safari. Looks like Safari displays the entire truncated text in a sort ot 'title tooltip'. I think this is unique to Safari (and I didn't know of this feature) but it's clear that all that text isn't great to see:

Aside:
I never fully understood why the List View has been implemented as a treegrid ARIA pattern. This pattern is poorly supported by assistive technology. There are not even data about actual support: https://a11ysupport.io/tech/aria/treegrid_role
Also, users are not familiar with this pattern abd it's very likely most screen reader users don't even know hot to interact with it. I'd argue that it's also semantically incorrect, as the treegrid pattern has been originally designer for interactive table cells e.g.: a spreadsheet. I'd thing this impelmentation should be refactored and greatly simplified. Worth also noting that #44291 added role=application to wrap the entire List View. While that partially solved some problems, it introdeuced other problems. All that could have been avoided by not using a treegrid pattern in teh first place. Cc @alexstine

[alexstine]

@afercia I wasn't involved from the beginning of the list view so I came in too late to influence the current ARIA pattern. I do disagree that users may not know how to use this pattern as it is starting to become very common. For example, Gmail and Outlook both use a similar pattern for mailbox listing. The role="application" was necessary to implement due to a long outstanding bug in NVDA where coming in contact with the block options button would cause NVDA to switch modes.

I think the biggest problem as I repeated in another PR, #53364, is Gutenberg is not standard to begin with so we have to manage carefully how screen readers interact with it. I fully agree that it is not perfect but I am also of the opinion that given the whole UI today, the list view is probably the most accessible part of Gutenberg for screen reader users.

I would fully support an editor where users could move around in browse/virtual mode but in the current state of things, it isn't possible. I would much rather keep users in one mode to move around the editor vs. having to switch based on the element they wish to interact with.

Slack also faced the same problem when building the message/thread list components. Users have an option under the Accessibility tab in user preferences to use the application role due to NVDA and JAWS unpredictable mode switching. I am of the opinion that the current advances in JavaScript are just not fully to the point of accessible experiences yet so there is a lot of hacking involved to get there.

Then there is Mac, where everything I said above is completely invalid due to how Voiceover is different than Windows screen readers. Its really a no win situation.

Thanks.

[richtabor]

The first image is not more helpful, that's what my argumentation tries to convey :)

Perhaps that’s subjective. I think it’s more helpful than “Paragraph” repeated X times. :)

[richtabor]

If we remove the aria-label, accessible name and visible text would match but that wouldn't help much users to understand what the block type is: that information is only visual and only provided by the icon:

@afercia Just thinking. Is it more important that the technical block type is present, or what the block actually represents (i.e. the paragraph content)? You’re able to understand the block type yes, but not what it actually is.

[draganescu]

@richtabor I am trying to make a very clear and pointed argument not to convey my subjective perception. I haven't had neither an answer for how does this really help the UX, nor addresses to my points about the clutter it creates.

In the words of the author:

I think block naming/labelling is definitely the best solution, although I still see value on this happening automatically at least on some elements and probably behind a setting.

We already have the best solution. "Still seeing value" is not compelling enough to me. The automatic labeling has to be way smarter than cropping 1st x chars from a paragraph. If we want automatic labeling it should also extend to many situations. Maybe covers should be labeled via the heading content if they contain a heading.

Is it more important that the technical block type is present, or what the block actually represents

I don't want to answer in Andrea's place just to say that the problem I see with announcements is that they'll be mixed between block type and block content.

[draganescu]

Following a chat with @juanfra I'd like to point out that my goal is not to reach the ultimate helpfulness (which indeed is a subjective thing) but to figure out how does this change integrate in the "larger scheme of things".

• Should the autolabels be renameable via the modal? How does that look? Should the auto label be the placeholder in the modal? How long should that be>
• Should a labeled paragraph not be auto labeled? What if all its content is replaced? Same for headings.
• Plus my original questions about the UX: isn's a search function better than a blob of text as label?
• If the usecase that the PR solves is finding duplicated content, given the 80/20 motto we use, does auto labeling solve for 80 or for 20 - given we have manual labeling available for everything not just for groups?

@juanfra also pointed to this comment from @mtias :

I want to make a point about separating the need for adding names from the possibility of improving how things are presented in the list view. For example, paragraphs, headings, etc, could be showing their actual content instead of "Paragraph" and "Heading" by default; images could show a small thumbnail, collapsed galleries could show a series of thumbnails, etc. I think that's worth exploring before jumping ahead with custom naming.

Since renaming blocks landed could we get a holistic design exploration that combines labeling (via modal) with autolabeling for any block?

[richtabor]

We already have the best solution. "Still seeing value" is not compelling enough to me. The automatic labeling has to be way smarter than cropping 1st x chars from a paragraph. If we want automatic labeling it should also extend to many situations. Maybe covers should be labeled via the heading content if they contain a heading.

I'm stuck on the inconsistency between the heading block and paragraph blocks. Why should one perform one way (receiving text in place of the "Heading" label) while paragraphs (and other content blocks) do not?

Should the autolabels be renameable via the modal?
Should a labeled paragraph not be auto labeled? What if all its content is replaced? Same for headings.

Yes. I would think an auto-label for any content block is a name I can override if I'd like to. For example, a paragraph block with the content of "Rich Tabor" would have a label in list view of "Rich Tabor" but I can rename that label to "Name".

That custom label of "Name" would persist unless I clear/reset the label (the same flow as the existing "Rename" for group blocks flow).

Plus my original questions about the UX: isn's a search function better than a blob of text as label?

I think search would be interesting to explore, but not thinking it's directly related to this effort.

If the usecase that the PR solves is finding duplicated content, given the 80/20 motto we use, does auto labeling solve for 80 or for 20 - given we have manual labeling available for everything not just for groups?

I think it's more helpful understanding what content is what right off (just like with heading blocks) instead of having to click around and look for the focused block within the block content area.

When we have custom labeling for everything that's just an added bonus that some people will leverage, but I don't expect folks will use custom labels for paragraphs on the norm — more-so for pattern/site building work.

Since renaming blocks landed could we get a holistic design exploration that combines labeling (via modal) with autolabeling for any block?

I don't think we need any design work — the current auto-labeling for core/heading works great. And as I mentioned earlier, if you rename a block you're overriding that auto-label. If you change the content, that custom label remains. And if you clear/reset the label, it returns to the auto-label. Auto-label is essentially a new default (just like heading labels).

And this is all using the existing rename flow exposed in the Group block. We don't need additional design exploration.

[richtabor]

I want to make a point about separating the need for adding names from the possibility of improving how things are presented in the list view. For example, paragraphs, headings, etc, could be showing their actual content instead of "Paragraph" and "Heading" by default; images could show a small thumbnail, collapsed galleries could show a series of thumbnails, etc. I think that's worth exploring before jumping ahead with custom naming.

Yes, I agree! I don't think custom labeling of content will be useful in the context of writing (while auto-labels will). But in the context of site building/pattern creation, we could label paragraphs/headings as what they're designed to be. Like "Testimonial Name", "Testimonial Role", "Testimonial Quote" etc.

[draganescu]

I'm stuck on the inconsistency between the heading block and paragraph blocks. Why should one perform one way (receiving text in place of the "Heading" label) while paragraphs (and other content blocks) do not?

I think the inconsistency is good. Some blocks are structural blocks and others are minute details. Paragraphs, list elements, content inside the details block, image captions, the name of the file in the file block, they're on a level of detail which exceeds the limited area and experience that the list view can offer. The noise will be a hoop to go through when wanting to manually rename too. These items need to be named if the author considers them important. Otherwise the generic "paragraph" label helps identify their role but does not clutter and cause pause.

I think it's more helpful understanding what content is what right off (just like with heading blocks) instead of having to click around and look for the focused block within the block content area.

This is a valid argument but the search for minute details is rarely done visually through a tree of items. A fuzzy search solution is much better for a way to identify minute detail content.

Speaking of understanding, I think one of the worst things this change does is that the only way to separate headings from paragraphs in a text only document is via the heading icon.

[richtabor]

What if we add an editor preference?

[draganescu]

@richtabor yes, that would work - it's really a prefference and it's good to add it as it can help those who need it in certain workflows.

[richtabor]

@richtabor yes, that would work - it's really a prefference and it's good to add it as it can help those who need it in certain workflows.

Now the harder question. On by default? ;)