feat: modernize float classes to Bootstrap 5 with deprecation handling

[CybotTM]

Summary

Modernizes Bootstrap float classes from v4 (float-left/float-right) to v5 (float-start/float-end) in the TYPO3 docs theme, with backward-compatible deprecation handling.

• Twig templates: Map RST :align: to Bootstrap 5 classes, with deduplication to prevent duplicate CSS classes
• FigureDirective: Detect and rewrite legacy :class: float-left/right, emit deprecation warnings, extract shared RewritesLegacyFloatClasses trait
• ImageDirective: Composition-based decorator wrapping upstream final class — intercepts legacy float classes without forking
• Integration tests: 18 assertions covering align, legacy rewrite, mixed classes, modern pass-through, and substitution images

Commits

1. refactor: modernize float classes to Bootstrap 5 naming — Twig dedup + cross-refs + SCSS deprecation comments
2. feat: detect and rewrite deprecated float classes in FigureDirective — FigureDirective + trait
3. feat: add ImageDirective decorator for float class deprecation — composition-based decorator
4. test: add integration tests for float class modernization — comprehensive test coverage

Key design decisions

• Composition over inheritance for ImageDirective: upstream class is final, so we wrap it via manual instantiation rather than Symfony ->decorate() (which caused PHP 8.1 issues with tagged service collections)
• Shared trait RewritesLegacyFloatClasses eliminates DRY violation between Figure and Image directives
• Twig class deduplication prevents float-start float-start when both :align: and rewritten :class: produce the same class

Upstream context

• Upstream PR: feat: modernize float classes to Bootstrap 5 with deprecation handling TYPO3-Documentation/render-guides#1179 (stacked on feat: add CSS float and alignment support for images and figures TYPO3-Documentation/render-guides#1174)
• Upstream issue: Allow themes to extend ImageDirective and FigureDirective (currently final) phpDocumentor/guides#1303

Test plan

• All 196 tests pass locally (PHP 8.5)
• CI green on PHP 8.1, 8.2, 8.3, 8.4
• Quality check passes
• Copilot review
• Gemini review

[gemini-code-assist]

Summary of Changes

Hello @CybotTM, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request modernizes the TYPO3 documentation theme by updating its handling of floating elements to align with Bootstrap 5's logical properties. It introduces a robust system for backward compatibility, automatically rewriting deprecated Bootstrap 4 float classes while providing clear warnings. The changes ensure that the documentation rendering remains consistent and adaptable to future web development practices, improving maintainability and user experience.

Highlights

• Bootstrap 5 Float Class Modernization: Migrated Bootstrap 4 float classes (float-left/float-right) to their Bootstrap 5 equivalents (float-start/float-end) across Twig templates and SCSS, ensuring compatibility with modern web standards and RTL language support.
• Backward-Compatible Deprecation Handling: Implemented logic within FigureDirective and a new ImageDirective decorator to detect and automatically rewrite legacy float classes, issuing deprecation warnings to guide users towards the new naming conventions.
• Architectural Improvements: Introduced a shared RewritesLegacyFloatClasses trait to centralize float class rewriting logic and utilized composition for the ImageDirective to extend functionality without modifying the upstream final class.
• Enhanced Styling and Responsiveness: Updated SCSS to define styles for both new and deprecated float classes for figures and images, including responsive adjustments to disable floating on small screens, and added align-center support.
• Comprehensive Integration Tests: Added a new suite of integration tests to cover various scenarios of image and figure floating and alignment, including legacy class rewriting, modern class usage, and mixed class combinations, ensuring robust behavior.

Changelog

• Documentation-rendertest/ImagesAndFigures/FloatAndAlignment.rst
  • Added a new reStructuredText file to demonstrate and test image and figure floating and alignment.
• Documentation-rendertest/ImagesAndFigures/Index.rst
  • Refactored the main index file by extracting zoom-related content into a dedicated file and adding a reference to the new float and alignment test file.
• Documentation-rendertest/ImagesAndFigures/Zoom.rst
  • Added a new reStructuredText file containing examples and documentation for image zoom functionalities, previously located in Index.rst.
• composer.json
  • Updated the friendsofphp/php-cs-fixer development dependency to version ^3.94.
• composer.lock
  • Updated the content hash and specific versions for friendsofphp/php-cs-fixer and other related development dependencies.
• packages/typo3-docs-theme/assets/sass/_utilities.scss
  • Extended the .cc CSS selector to also apply clear: both to the .clear-both class.
• packages/typo3-docs-theme/assets/sass/components/_images.scss
  • Implemented Bootstrap 5 float classes (float-start, float-end) for figure elements, added deprecation styles for float-left/float-right, and introduced responsive behavior to disable floats on small screens.
• packages/typo3-docs-theme/assets/sass/components/_rst.scss
  • Applied Bootstrap 5 float classes (float-start, float-end) and deprecation styles for float-left/float-right to img and object elements within RST content, including responsive adjustments. Also added align-center styling.
• packages/typo3-docs-theme/resources/config/typo3-docs-theme.php
  • Registered the new ImageDirective as a service.
• packages/typo3-docs-theme/resources/public/css/theme.css
  • Generated updated CSS reflecting the new float and alignment styles for figures and images, including responsive rules.
• packages/typo3-docs-theme/resources/template/body/figure.html.twig
  • Updated the Twig template to map RST :align: options to Bootstrap 5 float classes and prevent duplicate class assignments.
• packages/typo3-docs-theme/resources/template/body/image.html.twig
  • Modified the Twig template to map RST :align: options to Bootstrap 5 float classes, removed the align HTML attribute, and ensured class deduplication.
• packages/typo3-docs-theme/src/DependencyInjection/Typo3DocsThemeExtension.php
  • Updated the dependency injection configuration to remove the base ImageDirective in favor of the custom implementation, similar to how FigureDirective is handled.
• packages/typo3-docs-theme/src/Directives/FigureDirective.php
  • Enhanced the FigureDirective to include the RewritesLegacyFloatClasses trait, detect and rewrite deprecated float-left/float-right classes to float-start/float-end, and log deprecation warnings. It also strips float classes from the inner image.
• packages/typo3-docs-theme/src/Directives/ImageDirective.php
  • Added a new ImageDirective that decorates the upstream directive using composition to detect and rewrite legacy float-left/float-right classes for images, issuing deprecation warnings.
• packages/typo3-docs-theme/src/Directives/RewritesLegacyFloatClasses.php
  • Added a new trait to encapsulate common logic for identifying and transforming Bootstrap 4 float classes to their Bootstrap 5 equivalents.
• tests/Integration/tests/images/Float/expected/index.html
  • Added the expected HTML output for the new float and alignment integration tests.
• tests/Integration/tests/images/Float/expected/logs/warning.log
  • Added the expected log output, including deprecation warnings for legacy float classes, for the new integration tests.
• tests/Integration/tests/images/Float/input/guides.xml
  • Added the configuration file for the new float and alignment integration tests.
• tests/Integration/tests/images/Float/input/index.rst
  • Added the reStructuredText input file for the new float and alignment integration tests, covering various scenarios.

Activity

• The first commit, 'refactor: modernize float classes to Bootstrap 5 naming', focused on updating Twig templates for class deduplication, adjusting cross-references, and adding SCSS comments for deprecation.
• The second commit, 'feat: detect and rewrite deprecated float classes in FigureDirective', introduced the core logic for detecting and rewriting legacy float classes within the FigureDirective and extracted a reusable trait.
• The third commit, 'feat: add ImageDirective decorator for float class deprecation', implemented a decorator pattern for the ImageDirective to handle float class deprecation for images using composition.
• The final commit, 'test: add integration tests for float class modernization', added a comprehensive suite of integration tests to validate the new float class modernization and deprecation handling.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[Copilot]

Pull request overview

Modernizes float/alignment handling in the TYPO3 docs theme for Bootstrap 5 by mapping :align: to float-start/float-end and adding backward-compatible rewriting + warnings for legacy float-left/float-right usage across figures and images.

Changes:

• Add shared legacy-float rewrite logic, apply it to FigureDirective, and introduce a composition-based ImageDirective wrapper that rewrites legacy float classes and logs deprecations.
• Update Twig templates and theme styles (SCSS + compiled CSS) to use Bootstrap 5 float class names and support align-center, including class deduplication.
• Add an integration test fixture covering align mapping, legacy rewrite behavior, mixed classes, and deprecation warnings.

Reviewed changes

Copilot reviewed 18 out of 21 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/typo3-docs-theme/src/Directives/RewritesLegacyFloatClasses.php	New shared trait to detect/rewrite float-left/right to float-start/end.
packages/typo3-docs-theme/src/Directives/FigureDirective.php	Rewrites legacy float classes with warnings; shifts float behavior to the <figure> wrapper.
packages/typo3-docs-theme/src/Directives/ImageDirective.php	Wraps upstream final directive via composition to rewrite legacy float classes + warn.
packages/typo3-docs-theme/src/DependencyInjection/Typo3DocsThemeExtension.php	Removes upstream Figure/Image directive service definitions so theme directives take over.
packages/typo3-docs-theme/resources/template/body/figure.html.twig	Maps :align: to BS5 float classes and deduplicates CSS classes.
packages/typo3-docs-theme/resources/template/body/image.html.twig	Same :align: mapping/dedup; removes legacy HTML align attribute output.
packages/typo3-docs-theme/assets/sass/components/_images.scss	Adds BS5 float styling for figures + legacy class compatibility during migration.
packages/typo3-docs-theme/assets/sass/components/_rst.scss	Adds BS5 float styling and align-center for images/objects + responsive behavior.
packages/typo3-docs-theme/assets/sass/_utilities.scss	Adds .clear-both alias next to .cc.
packages/typo3-docs-theme/resources/public/css/theme.css	Compiled CSS updates corresponding to SCSS changes.
packages/typo3-docs-theme/resources/config/typo3-docs-theme.php	Registers the new ImageDirective service.
tests/Integration/tests/images/Float/**	New integration test fixture (input + expected HTML + expected warnings).
Documentation-rendertest/ImagesAndFigures/*.rst	Restructures rendertest docs and adds a dedicated float/alignment page using BS5 classes.
composer.json / composer.lock	Bumps friendsofphp/php-cs-fixer to ^3.94 and updates lockfile.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gemini-code-assist]

Code Review

This pull request is a well-executed modernization of Bootstrap float classes, complete with backward compatibility and deprecation warnings. The use of a shared trait for rewriting legacy classes and the composition-based decorator for the ImageDirective are excellent design choices that demonstrate a strong understanding of software engineering principles. The addition of comprehensive integration tests further enhances the quality of this contribution. My feedback includes a few suggestions to reduce code duplication in the SCSS and Twig templates, which should improve long-term maintainability.