Opt-in composite figures: a figure div is one figure of ordered panels

[dereuromark]

Composite figures, as an opt-in extension.

Upstream djot has no composite figure. The open discussion is jgm/djot#31, where the objection to the ^ caption syntax this library already ships (jgm/djot#37) was that it cannot spell a subfigure: "Figure 1a", "Figure 1b", one caption over the whole plate. This adds that, without new syntax and without touching the parser.

A bare ::: figure div becomes one figure of ordered panels:

{#fig-x .columns-2}
::: figure
![one](a.png)
^ (a) One

![two](b.png)
^ (b) Two
:::
^ Group caption

<figure class="figure-group columns-2" id="fig-x">
<div class="figure-panels">
<figure class="figure-panel">
<img alt="one" src="a.png"><figcaption>(a) One</figcaption>
</figure>
<figure class="figure-panel">
<img alt="two" src="b.png"><figcaption>(b) Two</figcaption>
</figure>
</div>
<figcaption>Group caption</figcaption>
</figure>

Why no parser change

Both halves already parse: ::: figure is a div with class figure, and a ^ line that cannot attach to anything is a paragraph whose first inline is Text("^ ..."). So FigureGroupExtension implements BeforeRenderExtensionInterface and rewrites the tree once, before rendering.

That is also why there are no renderer changes in this diff. beforeRender runs on the single render() path, so Markdown, plain text and ANSI degrade for free through the Figure, Div and Caption arms they already have.

Rules

• Panels are the children this library already makes captionable: image and blockquote Figure nodes are promoted in place, a Table is wrapped in a panel figure and keeps its own <caption>.
• Stray content stays put. A note between two panels renders where it was written, inside the panels container; it is simply not a panel.
• The group caption is the caret paragraph immediately after the closer. Escaping it (\^ ...) leaves an ordinary paragraph. That works because an escaped caret parses as EscapedText, a sibling of Text, not a subclass, so the check is sound rather than accidental.
• Groups do not nest. A figure div inside an open group stays a plain div.
• Opt-in. Without the extension a figure div still renders <div class="figure">; there is a test for exactly that.

The four class names (figure, figure-group, figure-panels, figure-panel) are constructor options.

Deliberately out of scope

• Numbering. The panel letters and the group number are what make subfigures useful in prose, and this library has no figure numbering at all to hook into. Nothing here fakes one.
• Short and long captions. The other half of the Figures jgm/djot#31 objection, and a separate decision (see Captions jgm/djot#28).
• Code and math panels. Only images, blockquotes and tables are captionable here today, so only those can be panels. Widening that is a core caption question, not an extension one.
• HtmlToDjot round trip.

Noted while working, not fixed here

PlainTextRenderer has no Figure arm, so a captioned image already renders as aPanel caption, the alt text glued to the caption. That predates this branch (reproduces on master with a plain captioned image) and the new test pins the current behavior rather than papering over it. Worth its own fix.

[codecov]

Codecov Report

❌ Patch coverage is 98.38710% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 92.49%. Comparing base (b9c8bac) to head (2e1d021).

Files with missing lines	Patch %	Lines
src/Extension/FigureGroupExtension.php	98.38%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #270      +/-   ##
============================================
+ Coverage     92.42%   92.49%   +0.07%     
- Complexity     3683     3708      +25     
============================================
  Files           109      110       +1     
  Lines         10439    10501      +62     
============================================
+ Hits           9648     9713      +65     
+ Misses          791      788       -3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[dereuromark]

Ordering note: #271 fixes the plain-text gap this PR's degradation test currently pins (PlainTextRenderer has no Figure or Caption arm, so a captioned image renders as aPanel caption - a bug that predates this branch). Once 271 lands I will rebase this branch and update the assertion to the fixed output.

[dereuromark]

Rebased onto master (b9c8bac). The degradation test asserted the pre-php-collective/djot-php#271 plain-text output (aPanel captionGroup caption); with that fix in, a composite figure now degrades to

a
Panel caption
Group caption

which is the point of #271. Assertion updated to the fixed output, nothing else changed. Full suite, phpstan and phpcs green on the rebased commit.