Iterate the Block directory search results

[enriquesanchez]

Branching off from #22124 (review).

Here's an exploration on ways to improve the design of the block directory search results in the inserter:

In general, I'd recommend avoiding anything lower than 13px for font size and use of italics.

Pinging @mtias and @StevenDufresne for feedback and comments.

[mtias]

Thanks! My first impression is that we are still on the dense side of the curve, overall. It might make sense to have a first view that is more pruned (the icon, name, and rating alone) and when clicking on it it expands to the info card with the ability to install.

[enriquesanchez]

@mtias

Here's another iteration taking your feedback into consideration:

A couple of items I'd like feedback on:

1. How does the placement of the 'Add block' button feel?
2. I cleaned up and simplified the description of the block. Thoughts?

[enriquesanchez]

Here are more explorations around placement of the 'Add Block' button. I'm exploring if it makes more sense to have this button placed at a first level, instead of nested inside the expandable block description.

The above allows those who just want to quickly install a block to do it with one click (maybe you already know what block you want) but it also allows those who prefer to browse and learn more about what they are about to install to have access to that info (via de chevron).

I would love to hear your thoughts, but of all the above, I lean towards the first option. The 'Add block' button is prominent enough and feels like the next obvious action after reading the block name and rating. It then offers the option to expand for more information.

Considering that you'd normally only get a handful or less of results, I don't have issue with the repeating pattern of the 'Add block' button. And as @mapk suggested, if you were to only get one result, it'd be more convenient in that case to have it already expanded.

[StevenDufresne]

Looks nice! I like that you removed the "average rating" copy. For me the "social proof" question that I have when selecting a block is complete within the block itself. Information about the author's other blocks is probably unnecessary. An author may have a great block and a terrible block, for whatever reasons. The terrible block shouldn't deter me from using their great block.

I would love to hear your thoughts, but of all the above, I lean towards the first option.

Of the options you have presented, it is also my pick.

Thought/Idea:
The one thing that troubles me with our current experience is that I can't really see the output of the block until I publish/preview. That's a pretty long journey. While that is consistent with default blocks, there is a built in trust with the default blocks. I'm wondering if there's a more consistent user experience that makes use of block previews. Maybe if we were to offload some the 'sell' to the block preview, we could potentially change the layout from a list view to a tile view, in the same way default blocks work. We then gain consistency with blocks and have the star rating as the differentiator on the tile. hmmm... Note: I recognize the In-document inserter doesn't have previews.

I quickly played the idea out for fun. Its a touch incomplete.

[mapk]

I really like that idea, @StevenDufresne! I was thinking myself about how these might look if they followed a similar grid patters as the core blocks do. I'm glad you explored this!

Offloading some of the details to the block preview is an interesting way to declutter this view too!

[mtias]

This is interesting. I think the grid could definitely work. One downside of the preview is that it's harder to access (virtually inaccessible) for keyboard, so I think we would still want the two-steps in the main inserter (tap on a grid item and see it focused).

[StevenDufresne]

I found another argument for the grid view looking into: #15121 & WordPress/block-directory#14.

Facts:

• When searching for blocks, registered blocks will be returned until the string no longer matches
• When there are no results returned from registered blocks, we search the block directory.

Current Issues:

A registered but disabled block is not returned in the search result (outlined in this issue).

A deactivated 3rd party block is not returned from the inserter nor is it returned from the block directory (outlined in this issue).

Since we only search the Block Directory when no results are returned, if you search for something generic that matches a registered block you will never see alternatives.

I'll need to know the exact name of the third party block to search the directory if a built-in block is generic enough or i already have a third party block installed with a similar title. Maybe we have a block called "Carousel" or they install a third party block. How do i see more carousel blocks? I can't search for "Carousel" again. It will return my registered block. I would need to venture on and make guesses "Carousel full width", "Carousel for mobile".

Additionally, since the plugin guidelines are pushing block authors toward generic block titles, registered blocks will effectively monopolize the inserter. As it sits today, the developers that gets 'carousels' into the block directory first will win out.

Lastly, and maybe a bug, we are also a bit greedy with the results. If you search for "Icons Icons Icons" you'll still only get the built-in "Social Icons" block back. No trip to the block directory.

In #15121, we propose that we show a view for disabled blocks.

If we do so, we won't trigger searches in the block directory. As a user, I'm further bound to built-in or third party registered blocks.

---

All that to say, my suggestion is...

Anytime a user searches in the inserter, search the block directory and return items in a section. When there are no registered blocks that match, show the view I posted above. If there are still matches, append the block directory items.

Thoughts?

[enriquesanchez]

@StevenDufresne regarding the grid view, where would the "Add block" button be placed?

[mapk]

I'm not saying this is the right answer, @enriquesanchez, but maybe it just gets added the same way one adds a block from the Inserter today. Just click the block and it gets added.

[StevenDufresne]

@StevenDufresne regarding the grid view, where would the "Add block" button be placed?

Great question, and yeah that's the tricky part and It's fine if the grid view ends up only being an exploration but I'd like to unfold my ideas and leave them here :).

Building on what @mapk's mentioned above, I think that clicking on the block should just add it as if its a built-in block. Let me try to convince you as well :)!

We don't really communicate to users that adding a block directory block actually installs a plugin in the background. For all they know, the block directory is the name for a different collection of blocks. We are assuming that providing the additional block/author info communicates the separation, and for advanced users, i think it would be understood. For others, I'm not convinced.

In the early explorations phase (I wasn't around then, so its based on threads I have read), we were concerned about leaving behind unused but installed block plugins. This is especially a concern because installed blocks could potentially have site-wide consequences. We decided that we should uninstall blocks if they were added to the post but not used when they save.

Note: The code was removed during a refactor and we intend to add it back (#22307).

If we don't communicate that things get installed into your plugin directory when you add a block, and we remove them if you don't use them, then we should push for seamless. We should note that they are from the block directory, and provide them with a bit more information so they can choose the right one.

But if we keep the uninstall feature, which we probably should, then its a weird experience if I install 2 blocks and only use one. If I search for the one I used that didn't get uninstalled, it'll show up in the inserter looking like a built-in block. If I search for the other block that was uninstalled, it'll look like a block directory one because i didn't use it. That process is opaque to me and I would have no idea why.

This inconsistency, coupled with some of the current search limitations I mentioned in my previous post...... I think when they click on the block it should just add. 🤓

[enriquesanchez]

@mapk @StevenDufresne I do like the idea of "click to install" and skipping the "Add block" step.

I do wonder if this interaction would be as expected by most users. Knowing that everywhere else in WordPressland I have to intentionally click "Install", "Activate", "Add new", etc, I'm not sure if skipping that step would make for an obvious interaction here.

Granted, you can always undo/uninstall. So I'm not 100% certain...

Another thought I have is that the more these block library results look like currently installed blocks, the more blurred these lines become, and I wonder if this can make someone not be aware that they are looking at results from the block library. Again, I'm not 100% certain if this would be a desired outcome or not...

[StevenDufresne]

@enriquesanchez I'm with you and share the same concerns. I don't know what the right solution is. Blurring the lines feels like the right UX for Gutenberg but not necessarily the right solution for the WordPress community.

At the same time, I wouldn't want penalize Gutenberg with WordPress plugin paradigms seeing that blocks are not intended to be typical WordPress plugins per se. They have different guidelines to keep them small and purposeful.

Additionally, with the block directory being experimental and completely new, I think it makes sense for us to make the boldest move and scale back. I would prefer feedback that says we moved too fast, than too slow.

In the end, since this is mostly a CSS problem, I may look to A/B testing. This experience really needs to be felt. Designs don't do a good job communicating the intricacies.

[enriquesanchez]

@StevenDufresne You make really good points and Ithink this new direction is worth exploring.

I think your mockups are a good starting point. Would you still need help with any design work?

[ryelle]

I see @mtias mentioned it above, but you can't get to the preview box with a keyboard or screen reader, so we shouldn't put useful information there.

The description, rating, and last-updated date are metrics used for picking a plugin, and I think the assumption is that they'll be similarly helpful for picking a block (even if you can install a bunch and then pick, that info could tell you where to start). If that's the case, and we want to show this info to users, it should be accessible too.

Maybe we could still explore a popover/modal style approach, where a user would tap the block icon -> focus into a modal with the extra info -> click a button to add the block (or click away to close).

[mapk]

I'm a bit torn on this, @ryelle. You bring up good points. When adding a block to the page as a user, I'm very interested in seeing the block preview and a description. These are the two items we show for installed blocks. It stinks that they aren't accessible and that should exist as a separate issue from this one so we can focus on that. I'm glad that's being raised. 👍

That being said, blocks feel almost ephemeral (probably the wrong word). I can add one to the page, delete it, convert it, etc. A plugin frequently involves some sort of settings. They often come with their own interface. It feels like a process. Adding a block from the Inserter is a different mental model than adding a plugin. They're totally both plugins, but they feel different.

I'm partial to adding/installing a new block with the one-click step outlined by @StevenDufresne above. Having this exist in the plugin for a bit might provide some good feedback if we're sure to elicit it once it's ready.

[shaunandrews]

Just discovered this issue today and wanted to throw in my quick mockup to hopefully stir up some more activity around updating the design of the results; What I see in master now is super heavy, and hard to scan. Here's my quick mockup:

[MichaelArestad]

Here's my first take on it after looking at all of the above. I'm not quite ready to call it a proposal as I would like both developer and design feedback.

Add block via search prototype i1

• The list of blocks is as simple as possible by only showing the name, the author, the ratings, and the block icon (not the plugin icon). I am relying on the block preview to show more information. I'll circle back to this shortly.
• The presentation deviates from the standard block grid to not only make it more readable, but also give the user an idea that these aren't installed blocks.
• I went with an "Add" button on hover/focus to both install and insert the block. It seems like the most flexible term here.
• The hover state shows the block preview just like installed blocks. There is additional information and the user should be able to navigate into the preview window for relevant links. This means we will need to work out the best method to do this in an accessible way. If it is not feasible to make the preview accessible, I am willing to revisit the designs.

Here is a gif showing the start of this flow:

You can try out the prototype if you like.

More details

What happens when block names or author names get long? I propose it wraps just like a paragraph. It is simple and the most readable based on my explorations:

Focus states. I have opted for minimal focus states indicated by the appearance of an "Add" button. I did try a variant with the usual blue border, but it was a little much:

Black rating stars. These fit more with the latest Gutenberg styling and felt more cohesive than repeating yellow stars. They're also a bit higher contrast (win!).

The block preview:

The anatomy of the block preview should be familiar. It follows the exact conventions of the previews for installed blocks:

• Preview
• Block icon
• Block name
• Block description

Following those are the addition of the "active installs," the "last updated" information, and a "More details" link. The "More details" link could either open a modal showing the full plugin information or could take the user to the plugin directory.

I chose not to add the plugin author or ratings in the block preview window as it is somewhat duplicative.

Since I would like the user to be able to navigate to this preview with a keyboard or mouse, I think we could also include some screenreader buttons like a duplicate "Add" button so the user doesn't have to navigate back to the list to install the block.

Going further

Here is a gif expanding on this concept and going through the flow of a user-initiated block directory search:

You can try out the prototype if you like.

Source figma file

[shaunandrews]

The "More details" link could either open a modal showing the full plugin information or could take the user to the plugin directory.

The way these floating previews work today preclude them from containing interactive elements — they only appear when hovering an item, so you can never actually move your pointer and clicking on anything inside.

[shaunandrews]

Focus states. I have opted for minimal focus states indicated by the appearance of an "Add" button. I did try a variant with the usual blue border, but it was a little much

I think this breaks the progress we've made on having a more consistent and understandable focus state. I don't think the button alone is enough to indicate keyboard focus; If the whole row/item is clickable then I'd expect the blue ring.

[mapk]

If I wanted to jump back from the Block Directory results to the installed blocks that may have shown in my original search, is that possible? Or once I enter into the directory results, would I have to do another search with that same keyword to see my installed blocks again?

Should I be able to see them both at the same time?

[enriquesanchez]

We should avoid actions and important information than only appears on hover.
In the prototype, someone using a touch device would not be able to reach the Add button and wouldn't be able to access the content in the flyout.

[MichaelArestad]

If I wanted to jump back from the Block Directory results to the installed blocks that may have shown in my original search, is that possible? Or once I enter into the directory results, would I have to do another search with that same keyword to see my installed blocks again?

I thought about making them visible at the same time, but it ultimately lacked clarity and focus. If the user intends to search the directory, we can let them do that. What I'm not sure about yet is exiting the search. Currently, cancelling the search will hide the block directory results. Changing search terms also restarts the search. In this case, it would likely revert to local blocks unless specified. Clearly entering/exiting search might be a problem. I'd like to save discussion around user-initiated search for that thread when we get further. I shared it as it's a similar context that might use the same patterns. It might also make sense to, instead, open a modal with dedicated block directory search or take the user to an Add Block page in wp-admin (like Add plugin).

[mtias]

Good explorations, I like the perspective of a slightly more condensed view. One general thing to comment is that it might be good to explore options where the directory results are on demand (a "show results from the block directory" action, for example) rather than list them there all the time. It can be slightly unnerving to see content that you haven't explicitly vetted show up on a search directly. It might also be good to have a clear separation between "installed" and "in the block directory".

We need to handle cases where there is a local result precluding you from searching the directory further, so I'd suggest looking at that from the beginning since it might change the design in significant ways.

[MichaelArestad]

One general thing to comment is that it might be good to explore options where the directory results are on demand (a "show results from the block directory" action, for example) rather than list them there all the time. It can be slightly unnerving to see content that you haven't explicitly vetted show up on a search directly.

@mtias Good point. Exploring that now.

We need to handle cases where there is a local result precluding you from searching the directory further, so I'd suggest looking at that from the beginning since it might change the design in significant ways.

I agree. That's one of the reasons why I prototyped that exact scenario in the "Going further" section of my comment. I think I'll try something similar to that flow for having a user choose to show the directory search results when no blocks are found locally.

[mtias]

Another case to keep in mind in search results are block that might have been disabled by the user using the block manager — we should list those and allow enabling them back easily.

[MichaelArestad]

Another case to keep in mind in search results are block that might have been disabled by the user using the block manager — we should list those and allow enabling them back easily.

@mtias I'm less sure about this being a need. If an admin has removed them from the inserter intentionally, why show them there? Have you heard cases where folks are having trouble re-enabling blocks?

I do have an idea of how to do what you ask from a design perspective and will bring it into the next prototype. It's just hard for me to understand the need on this one.

[mtias]

The disabling of blocks is per user, so it's the user having disabled it in the past and forgetting about it. There have been a few cases reported already of people missing the ability to add, say, an image and finding out they disabled it at some point in the block manager.

[MichaelArestad]

@mtias got it. I'll make it so.

[MichaelArestad]

Add block via search prototype i2

Here is the second prototype.

Changes

• There is an additional step before displaying the block directory results. This is to help clarify the flow and give users the choice to intentionally install additional blocks if needed. Coincidentally, this view will also be useful for allowing users to show block directory results even if installed blocks match their search.
• There is now more spacing giving the blocks a little more breathing room. It also makes them feel closer to the design of installed blocks.
  *The contrast of the least important elements has been lowered to make the title and rating remain prominent. This results in a list that's faster to scan.
• After iterating on the "Add" button styles and placement, I decided to go a different direction. It was limiting space for the plugin name/author more than I wanted so I tried removing it to see how it feels. To me, it's much smoother and much closer to the way blocks already work.

Screenshots

Next steps

1. I am going to mock up a flow to show blocks that have been hidden from the inserter via the block manager. It likely will not deviate much from the above flows. I'm doing it as its own flow for my own prototyping sanity.
2. I am going to explore the idea of a modal that pops up the first time a user clicks a block in the block directory that explains that a new block is being installed.

.
.
Source figma file

[kellychoffman]

The overall flow is feeling good. Once you work through the other flows mentioned, I would tighten up some of the UI elements.

• Making sure left border of hover state aligns to the left of the Search box
• Spacing above and below "No Installed Blocks" and "Showing x Available Blocks" feels too large
• "Showing x Available Blocks" heading feels odd centered and it doesn't feel like it should have such prominence
• "No Installed Blocks Found" step could use a little somethin'! Jazz it up a little.

[ryelle]

In cases where we have trouble installing the block (it causes a fatal error, something's broken in the block, or the registration just didn't work), we add an inline message like this:

Where should that go in this iteration?

[MichaelArestad]

@ryelle good question. I'll work it in to the next iteration!

[MichaelArestad]

Alrighty! Round 3! Now with a mobile flow and a flow for hidden blocks (sort of)! 🥳

Prototype i3 - large screens

Try the prototype!

Changes:

• Alignment and padding changes as requested :)

@ryelle regarding the "already installed" notice. Does the user need to ever see that? Do they need to reload? I would much prefer we don't show the notice and instead let them add the block by clicking it.

Screenshots
Source Figma page

Prototype i3 - small screens

Try the prototype!

Here's where we get into new territory. Mobile doesn't have the benefit of screen real estate so I wanted to show the description right in the list on smaller screens. This is because we can't don't the block preview on mobile and I wanted to stay consistent.

Screenshots
Source Figma page

Hidden blocks

Hidden blocks are a bit of a doozy. I tried some ideas to "unhide" blocks right in the inserter, but I'm not sure that's the right place for that. Instead, I'd like to list them in a "Hidden" category that shows up in searches.

After that, I think we should work out a way for a user to see that a block in the editor has been hidden from the inserter. We can approach this a variety of ways that go well outside the focus of this issue. I would like to show them either in the block toolbar or inserter via a notice. Or perhaps, if a block has been added in the editor, we simply unhide it. :)

Source Figma page

[enriquesanchez]

Really digging how much more simple this whole flow feels with the updates you've made.

I'm not missing the 'Add button' we had before, it's really not necessary. We'd just need to be careful that these search result buttons communicate the appropriate action and info to AT, such as screen readers.

Love that you include the description on mobile. This takes care of the fly-out dilemma we had before.

I also like the flow for hidden blocks, I'd just suggest we add a little description of what a hidden block is and/or why this is a thing and what will happen if they add it.

[ryelle]

Does the user need to ever see that? Do they need to reload? I would much prefer we don't show the notice and instead let them add the block by clicking it.

@MichaelArestad If everything's working correctly, they never see it and the block is added. This is an error state - something went wrong when installing, and we can't add the block to the page. The only way to fix it is to reload, but we don't want to do that without user interaction. Possibly this is caused by someone installing a block while the editor is open in a different tab, or something's wrong with a block and it causes a JS error, etc.

I'm not missing the 'Add button' we had before, it's really not necessary. We'd just need to be careful that these search result buttons communicate the appropriate action and info to AT, such as screen readers.

@enriquesanchez Since it seems like the whole block result is a button now, what do you think is the best way to handle that for screen readers? I'm also not sure what you mean by "communicate the appropriate action and info".

[StevenDufresne]

I'd like to list them in a "Hidden" category that shows up in searches.
I like where that is going. Those category headings are pretty muted, in fact, I barely register that they are there let alone how they contextualize the blocks below. It may make sense to have an icon on the block tile, or something that more overtly communicates that's it currently hidden/turned off.

Also, I can't remember, are hidden blocks user-specific? If not, another {role} may have hidden it for a reason, do we want to make it so easy to turn back on?

[enriquesanchez]

@ryelle I'm thinking that it can be handled similarly to how we do with block patterns, where the pattern itself is a button but the title and description are announced to AT.

Do you think that would also work here?

[MichaelArestad]

This is an error state - something went wrong when installing, and we can't add the block to the page. The only way to fix it is to reload, but we don't want to do that without user interaction. Possibly this is caused by someone installing a block while the editor is open in a different tab, or something's wrong with a block and it causes a JS error, etc.

If I'm understanding this correctly, when this situation occurs, there's no way to insert the block without a reload? This confuses me, because the block can be installed and inserted without a reload.

Also, I can't remember, are hidden blocks user-specific? If not, another {role} may have hidden it for a reason, do we want to make it so easy to turn back on?

@StevenDufresne They are user-specific in this case. These are blocks that are hidden because the user went to the block manager and chose to hide them. If they are hidden by other means, I don't think we should show them in the inserter at all.