Block API: Declare block keyboard shortcuts on variations and transforms

[youknowriad]

What?

Lets blocks declare a keyboard shortcut on a variation or a block transform, and moves the handling into block-editor. Removes BlockKeyboardShortcuts from block-library.

Why?

That component hardcoded the Heading/Paragraph shortcuts, was exported as a private API, and had to be rendered by edit-post, edit-site, edit-widgets and customize-widgets. Third-party blocks had no way to contribute a shortcut.

How?

A shortcut object, shaped like registerShortcut:

shortcut: {
	name: 'core/block-editor/transform-heading-to-paragraph',
	description: __( 'Transform the selected heading into a paragraph.' ),
	keyCombination: { modifier: 'access', character: '0' },
	aliases: [ { modifier: 'access', character: '7' } ],
}

Heading's six level shortcuts now live on its h1–h6 variations; access+0/access+7 on its existing to: core/paragraph transform. A variation shortcut applies the variation's attributes in place when the block is already that type (skipped when isActive matches), and otherwise transforms first — which is what keeps access+2 working on a paragraph.

Notable behavior changes:

• Transforms run through switchToBlockType instead of hand-copying content + textAlign, so anchor and bindings/metadata are now preserved.
• The shortcuts appear in the help modal. They were registered under a block-library category that the modal never renders; they now use block. Descriptions are rewritten — the six levels previously shared one string.
• The key combination is only swallowed when the shortcut is relevant to the selection. Previously preventDefault() ran before the block-type check.
• Shortcuts are ignored unless the block's editing mode is default. This replaces edit-site's isEditMode gate.

Shortcut names are unchanged.

Testing Instructions

1. Select a paragraph, press Alt+Shift+2 (Ctrl+Alt+2 on macOS). It becomes an H2.
2. Press Alt+Shift+4. The level changes to H4.
3. Press it again. Nothing changes and the post is not marked dirty.
4. Press Alt+Shift+0 (or 7). It becomes a paragraph.
5. Repeat in the site editor, the widgets screen and the customizer.
6. Open the keyboard shortcuts help modal (Alt+Shift+H) and confirm the seven shortcuts are listed under "Block shortcuts".

Testing Instructions for Keyboard

The feature is keyboard-only; the steps above cover it.

Use of AI Tools

Authored with Claude Code (Opus 5), reviewed by me before opening.

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Required label: Any label starting with [Type].
• Labels found: .

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

[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: youknowriad <youknowriad@git.wordpress.org>
Co-authored-by: scruffian <scruffian@git.wordpress.org>

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

[github-actions]

Size Change: +357 B (0%)

Total Size: 7.72 MB

📦 View Changed

Filename	Size	Change
build/scripts/block-editor/index.min.js	461 kB	+642 B (+0.14%)
build/scripts/block-library/index.min.js	358 kB	-286 B (-0.08%)
build/scripts/blocks/index.min.js	45.5 kB	+158 B (+0.35%)
build/scripts/customize-widgets/index.min.js	14.9 kB	-25 B (-0.17%)
build/scripts/edit-post/index.min.js	52.9 kB	-41 B (-0.08%)
build/scripts/edit-site/index.min.js	335 kB	-57 B (-0.02%)
build/scripts/edit-widgets/index.min.js	22.6 kB	-34 B (-0.15%)

_{compressed-size-action}

[github-actions]

Flaky tests detected in 0fb93ab.
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/31794385370
📝 Reported tests:

Allow creating custom block templates in classic themes in /test/e2e/specs/editor/various/post-editor-template-mode.spec.js, passed after 1 failed attempt.

Error: apiRequestContext.fetch: socket hang up
Call log:
  - → GET http://localhost:8889/wp-json/wp/v2/templates
    - user-agent: Playwright/1.62.1 (x64; ubuntu 24.04) node/20.20 CI/1
    - accept: */*
    - accept-encoding: gzip,deflate,br
    - X-WP-Nonce: 3226b1b153
    - cookie: wordpress_test_cookie=WP%20Cookie%20check; wordpress_logged_in_23778236db82f19306f247e20a353a99=admin%7C1786878274%7CEl97woQKbkYn52X049svWYAPDUXaI8lBGiVC30ixiYq%7Cfd6108d216ba9a5500e73df5d472608e669628d5999d7f932dae7005de83e89a; wp-settings-time-1=1786706062; wp-settings-1=editor%3Dtinymce

    at RequestUtils.rest (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/request-utils/rest.ts:112:39)
    at RequestUtils.deleteAllTemplates (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/request-utils/templates.ts:35:31)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/post-editor-template-mode.spec.js:34:17

adds and activates a new tab when pressing Enter at the end of a tab label in /test/e2e/specs/editor/blocks/tabs.spec.js, passed after 1 failed attempt.

Error: expect(locator).toHaveCount(expected) failed

Locator:  locator('[name="editor-canvas"]').contentFrame().getByRole('tab')
Expected: 3
Received: 2
Timeout:  5000ms

Call log:
  - Expect "toHaveCount" with timeout 5000ms
  - waiting for locator('[name="editor-canvas"]').contentFrame().getByRole('tab')
    14 × locator resolved to 2 elements
       - unexpected value "2"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/tabs.spec.js:146:25

[scruffian]

I looks like we're reimplementing quite a lot of logic that already exists for block transformations. Can we reuse more of that?

[youknowriad]

The main goal is to actually reuse the transformations where previously we were duplicating its "transform" function. so I'm not really sure what part you think we're duplicating?

[scruffian]

Ok I looked more closely. I was assuming we had a more central place to handle transforms, but actually its mostly inside switchToBlockType, so I don't have that concern now.

This works great in my testing.

LGTM!

[mcsf]

1. No need to export, right?
2. I really dislike the naming here: slapping that "normalized" prefix feels like a cop-out. It's not really normalising, but wrapping the data so it can be more easily processed later. Have you considered augmenting instead of wrapping and calling it something like:

type EnhancedBlockShortcut = BlockShortcut & {
  targetBlockName: ...
  blockNames?: ...
  variationName?: ...
}

or even the more colourful

type BlockToBlockShort = BlockShort & { ...

[mcsf]

Misleading:

Suggested change

	name: `core/block-editor/transform-paragraph-to-heading-${ level }`,
	name: `core/block-editor/transform-to-heading-${ level }`,

[mcsf]

I wonder if a distinction is needed between:

• shortcuts that can transform any block to a variation V of block type T
• shortcuts that are only available when selected block is of type T to convert between V₁, V₂...

[mcsf]

Seems strange not to warn here.

[mcsf]

I thought of suggesting the name trigger here, but I realised it is intended to match registerShortcut.

[mcsf]

I find this comment confusing.

[mcsf]

Suggested change

	// A `to` transform can list several targets, but a shortcut can
	// only produce one. The first entry wins.
	// A `to` transform can list several targets, but a shortcut can
	// only produce one. The first target with a shortcut wins.

[mcsf]

Does this need to be exported?