feat(core): split keyboard behaviour from container structure - #3142

Builds on #3059. This PR separates how the keyboard treats a block from how the block is structured.

Why

After the tabs and stepper examples (#3140), I moved the built-in toggle blocks to the frame API (renderFrame). The frame part worked for about 90% of the cases immediately: the chevron, the "Add block" button and the open state all moved into a frame with less code than before.

The keyboard part did not fit. A toggle needs some behaviour of a "titled" block, but not all of it:

• When the toggle is open, Enter in its text must go into its children (as in Notion). When it is closed, Enter must split the block.
• Enter in an empty child must add another child. It must not leave the toggle and it must not outdent.
• Shift-Tab must still move a block out of the toggle. For a toggle, children are nesting, not a body.

In #3059, all of this came from one flag: children on a block with content. That flag switched on a fixed set of behaviour, in 21 places in 8 files (hasOwnedChildren in the keyboard handlers, merge, nest, update, block info, the exporter and the validator). A block could only have all of that behaviour or none of it, and the behaviour could not depend on props or on view state (open or closed).

So the conclusion was: keyboard behaviour must be a separate, explicit setting on the block, and the structure must be a separate, explicit flag.

What changes

1. Keyboard settings on the block implementation

A block implementation has a keyboard option: only the settings that differ from the defaults, or a function of the block that returns them.

The schema fills in the defaults once. The spec then holds a function that returns every setting, so the handlers do not check for missing values. A setting given as undefined keeps its default.

Examples:

// Bullet list item
keyboard: { splitKeepsType: true, emptyEnterResets: true },

// Toggle list item: depends on view state
keyboard: (block) => {
  const open = isToggleOpen(block);
  return {
    splitKeepsType: true,
    emptyEnterResets: true,
    enter: open ? "into-children" : "split",
    emptyChildEnter: open ? "stay" : "outdent",
  };
},

// Callout with a title
keyboard: { enter: "into-children", childrenCanOutdent: false, emptyChildEnter: "exit-at-end" },

The central Enter and Backspace handlers read these settings and apply them in a fixed order. The order is documented on the BlockKeyboard type. meta.hardBreakShortcut is deprecated. It still works as the default for enter and shiftEnter.

2. container: true marks a container

A container (a block whose own node holds its child blocks, such as a column list) now declares container: true. It must have content: "none". The type and the validator enforce this.

children now has one meaning: which child blocks a block accepts. The default is { allow: "blocks" } for every block. Only a container can restrict the types or set a minimum count, because the children of other blocks share one untyped group.

{ type: "callout", content: "none", container: true }
{ type: "columnList", content: "none", container: true, children: { allow: ["column"], min: 2 } }

3. Exporters: the mapping decides where children go

A block mapping is a plain function (the exporter places the children, indented) or { withChildren } (the mapping receives the rendered children and places them). The shape of the mapping decides where the children go. The only container check left: a container with a plain mapping throws, so the error comes early.

4. Toggles

• The built-in toggles use createToggleFrame with renderFrame.
• The chevron has an accessible name and aria-expanded. The CSS also reads aria-expanded, so data-show-children is removed.
• A toggle heading changed to a regular heading with the keyboard shortcut, the markdown rule (## ) or the slash menu stops being a toggle. The block type menu already did this (fix: BlockTypeSelect item filtering based on schema #2112).

5. Block colors with frames

.bn-block carries the block's text and background color. The block container's node view and the internal HTML serializer set them. The 18 color rules in Block.css no longer look for the content as a direct child. Thus colors reach the children of any framed block, also custom ones, and the toggle-specific copies of these rules are removed.

Benefits

• Combinations that were not possible before:
  • A block with content whose keyboard behaviour depends on props or view state (a toggle heading, an open or closed toggle).
  • A block that sends Enter into its children but lets Shift-Tab move blocks out (a toggle), or keeps them in (a callout).
  • A block where Enter inserts a line break (a diagram), without a meta flag.
  • A custom framed block whose colors apply to its children.
• Less implicit behaviour: before, adding children to a block with content changed the keyboard, merge, nest, update and export behaviour in 21 places. Now each concern has its own explicit setting: container for structure, keyboard for keys, the mapping shape for export. Changing one does not change the others.
• Lists are first-class: the list Enter handling was a separate Enter shortcut in each list block (listItemEnterHandler.ts), plus an unused copy (ListItemKeyboardShortcuts.ts). Now list items declare splitKeepsType and emptyEnterResets, and the central handlers apply them in the same order as for every other block.
• Less toggle code: createToggleWrapper (197 lines) and the React ToggleWrapper (162 lines) are replaced by createToggleFrame (127 lines) for both toggles.

Issues

• Closes Hitting enter on a unfolded toggle block creates new toggle block #1875: Enter on an open toggle adds a block inside the toggle (BLO-929).
• Closes Enter Key Breaks Children in Custom Toggleable Blocks #2020: Enter no longer breaks a toggle's children (BLO-949).
• Closes Toggle block content is moved to next toggle block #2378: Enter on a closed toggle keeps its children in the toggle (BLO-998).
• Closes Cannot convert Toggle Heading to regular Heading — it remains collapsible #2124: the type menu part was fixed by fix: BlockTypeSelect item filtering based on schema #2112. The shortcut, markdown and slash menu paths are fixed here (BLO-959).
• Closes Collapsible list: unlabeled accessible button, decorative image #2811: the toggle button has an accessible name and state (BLO-1218). This overlaps with fix(core): give the toggle button an accessible name and state #3133.
• Closes Preserve block identity when editing from the block's start #550: editing at the start of a block keeps the block's identity.
  • Enter at the start of a block keeps the block's id, props and children.
  • Backspace below an empty block of the same type and props moves the block up into its place. The block keeps its id, props and children. Delete at the end of the empty block does the same.
  • Backspace below an empty block of another type (for example an empty heading) moves the text into that block, which keeps its id, type and props, as in Notion (feat: Update backspace handling in nested blocks (BLO-1326) #3124).

Also fixed:

• Backspace at the start of a paragraph after a code block with an indented child did nothing. It now joins the paragraph to that child.
• The core unit tests sometimes failed with "document is not defined". The placeholder extension changed the editor element's class outside ProseMirror, and ProseMirror read this change 20ms later, sometimes after the test environment was removed. The class is now set through ProseMirror's attributes prop. tiptap makes the same kind of change when it creates the view, so this makes the failure less frequent, but does not remove it.

New regression tests for fixes that had no test: #1672 (Shift-Enter keeps styles), #2566 (Backspace moves the caret to the last nested block), #605 (Backspace below an image deletes only the empty block).

Breaking changes

Compared with main:

• createToggleWrapper (core) and ToggleWrapper (React) are removed. Use renderFrame with createToggleFrame.
• The toggleable-blocks example is removed.
• Toggles no longer have data-show-children. Use .bn-toggle-button[aria-expanded].
• meta.hardBreakShortcut is deprecated. Use keyboard.enter and keyboard.shiftEnter.

Compared with #3059 (not released):

• A block with content cannot declare children restrictions. Use keyboard settings for the behaviour.
• A container must declare container: true.
• A container needs a { withChildren } exporter mapping.
• BlockInfo.hasOwnedChildren is removed.

Known gaps

• feat: Update backspace handling in nested blocks (BLO-1326) #3124 (merged in) makes every first child merge into a parent with inline content on Backspace. It replaces this PR's interim rule for "titled" blocks. Blocks with plain-text content never take merged text. So in a plain-text block with enter: "into-children", Backspace at the start of the first child un-nests it, or does nothing when childrenCanOutdent is false.
• The block colors need a node view on every block. If blocks without a frame stop getting a node view (review comment on Container blocks: compartments, renderFrame, repair, validation, exporters #3059), unframed blocks need the old direct-child color rules back.
• A toggle does not stay open when its last child is removed or moved out, and a block cannot be dropped into an empty toggle (BLO-956). Both are it.fails tests here, and feat(core): drop a block into a toggle (BLO-956) #3143 fixes them.
• In an empty toggle heading, the slash menu's "Heading 2" converts the block. Notion keeps the toggle heading and inserts a new heading below it.
• Improve delete key behavior near image blocks #1478 is reopened: Backspace at the start of text below an image still deletes the image.

TODO

• Decide the name of container: true before release. The flag means: the block has no content of its own, and its node holds only its child blocks. Candidates: container: true (today), layoutBlock: true, or frameOnly: true. frameOnly only fits if a container draws its box in renderFrame instead of render (today renderFrame is refused on containers), so decide both together.

Testing

After the merge of #3059 (which brings in main with #3124):

• Unit: the complete suite passes (core 1,038, tests 958, and every package).
• Browser (Docker, Chromium, Firefox and WebKit): the toggle, container, frame, block color, block identity, keyboard handler, multi-column, custom block and copy-and-paste suites pass. The only failures are the tests marked it.fails.
• Lint passes.

The commits split the work by topic for review. Only the complete PR is tested, so please squash on merge.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added configurable keyboard behavior for custom blocks, including how Enter and Shift+Enter work, how blocks split or reset, and whether child blocks can be outdented.
  • Toggle headings and list items now support expandable content, persistent open states, and improved keyboard editing.
  • Added localized labels for toggle controls across supported languages.
  • Export mappings can now incorporate rendered child blocks into a block’s output.

• Improvements

  • Custom container blocks use an explicit container setting, with updated guidance and examples.
  • Improved color rendering for nested blocks and HTML exports.

• Removals

  • Removed the toggleable-blocks example and the standalone ToggleWrapper component.