Block Editing Modes

[talldan]

For a while, Gutenberg/WordPress have shipped a stable (but mostly undocumented) feature called 'Block Editing Modes'.

A breakdown of how this feature works:

• API users can trigger an action setBlockEditingMode( clientId, mode ), where mode is one of three options:
  • 'default' - makes the block editable normally with all the regular block options available. This is the default value (used when the block has this value set explicitly or no value has been set).
  • 'contentOnly' - allows partial editing - Rich Text content, adding links etc. Controls in the block inspector are hidden. Blocks may also have their own internal logic to show/hide specific controls when in this mode.
  • 'disabled' - makes the block completely unselectable or editable. It not only affects the block, but also all child blocks (to any depth) inherit this behavior unless they have one of the other modes explicitly set.
• unsetBlockEditingMode is an action that removes one of those modes, and the block (usually) implicitly has the default mode again.
• getBlockEditingMode( clientId ) is a selector that can be used to retrieve the block editing mode for any block.
• const currentMode = useBlockEditingMode( newMode ) is a hook that can be used as both a getter and a setter. It's used within a block's edit function, and automatically determines the block's clientId from React context.

This API seems to be increasingly important as it underpins how blocks are interacted for a host of different features (Zoom Out, Write Mode, Synced Patterns, Page Editing, contentOnly template locking).

The API has noble goals, but there are some problems I've noticed or seen discussed. I've listed them below with the initial implementation. It'd be great to discuss ways that this can be improved.

Problems

At the surface, it might seem like quite a simple API, but there are a few problems:

• The modes work quite differently. While 'default'/'contentOnly' are similar and only affect the current block, 'disabled' is far more powerful in the way it can be inherited and also has a lot of nuance. A lot of the time this difference isn't fully understood (it doesn't help that there's limited documentation).
• The way 'disabled' works is expensive. It results in a need for recursive code that traverse sthe block hierarchy checking if there are any 'disabled' modes. getBlockEditingMode itself is recursive, but there are also other recursive selectors that call it like isBlockSubtreeDisabled. This is exacerbated by the way setBlockEditingMode( 'disabled' ) or useBlockEditingMode( 'disabled' ) feel like cheap calls, but can be called from components that aren't well optimized, resulting in repeated setting/unsetting of block editing modes (DisabledNonPageContentBlocks has this kind of effect when the dependencies change 😓 ).
• A block editing mode of 'contentOnly' is easily confused with a template lock of 'contentOnly'. The two things work differently since template lock is inherited, while the block editing mode isn't.
• Block editing mode is used behind the scenes to implement the contentOnly template locking. However, other types of template locking are not built using block editing modes. This results in overly complex logic when determining things like
  • can blocks be inserted here?
  • can blocks be moved?
  • the controls that should be shown for a block
• Similar to above, Block Editing Modes aren't expressive enough. For example, there are bugs like Write Mode: Block Movers appear when content block is immediate child of a section #67408 that seem to be very hard/impossible to solve with the way it works today. A use case (for sections, synced patterns, template locking) is requiring a block's inner block list be 'disabled' while the block itself is 'contentOnly' or 'default', but it can't be done.
• If setBlockEditingMode is called for the same clientId from different call sites, it results in race conditions, the last call wins.
• Often the modes are used to achieve a range of goals that aren't always compatible. For example, contentOnly is used for both container blocks (group, pattern etc.) and content blocks (paragraph, heading, image). Other contextual clues are often used to change the way a block works (is the block a section?, what's the block's type?). I think this leads to some hard to answer existential questions like "does this block work like this because it's contentOnly, or because it's a section?".

[talldan]

@gziolo asked a question on slack, thought I'd answer it here:

Do we have a clear understanding of what is the expected behavior for users broken down by scenarios like editing a post/page/cpt, template, template part, pattern, section / container block, or individual block?

I don't believe this exists in a single place. I think there are two things the block editing modes are used for:

Distinguishing between local and global content.

There's some relevant discussion in this issue: Ensuring local content is not added at the global scope, and vice versa

Particularly in this comment.

The block editing modes are used when editing to disable the content that's global so that users don't accidentally edit something that applies across a site. It applies to:

• Post / Page editing with the 'Show Template' option active. In this mode only the Post Title / Feature Image / Post content (and child blocks) are editable. The template for the post has to be edited completely separately.
• Synced Patterns, work essentially the same as above, local content (blocks with overrides) are editable, the source pattern has to be edited completely separately.

Write mode / Zoomed Out / contentOnly locking

issue: Writing and contentOnly modes.

These are tools within an editor that aim to reduce the complexity of the block hierarchy by only enabling selection/editing of particular blocks:

• In Zoom Out and Write Mode, blocks that are considered 'sections' can be selected and rearranged, and new sections can be inserted.
• In Write Mode, 'content' blocks (any block with a role: 'content' declaration on an attribute in the block.json) are also editable
• contentOnly locking - there's no user facing option for this at the moment, but it essentially exists for the same purpose with the difference being it can be applied to a subset of blocks

After reading this, I think it's also possible to combine the two categories, both aim to lock the design of a piece of content (the structure is locked), while still leaving it possible to edit text and media. Since the question asked about flows, I think it's good to make a distinction between the parts of the editing experience that are implicit (synced patterns, page editing) and those that are optional tools (write mode, zoom out), so that's why I've broken them into two.