feat: modernize float classes to Bootstrap 5 with deprecation handling by CybotTM · Pull Request #1179 · TYPO3-Documentation/render-guides

CybotTM · 2026-02-17T23:18:38Z

Stacked on #1174 — merge #1174 first, then this PR's diff will show only the modernization commits.

Summary

Modernize CSS float selectors to Bootstrap 5 logical properties (float-start/float-end), keeping backward-compatible aliases with grouped selectors to reduce duplication
Add Twig alignMap to translate RST :align: values to CSS classes, with deduplication to prevent duplicate classes when both :align: and :class: resolve to the same value
Detect and rewrite deprecated :class: float-left/:class: float-right in both FigureDirective and ImageDirective, emitting deprecation warnings
Extract shared RewritesLegacyFloatClasses trait for detection/rewrite logic (DRY)
ImageDirective uses composition (decorator pattern) instead of forking the upstream final class — zero code duplication, upstream changes are inherited automatically
Add responsive breakpoint for standalone images on small screens

Implementation notes

ImageDirective: Wraps the upstream final class via composition. Intercepts process() to rewrite float classes, then delegates to $this->inner->process(). No need to duplicate processNode() or resolveLinkTarget().
FigureDirective: Existing fork extended with float class detection. Uses array_filter/explode to strip float classes from the inner <img> while preserving non-float classes (e.g. with-shadow). A future PR will explore refactoring this to use decoration as well.
RewritesLegacyFloatClasses trait: Shared regex detection (hasLegacyFloatClass) and rewrite (rewriteLegacyFloatClasses) used by both directives.
Upstream issue for final removal: Allow themes to extend ImageDirective and FigureDirective (currently final) phpDocumentor/guides#1303

Test plan

Integration tests cover: align left/right/center, legacy float-left/right rewriting, mixed classes, simultaneous :align: + :class:, standalone images, modern float-start/float-end pass-through, substitution images
Deprecation warnings verified for all legacy class usages (7 warnings, no false positives for modern classes)
Unit tests: 40 tests covering RewritesLegacyFloatClasses trait, ImageDirective, and FigureDirective (100% patch coverage)

ineswillenbrock · 2026-02-17T23:42:40Z

Did you want to rewrite the deprecated float-left/right to float-start/end or just log their usage?

CybotTM · 2026-02-17T23:59:41Z

@ineswillenbrock

Did you want to rewrite the deprecated float-left/right to float-start/end or just log their usage?

Both.

CybotTM · 2026-02-18T11:06:30Z

yeah, finally, I think it is ready now.

ineswillenbrock · 2026-02-22T14:35:39Z

can you please add a test for the rewrite of the CSS class? I think that one got lost between #1174 and #1179

CybotTM · 2026-02-22T14:51:55Z

Hi @ineswillenbrock ,

can you please add a test for the rewrite of the CSS class? I think that one got lost between #1174 and #1179

Dunno what exact test you mean, but will have a look.

CybotTM · 2026-02-22T14:59:38Z

@ineswillenbrock,

oh, do you talk about e20a1b7 ?

This is not part of PR #1179 but #1174.
Or do you gonna drop #1174 and want to merge #1179 directly? Then I need to incorporate changes from #1174 also into #1179

The plan was #1174 needs to be merged first - this is the real float fix.

As stated in the #1179 description this PR depends on #1174.

Add missing float and alignment CSS for images and figures, replacing the deprecated HTML align attribute with CSS class mapping. - Add float-left/float-right CSS rules for img and figure elements with max-width: 50% and responsive breakpoint at 575.98px - Add align-center CSS for centered images and figures - Map :align: left/right/center to CSS classes in Twig templates, replacing the deprecated HTML align attribute on <img> - Preserve :align: option on FigureNode (was being stripped) - Strip float classes from inner <img> inside <figure> to prevent caption wrapping issues - Add .clear-both CSS utility alias alongside existing .cc - Split ImagesAndFigures rendertest into Index, Zoom, and FloatAndAlignment pages

Cover all float/alignment scenarios: - Figure :align: left/right/center maps to CSS classes - Image :align: left/right/center maps to CSS classes - Figure :class: float-left/right (float stripped from inner img) - Mixed :class: float-left with-shadow (extra classes preserved) - Image :class: float-right - Combined :align: + :class: (both applied to figure element)

- Map RST :align: left/right/center to Bootstrap 5 CSS classes (float-start, float-end, align-center) in Twig templates - Add class deduplication to prevent duplicate CSS classes when both :align: and :class: produce the same float class - Group modern and legacy float selectors in SCSS to reduce duplication - Add deprecation timeline comments to legacy CSS rules - Cross-reference comments between figure/image templates

- Extract RewritesLegacyFloatClasses trait for shared detection/rewrite logic - Detect :class: float-left/float-right and rewrite to float-start/float-end - Emit deprecation warning guiding authors to use :align: instead - Strip float classes from inner <img> using array_filter for clarity

- Wrap upstream final ImageDirective via composition pattern - Intercept :class: float-left/float-right, rewrite to float-start/float-end - Emit deprecation warning with substitution-image-aware message - Uses RewritesLegacyFloatClasses trait shared with FigureDirective - Register in DI config, remove upstream definition via compiler pass

- Test :align: left/right/center on figures and images - Test legacy :class: float-left/float-right rewriting on figures, images - Test mixed :class: with extra classes (e.g. with-shadow) - Test combined :align: + legacy :class: (deduplication) - Test modern float-start/float-end pass through without warnings - Test substitution image with legacy float class - Verify deprecation warnings with correct line numbers

Cover RewritesLegacyFloatClasses trait, ImageDirective decorator, and FigureDirective with 40 unit tests for 100% patch code coverage.

CybotTM · 2026-02-22T15:07:38Z

ok, I now added all stuff from #1174 also into this PR, dunno if this what you meant.

CybotTM marked this pull request as draft February 17, 2026 23:58

This was referenced Feb 18, 2026

Allow themes to extend ImageDirective and FigureDirective (currently final) phpDocumentor/guides#1303

Closed

feat: add CSS float and alignment support for images and figures #1174

Open

CybotTM force-pushed the refactor/modernize-float-classes branch 2 times, most recently from f70bc2c to c1c6b52 Compare February 18, 2026 07:09

CybotTM marked this pull request as ready for review February 18, 2026 07:19

CybotTM marked this pull request as draft February 18, 2026 08:27

CybotTM force-pushed the refactor/modernize-float-classes branch 2 times, most recently from f9da026 to 66a89af Compare February 18, 2026 09:34

CybotTM changed the title ~~[TASK] Modernize float classes to Bootstrap 5 float-start/float-end~~ feat: modernize float classes to Bootstrap 5 with deprecation handling Feb 18, 2026

CybotTM force-pushed the refactor/modernize-float-classes branch from 66a89af to f6ca36e Compare February 18, 2026 09:49

CybotTM mentioned this pull request Feb 18, 2026

feat: modernize float classes to Bootstrap 5 with deprecation handling netresearch/render-guides#4

Open

5 tasks

CybotTM force-pushed the refactor/modernize-float-classes branch from f6ca36e to 157a004 Compare February 18, 2026 10:28

CybotTM marked this pull request as ready for review February 18, 2026 11:06

CybotTM force-pushed the refactor/modernize-float-classes branch from 157a004 to 1c51cde Compare February 22, 2026 15:01

CybotTM added 7 commits February 22, 2026 16:02

[TASK] Add unit tests for float class rewriting directives

301f6b1

Cover RewritesLegacyFloatClasses trait, ImageDirective decorator, and FigureDirective with 40 unit tests for 100% patch code coverage.

CybotTM force-pushed the refactor/modernize-float-classes branch from 1c51cde to 301f6b1 Compare February 22, 2026 15:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

feat: modernize float classes to Bootstrap 5 with deprecation handling#1179

feat: modernize float classes to Bootstrap 5 with deprecation handling#1179
CybotTM wants to merge 7 commits intoTYPO3-Documentation:mainfrom
netresearch:refactor/modernize-float-classes

CybotTM commented Feb 17, 2026 •

edited

Loading

Uh oh!

ineswillenbrock commented Feb 17, 2026

Uh oh!

CybotTM commented Feb 17, 2026

Uh oh!

CybotTM commented Feb 18, 2026

Uh oh!

ineswillenbrock commented Feb 22, 2026

Uh oh!

CybotTM commented Feb 22, 2026

Uh oh!

CybotTM commented Feb 22, 2026 •

edited

Loading

Uh oh!

CybotTM commented Feb 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

CybotTM commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Implementation notes

Test plan

Uh oh!

ineswillenbrock commented Feb 17, 2026

Uh oh!

CybotTM commented Feb 17, 2026

Uh oh!

CybotTM commented Feb 18, 2026

Uh oh!

ineswillenbrock commented Feb 22, 2026

Uh oh!

CybotTM commented Feb 22, 2026

Uh oh!

CybotTM commented Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CybotTM commented Feb 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

CybotTM commented Feb 17, 2026 •

edited

Loading

CybotTM commented Feb 22, 2026 •

edited

Loading