New block: Figure block

[sarthaknagoshe2002]

Note

Please treat this PR as a baseline and a foundation. This is not meant to be the hard final version of the block. This PR is completely open to any additions, subtractions, or architectural pivots. The features included so far, the specific SVG icons used, the 5 chosen layout variations, and the block transformations are intended to demonstrate the block's technical capabilities and potential. Everything here is open for iteration, feedback, and discussion!

What?

Closes #78961

This PR introduces the new core/figure block: a native, semantic container for self-contained content (images, code, tables, composite media) with an optional caption. It features an initial setup state & block transforms.

Why?

Currently, Gutenberg lacks a proper, semantic <figure> wrapper for composite content. When authors want to pair a chart with a raw data table, or show "Before & After" images side-by-side with a single shared caption, they are forced to hack together core/columns or core/group blocks.

This PR solves that by providing a dedicated core/figure block that guides users into building perfectly structured, WCAG-compliant media layouts.

How?

• Implemented a 2-step onboarding flow (Choose Layout, Start Blank).
• Registered 5 semantic variations via variations.js (Before & After, Data Set, Code & Console, Multimedia Hub, Document Resource) using deep innerBlocks template arrays.
• Added transforms to handle multi-block wrapping. If an user transforms a quote into a Figure, the citation is extracted and hoisted directly into the <figcaption>.
• Implemented toolbar controls to toggle the caption position (Top/Bottom). Built a MutationObserver to actively track the physical presence of the <figcaption> in the DOM, ensuring the position toggle is intelligently disabled when the caption is turned off.

Testing Instructions

1. Open a post or page in the editor.
2. Insert a Figure block via the block inserter.
3. Enable the caption, and verify the "Move caption to top/bottom" toolbar icon becomes active.
4. Disable the caption. Verify the MutationObserver successfully detects the missing DOM node and disables the position toggle in the toolbar.
5. Toggle the caption position to "Top", and inspect the DOM to verify the physical <figcaption> node moves to match the visual order.
6. Insert an Image block followed by a Paragraph block outside of the Figure.
7. Multi-select both of them, click the block icon in the toolbar, and transform them into a Figure.
8. Add a core/quote block, insert a citation, transform to Figure block & verify the citation is hoisted into the Figure caption.

Screenshots or screencast

Figure.block.mov

Use of AI Tools

Used AI for test suits & research.

[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: New Block, [Package] Block library.

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: sarthaknagoshe2002 <sarthaknagoshe2002@git.wordpress.org>
Co-authored-by: hanneslsm <hanneslsm@git.wordpress.org>
Co-authored-by: prasadkarmalkar <prasadkarmalkar@git.wordpress.org>
Co-authored-by: peroyomas <atoon@git.wordpress.org>

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