Research: Aurora listing block variations and block add-on anatomy

[MrTango]

Part of #23

Question

In plone/aurora (alpha): how does an add-on register a variation/template of the stock listing block (the equivalent of Volto's variations on blocksConfig — does that mechanism exist yet in Aurora, and how stable is it)? What is the full anatomy of a third-party block add-on npm package (install(config), blockSchema conventions, lazy view/edit components)? How does Aurora render responsive images today vs. planned? And how would a gallery block schema express an object-browser multi-image picker in Aurora's schema system?

Findings captured on branch research/aurora-listing-variation.

[MrTango]

Resolution (researched against plone/aurora@ffaab61, main, 2026-08-20):

1. Listing variations: Aurora does NOT support Volto-style block variations today. BlockConfigBase.variations still exists in @plone/types (packages/types/src/config/Blocks.d.ts:142) but no runtime code outside the legacy packages/volto reads it; there is no variation chooser in cmsui. The listing block (packages/blocks/Listing/ListingBlockView.tsx) hardcodes data.variation === 'summary' vs default. The block is provisional: introduced Jan 2026, reverted/reapplied, being rewritten in open PR listing block aurora#107 (edit component + ListingSchema + QuerystringWidget, still no variation field); issue [CMSUI Blocks] - Listing aurora#40 calls for a refactor. Only extension path today: override config.blocks.blocksConfig.listing wholesale from an add-on, or ship an own gallery block.

2. Add-on anatomy: npm package, main: index.ts (no src/), default-exporting install(config: ConfigType) => config (@plone/registry loader enforces the return). Declared via the app's registry.config.ts addons array or package.json addons key; loaded by PloneRegistryVitePlugin into .plone/registry.loader.js; optional config/server.ts gives a server-only loader (place for a rootContentSubRequest data-loading utility like the listing block's querystringSearch). blocksConfig entry: { id, title, icon, category, view/edit as React.lazy, blockSchema (drives the sidebar form), defaultBlockWidth, restricted }. plateBlocksConfig only concerns Plate-native element types (p, h2, img, ...) — irrelevant for a registry gallery block.

3. Responsive images: the shared Image component (packages/layout/components/Image/Image.tsx) renders a plain <img> with srcset generated from image_scales (all scales sorted by width, + original when site allows more sizes), width/height, lazy/decoding handling; no <picture>; sizes is explicitly the caller's job (docs/development/images.md). No further 'final version' pipeline exists — this is the documented mechanism. (ListingBlockView currently bypasses it and hand-builds a thumb URL.)

4. Multi-image picker: cmsui's ObjectBrowserWidget is registered for widget: 'object_browser' and supports mode: 'multiple' | 'single' with multiple as default, plus selectedItemAttrs (include image_field, image_scales) and widgetOptions.pattern_options.{selectableTypes, maximumSelectionSize} — all expressible directly as schema property keys, since the settings form spreads schema properties onto the widget.

Full findings with file-level citations: docs/research/aurora-listing-variation.md on local branch research/aurora-listing-variation (not pushed).