[META] Production-ready ComponentSource plugins (#3520484) · Issues · project / canvas

[META] Production-ready ComponentSource plugins

>>> [!note] Migrated issue   Reported by: [wim leers](https://www.drupal.org/user/99777) >>> <h3 id="overview">Overview</h3> XB was originally developed with support SDCs, exclusively. Then in November 2024, we added support for block plugins (in <a href="https://www.drupal.org/project/experience_builder/issues/3475584" title="Status: Closed (fixed)">#3475584: Add support for Blocks as Components</a>) and introduced the <q><code>ComponentSource</code> plugin</q> concept. The problem: <ul> <li><code>ComponentSourceInterface</code> and surrounding infrastructure was built (and evolved) on an as-needed basis, not always with an eye towards making this a public API</li> <li>hence test coverage is partial at best</li> <li>there have been many <code>ComponentSource</code>-specific bugs for aspects/edge cases other component source plugins already fixed</li> <li>combined, this means it's hard to be confident about the production-readiness: robustness, edge case handling, etc.</li> </ul> We know there's both known technical debt, and more features that we'll eventually need to support: <ol> <li>debt: the explicit input schema must be able to evolve, and each <code>ComponentSource</code> may have different needs for that. For example: block plugins may change their settings (and their config schema), SDCs may gain new optional inputs, JS components may gain new required inputs </li><li>debt: we know we'll need to support implicit inputs (e.g. block plugins can declare required + optional "contexts" that allow block plugins behave differently not only to component instance author's explicit wishes ("explicit inputs"), but also based on the component developer's logic ("implicit inputs") </li><li>feature: asymmetric translation will need some explicit inputs to be locked, because some explicit inputs may be considered to be not translatable — for example an image input of some component </li></ol> Note: All <code>ComponentSource</code>s targeted for XB 1.0-beta1 (<a href="https://git.drupalcode.org/project/canvas/-/work_items/3515932" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3515932</a>): <ol> <li><code>sdc</code> → <code>\Drupal\experience_builder\Plugin\ExperienceBuilder\ComponentSource\SingleDirectoryComponent</code></li> <li><code>block</code> → <code>\Drupal\experience_builder\Plugin\ExperienceBuilder\ComponentSource\BlockComponent</code></li> <li><code>js</code> → <code>\Drupal\experience_builder\Plugin\ExperienceBuilder\ComponentSource\JsComponent</code></li> <li><code>_name tbd_</code> → stabilizing this highly experimental component source is out of scope for this meta, that has its own issue: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3519737" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3519737</a></li> </ol> <h2 id="beta">Beta blockers (July 2025)</h2> Beta blockers (tag: <code>beta blocker</code>) MUST happen before <a href="https://git.drupalcode.org/project/canvas/-/work_items/3515932" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3515932</a>. (Numbered lists must happen one after the other, bulleted lists can happen in parallel.) <ol> <li>✅ Test coverage to gain baseline confidence, and establish equivalent test coverage for all component sources, powered by a new <code>ComponentSourceTestBase</code>: <ol> <li>✅ <a href="https://www.drupal.org/project/experience_builder/issues/3501290" title="Status: Closed (fixed)">#3501290: Introduce unit test coverage for both ComponentSource plugins (Block + SDC)</a> </li><li> <ul> <li>✅ <a href="https://www.drupal.org/project/experience_builder/issues/3518835" title="Status: Closed (fixed)">#3518835: Move components/sdc_statuses/* SDCs into `xb_test_sdc` module</a> </li><li>✅ <a href="https://www.drupal.org/project/experience_builder/issues/3518838" title="Status: Closed (fixed)">#3518838: ComponentSource robustness: add `ComponentSourceTestBase::testSettings()`</a> </li><li>✅ <a href="https://www.drupal.org/project/experience_builder/issues/3518833" title="Status: Closed (outdated)">#3518833: [PP-2] Update JsComponentTest to subclass ComponentSourceTestBase for consistent test coverage</a> </li><li>✅ <a href="https://www.drupal.org/project/experience_builder/issues/3518832" title="Status: Closed (fixed)">#3518832: ComponentSource robustness: add `ComponentSourceTestBase::testGetClientSideInfo()`</a> </li></ul> </li> </ol> </li> <li>Incomplete functionality (due to demo-driven development) — which must ALWAYS expand a <code>ComponentSourceTestBase</code>-powered test: <ol> <li>✅ Discovery of components in a source, and only allowing the ones we know will work reliably: <ul> <li>✅ <code>block</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3520617" title="Status: Closed (fixed)">#3520617: BlockComponent::checkRequirements() should disallow any block plugins whose definition declares it requires certain contexts</a> </li><li>✅ <code>sdc,js</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3508725" title="Status: Closed (fixed)">#3508725: ComponentMetadataRequirementsChecker::check() should validate that the example(s) actually match the JSON schema</a> </li><li>✅ ALL sources: <a href="https://www.drupal.org/project/experience_builder/issues/3519168" title="Status: Closed (fixed)">#3519168: Handle components provided by ComponentSources EXPLICITLY disappearing — enables deleting JS components that are in use</a> </li><li>✅ <code>block</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3484682" title="Status: Closed (fixed)">#3484682: Handle update and delete of Block `Component`s, plus react to dependency removal</a> </li><li>✅ <code>sdc</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3522164" title="Status: Closed (duplicate)">#3522164: Handle update and delete of SingleDirectoryComponent `Component`s, plus missing config dependencies</a> </li><li>✅ <code>sdc</code><a href="https://www.drupal.org/project/experience_builder/issues/3523625" title="Status: Closed (fixed)">#3523625: ComponentMetadataRequirementsChecker::check() should validate no prop is of `type: object` without a proper `$ref`</a> </li><li>✅ <code>sdc,js</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3503087" title="Status: Closed (fixed)">#3503087: Disallow SDCs with `type: string, enum: …` with an empty string listed to convey optionality: the prop should then just be optional</a> </li></ul> </li> <li>Correct rendering of components in a source: <ul> <li>✅ <code>js</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3521072" title="Status: Closed (fixed)">#3521072: Auto-saved Javascript Components CSS changes do not work with CSS aggregation</a> </li><li>✅ <code>sdc,js</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3522673" title="Status: Closed (fixed)">#3522673: Previews of SDCs with default image props broken</a> </li><li>✅ <code>js</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3508937" title="Status: Closed (fixed)">#3508937: Global AssetLibrary should render with its auto-saved state (if any) when rendered in the XB UI</a></li> <li>✅ <code>block</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3518722" title="Status: Closed (fixed)">#3518722: Test coverage to prove that BlockPluginInterface cacheability is correct when rendered via XB</a> </li><li>✅ <code>js</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3522217" title="Status: Closed (fixed)">#3522217: JsComponent-sourced rendered component instances lack cacheability of underlying config entities (+ first-party imports + auto-save tag when previewing)</a> </li><li>✅ ALL sources: <a href="https://www.drupal.org/project/experience_builder/issues/3521128" title="Status: Closed (fixed)">#3521128: Ensure XB works with CSS + JS aggregation, including for (auto-saved) code components</a> </li><li>✅ <code>sdc</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3499352" title="Status: Closed (fixed)">#3499352: SDCs should only have get HTML comments injected when `renderComponent(isPreview: TRUE)`</a> </li><li>✅ <code>js</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3525374" title="Status: Closed (fixed)">#3525374: Include compiled CSS from global asset library when displaying component library preview thumbnails</a> </li><li>✅ <code>sdc</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3526967" title="Status: Closed (fixed)">#3526967: Disabled SDC components are re-enabled after cache rebuild</a> </li><li><code>block</code>: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3502371" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3502371</a> </li></ul> </li> <li>🟢 Source's explicit inputs: <ul> <li>✅ <code>sdc,js</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3521444" title="Status: Closed (fixed)">#3521444: Required image field becomes non-functional after publishing with empty field</a> </li><li><code>sdc,js</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3516602" title="Status: Closed (fixed)">#3516602: SDC `enum` props should have human-readable labels: use `meta:enum`</a> </li></ul> </li> <li>✅ Other <ul> <li>✅ ALL sources: <a href="https://www.drupal.org/project/experience_builder/issues/3502982" title="Status: Closed (fixed)">#3502982: Rename ComponentSource settings' `plugin_id` to `local_source_id` or similar to not bias towards source plugins that don't use plugins under the hood</a> </li><li>✅ <code>js</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3521843" title="Status: Closed (duplicate)">#3521843: JS component slots and props don't appear in the preview canvas until published</a> </li><li>✅ <code>js</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3516390" title="Status: Closed (fixed)">#3516390: Compile Tailwind CSS globally for code components</a></li> </ul> </li> </ol> <h2 id="stable">Stable <code>ComponentSource</code> plugin API blockers (date: TBD)</h2> Stable blockers (tag: <code>stable blocker</code>) do not block <a href="https://git.drupalcode.org/project/canvas/-/work_items/3515932" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3515932</a>, but would be nice-to-have at that point in time. <del>They MUST happen before <a href="https://git.drupalcode.org/project/canvas/-/work_items/3517885" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3517885</a>.</del> This is for after <a href="https://git.drupalcode.org/project/canvas/-/work_items/3517885" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3517885</a>. To prevent contrib disruption prior to this being done: <a href="https://www.drupal.org/project/canvas/issues/3546903" title="Status: Closed (fixed)">#3546903: Disallow using any ComponentSource other than SDC/JS/Block unless `canvas_dev_mode` is installed</a>. <ul> <li>✅ <code>sdc,js</code>: <a href="https://www.drupal.org/project/canvas/issues/3544756" title="Status: Closed (fixed)">#3544756: ComponentInstanceForm displays default value in the component form when value is empty.</a> </li><li><code>sdc,js</code>: <a href="https://www.drupal.org/project/canvas/issues/3532414" title="Status: Active">#3532414: Follow-up for #3500386: tighten `::collapse()` to improve data integrity, because new props added to auto-saved code components cannot have a widget anyway</a> </li><li><a href="https://www.drupal.org/project/canvas/issues/3526045" title="Status: Active">#3526045: Settle on final name for `ComponentSource` plugins (`ComponentType`?) + expand their scope (discovery, maybe more?)</a> </li><li><code>sdc,js</code>: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3503038" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3503038</a>, which will unblock <ul> <li><code>sdc,js</code>: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3513589" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3513589</a></li></ul> </li> <li><code>js</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3526520" title="Status: Closed (outdated)">#3526520: JavascriptComponentStorage::createOrUpdateComponentEntity should not create component entities during config sync</a> </li><li><code>sdc,js</code>: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3513562" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3513562</a></li> <li>ALL sources: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3492358" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3492358</a> </li><li>✅ ALL sources: <a href="https://www.drupal.org/project/experience_builder/issues/3523496" title="Status: Closed (fixed)">#3523496: Block component instance form values not processed by validation/submit handlers</a> </li><li>✅ <code>block</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3518325" title="Status: Closed (fixed)">#3518325: [11.2-only] BlockComponent::checkRequirements() requires block settings to be fully validatable, but XB pretended for demo purposes Views blocks are … now: error!</a> 🛑 core blockers: <ul> <li>✅ <a href="https://www.drupal.org/project/drupal/issues/3520944" title="Status: Closed (fixed)">#3520944: Make menu blocks (block.settings.system_menu_block:*) fully validatable</a> </li><li>✅ <a href="https://www.drupal.org/project/drupal/issues/3520946" title="Status: Closed (fixed)">#3520946: Make View blocks (block.settings.view_block:*) fully validatable</a> </li></ul> </li> <li>🪦 <del><code>block</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3484669" title="Status: Closed (outdated)">#3484669: Define how block settings should be presented in the UI</a></del></li> <li>🪦 <del><code>block</code>: <a href="https://www.drupal.org/project/experience_builder/issues/3509265" title="Status: Closed (outdated)">#3509265: Auto-saving of blocks needs to handle string-to-bool fixing</a></del> </li><li><code>block</code>: <a href="https://www.drupal.org/project/canvas/issues/3526118" title="Status: Postponed (maintainer needs more info)">#3526118: CSS assuming block-plugin-rendered-in-a-wrapper-for-the-block-config-entity does not apply to XB: either A) stay the course, B) simulate the same markup structure</a> </li><li><code>block</code>: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3518656" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3518656</a> </li><li><code>block</code>: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3500795" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3500795</a> </li><li>✅ ALL sources: <a href="https://www.drupal.org/project/experience_builder/issues/3473761" title="Status: Closed (fixed)">#3473761: Render a placeholder DIV inside empty Regions/Slots in the preview</a> </li><li>ALL sources: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3518250" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3518250</a> </li><li>Implicit inputs: make <code>BlockComponent</code> support block plugins' required and optional contexts <ol> <li><a href="https://git.drupalcode.org/project/canvas/-/work_items/3485502" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3485502</a> </li> </ol> </li> <li><a href="https://git.drupalcode.org/project/canvas/-/work_items/3513590" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3513590</a> </li><li><code>sdc,js</code>: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3492366" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3492366</a> </li><li><code>block</code>: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3497990" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3497990</a> </li><li><code>sdc</code>: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3470422" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3470422</a> </li><li><code>sdc</code>: <a href="https://www.drupal.org/project/canvas/issues/3546208" title="Status: Active">#3546208: [Needs design] Updating the `group` key in SDC's *.component.yml does not update it in Canvas editor (even after cache clear)</a> </li><li><code>sdc</code>: <a href="https://www.drupal.org/project/canvas/issues/3546209" title="Status: Active">#3546209: Support `replaces`: 2 SDCs with one replacing the other — Canvas creates `Component`s for both</a> </li> <li id="explicit-input-schema-change-strategies">Explicit input schema change strategies:: now has its own meta: <a href="https://www.drupal.org/project/canvas/issues/3524751" title="Status: Postponed">#3524751: [later phase] Component Source plugins: generalized support for schema changes of explicit inputs</a>.</li> <li>ALL sources: <a href="https://www.drupal.org/project/canvas/issues/3525691" title="Status: Needs work">#3525691: Rename ComponentSourceInterface's singular method names to plural</a> </li><li><code>block</code>: <a href="https://www.drupal.org/project/canvas/issues/3524399" title="Status: Needs work">#3524399: `BlockComponent::validateComponentInput()` allows garbage to pile up</a> </li><li>✅ <code>sdc,js</code>: <a href="https://www.drupal.org/project/canvas/issues/3524401" title="Status: Closed (fixed)">#3524401: `GeneratedFieldExplicitInputUxComponentSourceBase::validateComponentInput()` allows garbage to pile up</a> </li><li><code>block</code>: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3504925" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3504925</a> </li><li><code>sdc</code>: <a href="https://www.drupal.org/project/canvas/issues/3532514" title="Status: Closed (fixed)">#3532514: Gracefully handle components in active development: ensure great DX</a> </li><li><code>js</code>: <a href="https://www.drupal.org/project/canvas/issues/3540082" title="Status: Needs work">#3540082: JavaScriptComponent::getComponentUrl() gets calculated twice on render for each component</a> </li><li><code>block</code>: <a href="https://www.drupal.org/project/canvas/issues/3541125" title="Status: Active">#3541125: Integer BlockComponent inputs (i.e. block settings) are incorrectly saved as strings</a> </li><li><code>block</code>: <a href="https://www.drupal.org/project/canvas/issues/3549793" title="Status: Active">#3549793: ComponentInstanceForm fails to load for block components without any config</a> </li><li><code>block</code>: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3502376" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3502376</a> </li><li><code>block</code>: <a href="https://www.drupal.org/project/canvas/issues/3542194" title="Status: Closed (duplicate)">#3542194: 500 error when using Test Block Components</a> </li><li>✅ <code>block</code>: <a href="https://www.drupal.org/project/canvas/issues/3542102" title="Status: Closed (fixed)">#3542102: Prevent publishing when `block` component instance values do not #validate</a> </li><li><code>sdc,js</code>: <a href="https://www.drupal.org/project/canvas/issues/3565718" title="Status: Closed (fixed)">#3565718: Validate `GeneratedFieldExplicitInputUxComponentSourceBase`-powered Component config entity props' `required` value matches the actual source for the `active` version</a></li> <li><code>sdc,js</code>: <a href="https://www.drupal.org/project/canvas/issues/3565755" title="Status: Active">#3565755: Changing a slot's metadata (title/examples) should not generate a new Component config entity version</a></li> <li>✅ <code>sdc,js</code>: <a href="https://www.drupal.org/project/canvas/issues/3550882" title="Status: Closed (fixed)">#3550882: Empty (optional) date prop throws error upon reload, due to bug in client-side transform</a></li> <li><code>sdc,js</code>: <a href="https://www.drupal.org/project/canvas/issues/3530808" title="Status: Needs work">#3530808: Example values for SDC props powered by datetime fields (in core, more in contrib) are not config schema-conformant because Canvas does not call `FieldItemListInterface::processDefaultValue()`</a></li> <li><code>block</code>: <a href="https://www.drupal.org/project/canvas/issues/3572850" title="Status: Postponed (maintainer needs more info)">#3572850: "block" ComponentSource plugin should never store inputs for `label` and `label_display`, because they're not available for Canvas users</a></li> <li>✅ <code>js</code>: <a href="https://www.drupal.org/project/canvas/issues/3574120" title="Status: Closed (fixed)">#3574120: Validate props for code components when rendering, like SDCs do</a></li> <li><code>sdc,js</code>: <a href="https://www.drupal.org/project/canvas/issues/3576578" title="Status: Closed (fixed)">#3576578: Inform SDC/code component developers of nonsensical `type: array` prop restrictions: `maxItems <2`</a> </li><li><a href="https://www.drupal.org/project/canvas/issues/3576805" title="Status: Active">#3576805: DX: reorganize test components: `canvas_test_sdc` should have its (intentionally invalid) SDCs moved to `canvas_test_sdc_invalid`</a> </li><li><code>block</code>: <a href="https://www.drupal.org/project/canvas/issues/3578142" title="Status: Closed (fixed)">#3578142: [upstream] New Views blocks are not available to be placed until cache clear</a> </li><li><code>block</code>: <a href="https://www.drupal.org/project/canvas/issues/3558721" title="Status: Active">#3558721: Regression: can no longer access previously stored values for block component instances</a> </li></ul> <h2 id="post-stable-priorities">Post-stable priorities (after achieving a stable PHP API)</h2> Post-stable priorities (tag: <code>post-stable priority</code>) do not block any release, and are things we'd like to see happen, but are intentionally NOT happening any time soon. We're highly confident that these will be net additions without the need for backwards compatibility breaks. <ul> <li><code>sdc,js</code>: <a href="https://git.drupalcode.org/project/canvas/-/work_items/3514672" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3514672</a> </li></ul> </li></ol> > Related issue: [Issue #3517941](https://www.drupal.org/node/3517941) > Related issue: [Issue #3520449](https://www.drupal.org/node/3520449) > Related issue: [Issue #3521002](https://www.drupal.org/node/3521002) > Related issue: [Issue #3521221](https://www.drupal.org/node/3521221)

issue