feat(figure): add image zoom functionality with multiple modes

[CybotTM]

Summary

Add :zoom: option to figure and image directives supporting four zoom modes:

• lightbox: Click to open full-size in modal dialog overlay
• gallery: Click to open with navigation between grouped images
• inline: Mouse wheel zoom directly on image with pan support
• lens: Magnifying lens follows cursor showing zoomed view

Usage

.. figure:: /images/screenshot.png
   :zoom: lightbox

   Click to enlarge this screenshot

.. figure:: /images/photo1.png
   :zoom: gallery
   :gallery: photos

   Part of the photos gallery

Features

• :zoom: option accepts lightbox | gallery | inline | lens
• :gallery: option groups images for gallery navigation
• :zoom-indicator: option to show/hide the zoom icon (default: show)
• Zoom indicator with appropriate cursor (zoom-in or crosshair)
• Tooltips on indicators ("Click to enlarge", "Scroll to zoom")
• Click/scroll events pass through indicator to underlying image
• Full keyboard accessibility for all zoom modes
• Respects prefers-reduced-motion media query
• Works with with-border and with-shadow styling classes

Technical Changes

• New FigureDirective.php extending SubDirective
• New image.html.twig template for standalone images with zoom
• JavaScript in image-zoom.js bundled into theme.min.js
• CSS in _component_image_zoom.scss imported into theme.scss
• Updated figure.html.twig with zoom data attributes

Test plan

• Verify lightbox mode opens dialog on click
• Verify gallery mode with navigation between grouped images
• Verify inline mode with scroll-to-zoom and drag-to-pan
• Verify lens mode with magnifying glass following cursor
• Verify keyboard navigation works for all modes
• Verify zoom indicator positioning with border/shadow classes
• Verify :zoom-indicator: false hides the indicator

[CybotTM]

Fixes Applied

Based on @linawolf's testing feedback, the following issues have been resolved:

🔧 Lightbox (was: "does nothing")

• Root cause: JS expected a pre-existing <dialog> element referenced by data-zoom-dialog attribute, but none was created
• Fix: Now creates the dialog dynamically when initializing lightbox triggers

🔧 Gallery (was: "opens empty")

• Root cause: JS looked for trigger.src but trigger is <figure> element (not <img>), so src was undefined
• Fix: Now finds the <img> child inside the figure and extracts src/caption from there

🔧 Lens (was: "looks wrong")

• Root cause: CSS expected .lens-zoom-container class but container was just <figure data-zoom="lens">
• Fix: JS now adds required class and positioning styles to the container

🔧 Inline

• Similar fix: adds required container class and overflow styles

✅ Additional Changes

• Added image.html.twig template to support :zoom: on standalone image directive (not just figure)
• Added render test examples for both figures and images with all zoom modes
• Rebuilt compiled assets (theme.css, theme.min.js)

Note: Changes from #1140 are now integrated into this PR.

[linawolf]

Happy to see you are working on this, please ping me when you require my review

[CybotTM]

Hi @linawolf, IMO it should be ready now for a review.

[josefglatz]

I just tested it as a non-a11y-expert. Really cool to see them accessible.

is it also possibel with actual RsT parser to have a automatic rendered thumbnail/image in the normal view and an original image in the lightbox?

[linawolf]

I added an integration test. In my eyes we can remove draft status

[CybotTM]

@josefglatz Good question! Currently the zoom modes use the same image source for both the inline view and the lightbox/gallery.

To support separate thumbnail/original images, we'd need to add a new directive option like :zoom-src: that specifies the full-size image to show in the lightbox:

.. figure:: /images/screenshot-thumbnail.png
   :zoom: lightbox
   :zoom-src: /images/screenshot-original.png
   :alt: Screenshot

   Click to see full resolution

This would be a nice enhancement for a follow-up PR. Would you like to create a feature request issue for it?

[CybotTM]

To clarify - there are two possible approaches:

1. Manual: :zoom-src: option where the user provides both thumbnail and original (as described above)

2. Automatic: The renderer generates thumbnails from the original image during build time

The automatic approach would be more user-friendly but requires image processing capabilities in the render pipeline (resizing, caching, output path management). This is likely out of scope for render-guides as it's primarily a documentation renderer, not an image processing tool.

For automatic thumbnails, this might be better handled at the infrastructure level (e.g., via a CDN/image service that serves resized versions on-the-fly) rather than in render-guides itself.

@linawolf what's your take on this?

[CybotTM]

oh, yes, tests, sorry, totally forgot about them 🤦
added some more now.

[linawolf]

I would suggest that we first get this PR merged and then deal with different images for preview and the zoom box itself in follow ups.

I am not very familiar with how the rendering pipeline actually works so I would be hesistant to change it unless someone really knows what they are doing. New features are nice, but it also means that we have more things we need to maintain and promise for the indefinate future. Also ppl actually using such features are usually quite a small group. So I would prefer a lowtech variant like :zoom-src: /images/screenshot-original.png In such a case we should also link the original picture so it is accessible without javascript

[linawolf]

Thanks a lot for these changes