[META] When the field type, storage/instance settings, widget, expression or requiredness for an SDC/code component prop changes, the Content Creator must be able to upgrade

Just realized that this is actually far out because of #3464003: [PP-1] [later phase] [needs design] Introduce "adapters" UX.

FYI over at #3515629-16: FieldWidget's XB transforms must be bubbled by the Field Widget rendering to inform the client.2, I sketched how I now think this could actually happen automatically.

Coming up again in #3523841: Versioned Component config entities (SDC, JS: prop_field_definitions, block: default_setting, all: slots for fallback) + component instances refer to versions ⇒ less data to store per XB field row.

Closely related: #3528284: Add e2e tests that prove we can edit an old version of a component. That will lay the foundations for the necessary test coverage for this issue.

I think #5 is actually wrong — this is not blocked on adapters. Because at least a common subset is in principle possible to realize already.

A crucial piece of metadata was missing that would've prevented building this UX: tracking of which props are required #3532514: Gracefully handle components in active development: ensure great DX's first MR (!205) fixed that. 👍

That means this issue is now able to:

• Compare requiredness of each prop
• Compare field type, storage settings, instance settings, widget and default value of each prop
• Compare the set of slot definitions of each prop (which slots exist, their order and the example values for each)

Which should be enough to build a first iteration

Related: #3514672: [Needs design] DX & authoring experience: support `default` in addition to `examples[0]`, enables updating a component input across all existing instances.

FYI: #3558719: Linking then unlinking a field renders a wrong Field Widget: corrupt `StaticPropSource` is sent by client, server should detect this is about to land, and I have +1s for the direction I'm taking #3560005: Require component instances to use the field type + storage + instance settings dictated by the `Component` version in, which will make this MR way simpler and more feasible.

Which also means that @lauriii's #20:

I'm second guessing myself from before by wondering if we should just automatically update all instances when the page is being edited.

… will actually become feasible for many things! 🚀

In a nutshell, we would be able to auto-update the component_version for a component instance that has:

1. a new Component version due to added optional props: automatic update possible (zero inputs changes)
2. a new Component version due to deleted props: automatic update possible (omit obsolete key-value pairs in inputs upon re-saving)
3. a new Component versions due to changed field widget (whether in Canvas itself or due to hook_storage_prop_shape_alter()): automatic update possible (zero inputs changes)

👆 IMHO those are the scope of this issue. They result in old content entity revisions remaining unchanged, new content entity revisions using "the latest and greatest".

But … even for BC break scenarios, update paths become possible, but do inevitably require tailored update paths (i.e. code).

1. New Component versions due to changed field type/storage settings/instance settings (whether in Canvas itself or due to hook_storage_prop_shape_alter()): automatic update possible IF the developer provided an update path.

   👉
   A) load all Components that contain >=1 props of the affected prop shape (will become easier after #3547579: Introduce a new cache tags aware prop shape repository, so changes affecting prop shape calculation can force the re-invoke of hook_canvas_storable_shape_prop_alter)
   B) iterate over all versions (Component::getVersions())
   C) find all instances using that version (ComponentAudit)
   D) per component instance, perform whichever logic is necessary — e.g. link to uri field type is a simple transformation, but image to (media) entity_reference is harder: requires an intermediary Media entity to be created for the previously reference File entity.
   E) set the component_version to the new ("active") version
   F) either save as a new content entity revision (preferable, would keep past data/revisions, and they would all still work!) or as an updated config entity (which do not support revisions — so the following component instance-containing config entity types would be updated in-place: ContentTemplate, PageRegion and Pattern)

   NOTE: this does NOT need to happen in a single request. It could (and must) be done in interruptible batches. State tracking (to immediately continue where we left) would accelerate such an update path, but it'd always be possible to reconstruct the remaining work, too (thanks to ComponentAudit).

   See the preparations for this from June 2025 in \Drupal\Tests\canvas\Kernel\Plugin\Canvas\ComponentSource\ComponentInputsEvolutionTest::testStorablePropShapeChanges().

2. New Component versions due to renamed props or added required props: automatic update possible IF the SDC developer provided an update path.

   👉
   A) load the Component
   B) iterate over all versions (Component::getVersions())
   C) find all instances using that version (ComponentAudit)
   D) per component instance, perform whichever logic is necessary — e.g. rename a key in the component instance's input to the new prop name, or populate a new required prop with a default value
   .
   E) set the component_version to the new ("active") version
   E) either save as a new content entity revision (likely preferable, would keep past data/revisions, but none of them would work, because the live component implementation requires data) or not — it's up to the SDC developer to decide

Related: #3567586-4: Not possible to change theme due to SDC dependencies.

#26++, thanks @effulgentsia!

Guidance posted at #3567413-2: When editing a Canvas entity with a component tree (e.g., page, template, or region), automatically upgrade component instance versions for cases where there's no impact on existing data and -3. Hope it helps.

#3567413: When editing a Canvas entity with a component tree (e.g., page, template, or region), automatically upgrade component instance versions for cases where there's no impact on existing data and #3568906: Handle upgrading and rendering not yet upgraded component instances of components with newly removed props or slots are in. → PP-1

The latter hit a Product vs Engineering mismatch post-merge though: #3568906-29: Handle upgrading and rendering not yet upgraded component instances of components with newly removed props or slots — based on discussion between @lauriii and @penyaskito that may spawn a new child issue.

@penyaskito: this probably should also be postponed on #3574026: Component instances are not updating in the same way in regions than other entities, right? If so, this is still PP-2.

#3568602: Handle upgrading and rendering not yet upgraded component instances of components with new(ly) required props that include an example value is in (only reopened for comment clarifications)!

Last one: #3574026: Component instances are not updating in the same way in regions than other entities.

Once that's done: what work remains on this task? → tagged Needs issue summary update

Just noting that once this is done, we should determine next steps on #3557271: [PP-2] BE: Support changing the data-type of a code component prop.

EDIT: link fixed.

Reflecting the reality that all the actual work has been happening in child issues thanks to @effulgentsia's #29.

Actually, should we close this? Is this now just a duplicate of #3547808: label_display block configuration value should not be translatable?

#3463996: [META] When the field type, storage/instance settings, widget, expression or requiredness for an SDC/code component prop changes, the Content Creator must be able to upgrade has happened and means that "multiple-cardinality props" aka "multi-value props" aka "type: array props" has surfaced a number of edge cases. For example #3587711: Introduce a JsComponentInstanceUpdater that allows prop shape changes and accepts data loss.

This made me realize that actually #3577946: Remove Canvas Dev Mode flag for Multi-Value Props support should not have happened until some things here had been tackled:

1. Safe upgrade criteria (auto-upgraded) should contain "increase of cardinality"
2. Unsafe changes (NOT auto-upgraded) should contain "decrease of cardinality"
3. Unsafe changes (NOT auto-upgraded) for code components should probably allow decreasing the cardinality for code components (meaning a JsComponentInstanceUpdater extends GeneratedFieldExplicitInputUxComponentInstanceUpdater that discards old values) — see #3587711-14: Introduce a JsComponentInstanceUpdater that allows prop shape changes and accepts data loss (and that have been updated before #3577946: Remove Canvas Dev Mode flag for Multi-Value Props support landed)

And that in turn made me realize that another thing was missed in this meta, unrelated to #3577946's multiple-cardinality work:

4. Unsafe changes (NOT auto-upgraded) for code components should probably allow changing the prop shape for code components (meaning a JsComponentInstanceUpdater extends GeneratedFieldExplicitInputUxComponentInstanceUpdater that discards old values) — see #3587711-14: Introduce a JsComponentInstanceUpdater that allows prop shape changes and accepts data loss

(Added all of those to the issue summary. LMK what you think, @penyaskito.)

P.S.: Apparently I'm the one who marked this "PP-1" almost 2 years ago in #5. That's no longer relevant.

Yes, sorry, my bad — indeed all 4 of those still need to be implemented!

Other than that, does #45 make sense?

#48: yep, that's definitely what I intended: only drop the "excess" values. We should minimize data loss for sure.

Clarified in IS.

Repurposed #3587711 to solve one of the 4 todos listed in #45.

AFAICT #3574257: Provide a toast informing editors about which Canvas component trees have been auto-updated's blockers have landed. It would really help in informing the user of the unsafe changes allowed for code components.

Also, child issue #3574257: Provide a toast informing editors about which Canvas component trees have been auto-updated was not listed as a user interface change yet, so added that.

Quoting @lauriii:

NOT support cardinality decrease

I don't see the logic behind this; we support deleting props which is more severe data loss than decreasing the cardinality

Wow Removing props (required or optional) is indeed considered safe, I forgot about that! @lauriii decided that Jan 29 apparently, in
#3568906-3: Handle upgrading and rendering not yet upgraded component instances of components with newly removed props or slots.

That simplifies things.