List View block support: Hide list tab when allowedBlocks is empty, with no children

[andrewserong]

What?

Add a per-instance way for a block to disable the List View block support when it's template locked and has no children. The idea is that consumers may want/need to be able to disable the list view tab programmatically rather than just the boolean in block.json.

Why?

It's possible to have blocks that only want to allow the list tab or view to be available based on a certain set of conditions (or a mode). The primary use case I have in mind is that of a Dynamic Gallery block that has two modes: a dynamic one where the inner images are fetched via a query, and a static mode where individual blocks are set within the block. I.e what I'm exploring in #78796

That's just one use case, though. There could be many cases where a block wants or needs to hide its internals based on a condition. So this PR is proposing a general way to do that.

How?

• Previously this PR tried to add a listView flag, but it turns out we can infer a desired state for hiding the list view tab via allowedBlock: [] or allowedBlocks: false (and the absence of any inner blocks). This state can effectively become a "managed inner blocks" mode.
• Add a shouldRenderBlockListView selector to return whether or not the list view support is available — this way we're not just checking if the block type allows it, we're also checking if the block currently supports it

For an example of how a consumer might use this in practice, take a look at #78796 which adds a dynamic gallery block variation (effectively a mode).

Testing Instructions

We can simulate the behaviour in #78796 by updating a block locally to set allowedBlocks: []. This is quite artificial, the real use case is in the other PR. Here's a diff to apply it to the Gallery block in this branch.

In this case, to demo the behaviour, I've wired up switching allowedBlocks: [] to the randomOrder value so that you can see it hiding the list tab in the editor:

diff --git a/packages/block-library/src/gallery/edit.js b/packages/block-library/src/gallery/edit.js
index 12aeb5432b3..02ea6636798 100644
--- a/packages/block-library/src/gallery/edit.js
+++ b/packages/block-library/src/gallery/edit.js
@@ -603,6 +603,12 @@ export default function GalleryEdit( props ) {
 		directInsert: true,
 		orientation: 'horizontal',
 		renderAppender: false,
+		// TESTING ONLY — do not merge. Toggle the gallery's "Randomize order"
+		// setting to declare `allowedBlocks: []`, turning it into an empty,
+		// insertion-disallowed container so the List View exclusion and the
+		// drag-and-drop/insert block can be exercised without the dynamic
+		// gallery feature.
+		allowedBlocks: randomOrder ? EMPTY_ARRAY : undefined,
 	} );
 
 	const dropdownMenuProps = useToolsPanelDropdownMenuProps();

With the above diff applied, if you add the following block markup, you'll see the Gallery block with no list tab:

<!-- wp:gallery {"randomOrder":true,"linkTo":"none"} -->
<figure class="wp-block-gallery has-nested-images columns-default is-cropped"></figure>
<!-- /wp:gallery -->

Note again: this is a very artificial example to help test this branch. The above state is effectively useless on this branch, but it will become useful in the dynamic gallery PR (#78796)

Screenshots or screencast

With the above diff applied for example, the List tab would be hidden if you have randomOrder toggled on with a gallery block that has no children:

Use of AI Tools

Claude Code and Codex

[github-actions]

Size Change: +85 B (0%)

Total Size: 8.6 MB

📦 View Changed

Filename	Size	Change
build/scripts/block-editor/index.min.js	380 kB	+85 B (+0.02%)

_{compressed-size-action}

[github-actions]

Flaky tests detected in cdd94c4.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/27656969731
📝 Reported issues:

• [Flaky Test] Should save the changes #78689 in /test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js
• [Flaky Test] Text blocks sync modifications between users #78855 in /test/e2e/specs/editor/collaboration/collaboration-block-gauntlet.spec.ts

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: andrewserong <[email protected]>
Co-authored-by: tyxla <[email protected]>
Co-authored-by: ramonjd <[email protected]>
Co-authored-by: talldan <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[andrewserong]

Switching back to draft while I try out some other ideas. One thing I wasn't quite happy with is that this PR is an imperative call to disable the support. @talldan has suggested looking at a property on useInnerBlockProps which might work better.

I'll be AFK soon, so I'll likely play around with this more sometime next week.

[andrewserong]

Just switching this over to ready for review now. The main change is that this moves the listView flag to something that can be set within useInnerBlocksProps which makes it bit more declarative and avoids having to add an action / setter.

It also means that combined with templateLock: all it's possible for a consumer to effectively create a "managed inner blocks" state. That's what the dynamic gallery block prototype PR tries out in the gallery block via:

gutenberg/packages/block-library/src/gallery/edit.js

Lines 654 to 668 in 39f3ed7

	const innerBlocksProps = useInnerBlocksProps( blockProps, {
	defaultBlock: DEFAULT_BLOCK,
	directInsert: true,
	orientation: 'horizontal',
	renderAppender: false,
	// In dynamic mode the inner blocks are managed by the source, so lock
	// the container: this prevents inserting or dragging blocks into it
	// (e.g. from the main List View sidebar) via the standard
	// `getTemplateLock` -> `canInsertBlockType` path.
	templateLock: isDynamic ? 'all' : undefined,
	// In dynamic mode the gallery has no real inner blocks to navigate
	// (it renders a preview of the query result), so opt the instance out
	// of the List View.
	listView: ! isDynamic,
	} );

So essentially the proposal here is: add a small flag within useInnerBlocksProps that consumers can use as one part of how they control display and interaction with inner blocks.

(As always, I'm not wedded to any one approach for this, so happy for feedback if this looks off as an overall approach!)

[tyxla]

Thanks for this @andrewserong!

I'm a bit torn if we really need a new listView API - see my comment below.

I think the rest is just mechanics and quite straightforward to finish once we agree on that.

Curious to hear what others think too.

[tyxla]

Now that isEnabled comes from hasBlockListViewSupport( clientId ) instead of hasListViewSupport( name ), is name still used anywhere in ListViewPanel?

[andrewserong]

Looks like we're still using it as a visually hidden label for the panel in order to get its block name / title:

[tyxla]

Picking up the thread from my comment on the gallery PR (#78796 (comment)), since this is the better place for it.

I'm not convinced we need a dedicated listView opt-out API, and I'd like to question it before we commit to a permanent public surface. The thing that nags me: the flag is only ever subtractive, hasBlockListViewSupport shows it can only turn participation off, and only for a block that already has type support. So it's not really a new capability; it's a refinement of "should this instance's List View show." That makes me wonder whether the answer can be derived from the state we already have rather than declared.

The "managed inner blocks" state that motivates this is templateLock: 'all' + listView: false. A fully locked container that renders a preview has, by definition, nothing insertable and nothing navigable, which feels like enough signal on its own. So the question I'd like us to answer explicitly: can List View participation fall out of existing semantics, e.g. templateLock: 'all' with no navigable children, or a block editing mode like disabled/contentOnly, instead of a new flag a consumer has to remember to set alongside the lock?

Two concrete costs push me to ask: it's a permanent public API on useInnerBlocksProps, born from a single experimental consumer; and the BlockEdit change adds a store subscription to a per-every-block hot path, where the value was previously computed synchronously, and for the motivating case (gallery with no descendants) that propagation looks inert anyway.

To be clear, I think your composition instinct in #1229 makes sense, pairing templateLock: 'all' with a list-view signal beats inventing a bespoke "managed" mode. My doubt is narrower: whether the list-view half needs to be its own declared flag, or whether it should be a consequence of the lock/editing-mode the consumer already sets. If we try deriving it and it turns out gnarly (the navigation special case, controlled-blocks cases like Page List, etc.), then a minimal explicit flag like this is a fine outcome, but I'd like to see that we tried, so we're adding the API because the derivation doesn't hold, not by default.

[andrewserong]

I'm sold! 😄

It seems to be working quite nicely for me without the listView flag, so I've reworked the PR to go for the inferred approach. Let's see how it holds up!

[andrewserong]

Thanks so much for the thorough review @tyxla! I think you might have mentioned the idea of inferring the managed inner blocks state elsewhere, but it didn't quite click for me until you explained it in detail above.

I've reworked this PR to try that out so that it now becomes templateLock: 'all' + no inner blocks to set an effective "managed inner blocks" mode where the list tab is hidden.

This feels much better (and simpler to me) and gets to the heart of the use case for the dynamic gallery block. It also resolves a couple of your other (valid) comments about the PR.

I'll update the dynamic gallery block PR shortly to match the new behaviour of this one, but right now this is feeling much better to me!

This should be ready for another look. I'll be AFK tomorrow, but will continue on with this work next week. Thanks again!

[ramonjd]

Just catching up here, thanks for all the helpful explanations folks!

[ramonjd]

Kudos for trying out the suggested approach! in my testing when I replace the diff example with something like

templateLock: randomOrder ? 'all' : undefined,

and I see

<!-- wp:gallery {"randomOrder":true,"linkTo":"none"} -->

I don't see the list view's status changing, though the innerblocks are locked 🤔 I'm probably doing something wrong, or is that expected?

Curious, what's the intended usage for the dynamic gallery? It would set templateLock by default?

[ramonjd]

Maybe because gallery has N image inner blocks regardless of randomOrder, so getBlockOrder( clientId ).length === 0 never holds 🤔

That's probably it

[andrewserong]

I don't see the list view's status changing, though the innerblocks are locked 🤔 I'm probably doing something wrong, or is that expected?

The testing steps in this PR are quite artificial — it'll only work if the Gallery block has no inner blocks. It's much more natural in the dynamic gallery PR, but for this branch, you can use the following markup to get to that state:

<!-- wp:gallery {"randomOrder":true,"linkTo":"none"} -->
<figure class="wp-block-gallery has-nested-images columns-default is-cropped"></figure>
<!-- /wp:gallery -->

[ramonjd]

I eventually got there when I saw getBlockOrder( clientId ).length === 0 - i inferred my testing from the code. shoulda read the pr desc 😄

[andrewserong]

Curious, what's the intended usage for the dynamic gallery? It would would set templateLock by default?

You can see it in the dynamic gallery PR, but it'll set the logic like this:

	const innerBlocksProps = useInnerBlocksProps( blockProps, {
		defaultBlock: DEFAULT_BLOCK,
		directInsert: true,
		orientation: 'horizontal',
		renderAppender: false,
		// In dynamic mode the inner blocks are managed by the source, so lock
		// the container with `templateLock: 'all'`. This prevents inserting or
		// dragging blocks into it (via `getTemplateLock` -> `canInsertBlockType`),
		// and — because a locked container with no inner blocks has nothing to
		// navigate — also opts the gallery out of the List View.
		templateLock: isDynamic ? 'all' : undefined,
	} );

[ramonjd]

Is this the same check as typeHasListViewSupport above? Would hasListViewSupport work for both? Or with an added type if you think that's clearer, though I think the context makes it so.

[ramonjd]

Oh, typeHasListViewSupport is gone now 😄

[talldan]

I guess template locked + no blocks makes sense in terms of hiding the tab, a user wouldn't be able to insert blocks into a template locked empty block anyway and there are no blocks to view or rearrange.

I wonder though, why does a dynamic gallery have no blocks? Is it because a BlockPreview or similar is being used to show the dynamic gallery? The BlockPreview feels like an implementation detail. Using a block preview makes the gallery images inert and removes them from the accessibility tree, so it may not be the best implementation.

templateLock: 'all' is also overridden by templateLock: contentOnly on a parent, so that's something else to note. If you put a dynamic gallery in a group that has templateLock: contentOnly then the gallery's List View is visible again.

[andrewserong]

I wonder though, why does a dynamic gallery have no blocks? Is it because a BlockPreview or similar is being used to show the dynamic gallery? The BlockPreview feels like an implementation detail. Using a block preview makes the gallery images inert and removes them from the accessibility tree, so it may not be the best implementation.

It's partly because we're using a block preview, but also because they're not really blocks in this case. They're not interactive and they can't be arranged or customised in any way, as the final output is generated by a query. I think it makes more sense for it to not have inner blocks until a user switches off building by a query (switches to static blocks). But the decision here was partly influenced by thinking this isn't really inner blocks and partly because when I researched existing popular plugins that created dynamic galleries, they typically used a preview in the editor rather than inner blocks.

templateLock: 'all' is also overridden by templateLock: contentOnly on a parent, so that's something else to note. If you put a dynamic gallery in a group that has templateLock: contentOnly then the gallery's List View is visible again.

Oh, good catch — I'd tested with an unsynced pattern where the Dynamic Gallery exists within it, but I hadn't tested with a Group block with templateLock: contentOnly set with an inner Dynamic Gallery block. I wonder for this case: why would we override templateLock: all on children? Or if there's a way we can handle this case in the checking logic here 🤔

Here's how it's looking on the dynamic gallery PR (the list tab is available but there's no appender for the dynamic gallery):

I might not get a chance to keep iterating here before I wrap up for the day, but can dig in further next week! I'm quite liking the inferred approach now, as it seems overall less complex than the inclusion of the listView flag, but it'd be good to iron out the creases / see if this (or other) edge cases prove tricky. (Also happy to go with listView after all if it feels like a better solution)

Thanks again everyone for taking a look!

[andrewserong]

Tiny update: I've made it so this also respects allowedBlocks: false for disabling the list view, too. I think this should be ready for another round of reviews now.

[ramonjd]

I tested this with a gallery block and the code snippet as is, and inside a pattern, synced pattern and template and the block is behaving as expected 🎉

It's looking consistent to me so far. I only had a nitpick comment to offer 😄

[ramonjd]

This is testing well for me ✅

allowedBlocks + listView combo is a good signal I think. Happy to defer to other reviewers, but LGTM

Just left a non-blocking question around "parent": [ "some/block" ]

[andrewserong]

This is testing well for me ✅
allowedBlocks + listView combo is a good signal I think. Happy to defer to other reviewers, but LGTM

Thanks for the approving review! 🙇

This feels like it's been quite a collaborative PR this one as we've tried out a few different approaches, and I'm indebted to the all the good feedback from you all (@ramonjd, @tyxla, and @talldan). As such I'll leave this PR open overnight just in case there's any last minute feedback or concerns.

In my view, I think we've landed on a good shape and heuristic, so if there aren't any objections I'll merge it first thing tomorrow and then rebase the Dynamic Gallery prototype accordingly.

[tyxla]

Not much more to add, just a few non-blocking comments - this looks pretty solid! Thanks @andrewserong!

[tyxla]

This remains something to potentially follow up on as it might occur to some folks as unintended behavior.

[andrewserong]

Thanks Marin! I've renamed the private selector to shouldRenderBlockListView and re-tested locally. This is still all working well for me, so I'll merge it in now. Happy to pursue follow-ups of course if there are any issues after merge.