Gracefully handle components in active development: ensure great DX (#3532514) · Issues · project / canvas

Gracefully handle components in active development: ensure great DX

>>> [!note] Migrated issue   Reported by: [heyyo](https://www.drupal.org/user/474388) Related to !196 !153 !223 !219 !205 !1299 >>> <h3 id="overview">Overview</h3> Follow-up for <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>. <pre>  /**    * Whether the logic powering this component is broken.    *    * Typical example: a developer is developing an SDC, and while developing is    * testing it in Canvas. They're even renaming the SDC. It'd be a terrible DX    * if this caused the associated Component config entity to switch to the    * fallback version.    *    * @see \Drupal\canvas\Entity\Component::getComponentSourcePluginId()    * @return bool    */   public function isBroken(): bool;</pre>… but there's more we could detect! Quoting <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>: <blockquote><h3>Out of scope: handle more breakage scenarios when developing components</h3> There's more things that can fundamentally break a component instance though: <ol> <li>✅ (<del>this</del> that issue) the underlying component disappeared from the <code>ComponentSource</code> (whether deleted or renamed) </li><li>❌ the set of required explicit inputs increased (SDC terminology: "props") — decreasing is not a problem! </li><li>❌ the set of required explicit inputs changed (SDC terminology: "props") aka a required explicit input was renamed </li><li>❌ the shape of an explicit input (SDC terminology: "props") changed, e.g. a <code>type: string</code> becoming a <code>type: integer</code> </li></ol> ⚠️ Currently, there's also ways to break things in Canvas' UI that are not fundamental, such as passing an optional prop that either no longer exists or has been renamed. (That currently triggers the validation in <code>\Drupal\canvas\Plugin\Canvas\ComponentSource\GeneratedFieldExplicitInputUxComponentSourceBase::getDefaultStaticPropSource()</code> but arguably should not. See @heyyo's <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>.) (This may cause garbage values though, for that we have <a href="https://git.drupalcode.org/project/canvas/-/work_items/3524401" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3524401</a>.) </blockquote> This issue is about: <ul> <li>fixing the 1 ⚠️ , which is what most comments on this issue have been about so far, see especially @heyyo's #18</li> <li>fixing the 3 ❌, the first 2 correspond to what @catch wrote in #6, the 3rd was not yet discussed here</li> </ul> <h3 id="proposed-resolution">Proposed resolution</h3> <ol> <li>✅ Track which explicit inputs are required in the versioned information in a <code>Component</code> config entity for: <ul> <li>✅ <code>GeneratedFieldExplicitInputUxComponentSourceBase</code>-based implementations (SDC + code components) → <pre>diff --git a/config/schema/canvas.schema.yml b/config/schema/canvas.schema.yml index 7c7c57ee6..e5aa02441 100644 --- a/config/schema/canvas.schema.yml +++ b/config/schema/canvas.schema.yml @@ -459,6 +459,9 @@ canvas.generated_field_explicit_input_ux:        sequence:          type: mapping          mapping: +          required: +            type: boolean +            label: 'Required prop'            field_type:              type: string              label: 'Default field type'</pre> → <a href="https://git.drupalcode.org/project/canvas/-/merge_requests/205">MR 205</a> </li><li>✅ … which will require an update path → <a href="https://git.drupalcode.org/project/canvas/-/merge_requests/219">MR 219</a> </li><li>ℹ️ This also enables important future work: [3463996] and <a href="https://git.drupalcode.org/project/canvas/-/work_items/3509115" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3509115</a>. </li></ul> </li><li>✅ Update <code>GeneratedFieldExplicitInputUxComponentSourceBase</code> to stop relying on the live code implementation (the underlying SDC or code component) whenever possible and rely on the <code>prop_field_definitions</code> in the <code>Component</code> config entity instead: <ol> <li>✅ <code>::buildComponentInstanceForm()</code> should stop calling <code>::getDefaultStaticPropSource(…, validate_prop_name: TRUE)</code> — pass <code>FALSE</code> instead. Consider only calling that if A) assertions are on (indicating a developer) and B) Twig developer mode is off (because it'd otherwise get in the way while developing the SDC!) →ended up happening in <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>✅ Update <code>::buildComponentInstanceForm()</code> and <code>::getDefaultStaticPropSource()</code> to maximally rely on <code>prop_field_definitions</code> in the <code>Component</code> — which also means we're finally respecting the prop order defined in the SDC/code component! 🥳 → <a href="https://git.drupalcode.org/project/canvas/-/merge_requests/196">MR 196</a> </li></ol> </li> <li>✅ Ensure that even an exception while constructing the render array for a component instance in <code>GeneratedFieldExplicitInputUxComponentSourceBase::renderComponent()</code> cannot trigger a PHP fatal error: wrap that also in the <code>RenderSafeComponentContainer</code>, specifically in <code>Component::normalizeForClientSide()</code>, this ensures that the list of available components to instantiate correctly at runtime reflects what is broken and not → <a href="https://git.drupalcode.org/project/canvas/-/merge_requests/196">MR 196</a> </li><li>🚫 <del>Consider renaming: <code>::isValid()</code>?</del> → not stable-blocking, defer that to the overall goal of making the component source plugin API public & stable in <a href="https://git.drupalcode.org/project/canvas/-/work_items/3520484" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3520484</a>. </li></ol> <h3 id="ui-changes">User interface changes</h3> Rather than just "Component is broken" in <img src="https://www.drupal.org/files/issues/2025-09-26/Captura%20de%20pantalla%202025-09-26%20a%20las%2013.52.36.png">, when "verbose error logging" is enabled, you'd instead see something much more detailed/helpful, both inside Canvas and on the live site: <img src="https://www.drupal.org/files/issues/2025-10-09/Screenshot%202025-10-09%20at%2023.01.51.png" alt="Screenshot"> <img src="https://www.drupal.org/files/issues/2025-10-09/Screenshot%202025-10-09%20at%2023.02.10.png" alt="Screenshot"> > Related issue: [Issue #3536277](https://www.drupal.org/node/3536277) > Related issue: [Issue #3523841](https://www.drupal.org/node/3523841) > Related issue: [Issue #3521221](https://www.drupal.org/node/3521221)

issue