[FEATURE] Modernize float classes to Bootstrap 5 with deprecation handling by CybotTM · Pull Request #1179 · TYPO3-Documentation/render-guides

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

Summary

Builds on #1174 (merged). Modernizes legacy float CSS classes to Bootstrap 5 logical properties with backward-compatible deprecation handling.

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.

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

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

Resolves: #1172 ## Summary - Add missing `float: left`/`float: right` CSS properties to `img.float-left`/`img.float-right` rules (Bootstrap 5 removed these) - Add figure float rules (`figure.float-left`, `figure.float-right`) with `max-width: 50%` and responsive breakpoint (<576px disables float) - Add `img.align-center` / `figure.align-center` CSS for centered alignment - Replace deprecated HTML `align` attribute in `image.html.twig` with CSS class mapping (`:align: left` → `float-left`, `:align: right` → `float-right`, `:align: center` → `align-center`) - Add `:align:` CSS class support in `figure.html.twig` - Preserve `:align:` option on FigureNode (was being stripped) so `.. figure:: :align: left` works - Strip `float-left`/`float-right` from inner `<img>` inside `<figure>` to prevent caption wrapping issues - Add `.clear-both` CSS utility alias (alongside existing `.cc`) - Split `ImagesAndFigures` rendertest into separate pages: Index (styling), Zoom, FloatAndAlignment ## Files changed | File | Change | |------|--------| | `assets/sass/components/_rst.scss` | Add `float` property + `align-center` to img rules | | `assets/sass/components/_images.scss` | Add figure float/align rules + responsive | | `assets/sass/_utilities.scss` | Add `.clear-both` alias | | `resources/template/body/image.html.twig` | Replace HTML `align` attr with CSS classes | | `resources/template/body/figure.html.twig` | Add `:align:` CSS class support | | `src/Directives/FigureDirective.php` | Keep `:align:` on FigureNode, strip float from inner img | | `resources/public/css/theme.css` | Regenerated | | `Documentation-rendertest/ImagesAndFigures/` | Split into Index + Zoom + FloatAndAlignment | ## Test plan - [x] All 195 PHPUnit tests pass - [x] PHPStan reports 0 errors - [x] Rendered docs verified: image/figure float left/right with text wrapping - [x] `:align: left`/`:align: right` on figures works correctly - [x] `.clear-both` clears floats as expected - [x] Responsive: floats disable on small screens (<576px) - [x] Visual review of rendered ImagesAndFigures pages ### Related - Follow-up PR: #1179 (modernize to `float-start`/`float-end`) - Upstream issue: [phpDocumentor/guides#1303](phpDocumentor/guides#1303) — proposes removing `final` from upstream directives to avoid forking

linawolf · 2026-03-01T13:54:24Z

@CybotTM it seems like we have conflicts now

CybotTM · 2026-03-01T14:19:34Z

rebased

- 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 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

Merged

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

Closed

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 2 times, most recently from 1c51cde to 301f6b1 Compare February 22, 2026 15:02

CybotTM changed the title ~~feat: modernize float classes to Bootstrap 5 with deprecation handling~~ [FEATURE] Modernize float classes to Bootstrap 5 with deprecation handling Mar 1, 2026

CybotTM force-pushed the refactor/modernize-float-classes branch from 301f6b1 to a403c91 Compare March 1, 2026 14:17

CybotTM added 2 commits March 9, 2026 01:24

CybotTM added 3 commits March 9, 2026 01:24

[TASK] Add unit tests for float class rewriting directives

ba580a5

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 a403c91 to ba580a5 Compare March 9, 2026 00:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[FEATURE] Modernize float classes to Bootstrap 5 with deprecation handling#1179

[FEATURE] Modernize float classes to Bootstrap 5 with deprecation handling#1179
CybotTM wants to merge 5 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!

linawolf commented Mar 1, 2026

Uh oh!

CybotTM commented Mar 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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!

linawolf commented Mar 1, 2026

Uh oh!

CybotTM commented Mar 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

CybotTM commented Feb 17, 2026 •

edited

Loading

CybotTM commented Feb 22, 2026 •

edited

Loading