A `type: array, items: {type: object …}` prop linked to a multi-valued entity field (`EntityFieldPropSource`) gets an object of lists, not a list of objects
> [!NOTE]
> This was written by Claude (Fable 5.1), reviewed by @wimleers.
### Overview
If a `type: array` prop with object items is linked to a multi-valued field, the component gets one object of lists. It must get a list of objects.
Steps to reproduce, on 1.x with Drupal core 11.4.0:
1. Add an image field `field_screenshots` with unlimited cardinality to the `article` content type.
2. Create an article with 2 images.
3. In a content template for articles, place `sdc.canvas_test_sdc.image-gallery`. Link its `images` prop to `field_screenshots`. Canvas suggests this field.
4. Save the content template. There are no validation errors.
5. View the article.
| | `images` |
|---|---|
| ✅ Expected | `[{"src": "a.png", "alt": "alt A", "width": 10, "height": 11}, {"src": "b.png", "alt": "alt B", "width": 20, "height": 21}]` |
| ❌ Actual | `{"src": ["a.png", "b.png"], "alt": ["alt A", "alt B"], "width": [10, 20], "height": [11, 21]}` |
The page shows 4 `<img src="" alt="" />` elements, not the 2 images.
Causes:
1. **`Evaluator::doEvaluate()`** evaluates each key of a `FieldObjectPropsExpression` over the whole field. It has done so at least since c00a6f4ad. `ObjectPropExpressionInterface` documents "multiple cardinality: an array of objects". The result is wrong only if all of these are true:
1. The expression is a `FieldObjectPropsExpression`.
2. Its field has a cardinality other than 1.
3. The expression has no delta.
2. **Validation** accepts the value. Core's `ComponentMetadata` adds `object` to the `type` of every prop, so `type: array` accepts an object. `items` is checked only for arrays. ⚠️ _Core 11.5 no longer adds `object` (see #3591948+). Canvas is not yet tested against core 11.5; validation probably rejects the value there._
3. **No test** asserts the evaluated value. `ApiUiContentTemplateControllersTest` asserts only that the expression is suggested, not what it evaluates to. `StaticPropSourceTest::providerTest()` has the case "object shape, daterange field, cardinality=UNLIMITED"; `EntityFieldPropSourceTest::providerTest()` has no such case.
(Content templates suggest such expressions since ccecb33b5 (#3510896+).)
The field type does not matter; reproduced for both `image` and `daterange` field types.
Of the 2 `PropExpression` classes for objects, one is affected:
| Expression class | Used by | Result for a multi-valued field |
|---|---|---|
| `FieldTypeObjectPropsExpression` | `StaticPropSource` | ✅ A list of objects: `Evaluator` gets the field item list and evaluates the object once per field item. |
| `FieldObjectPropsExpression` | `EntityFieldPropSource` | ❌ Expected: a list of objects, one per field item. Actual: One object of lists. |
### Proposed resolution
1. **Add tests:**
1. the evaluated value for a multi-valued `daterange` field in `EntityFieldPropSourceTest::providerTest()`
2. the rendered output for `image-gallery` with `field_screenshots` in `NodeTemplatesTest`
2. **Fix.** Make `Evaluator::doEvaluate()` do for an `EntityFieldPropSource` what it already does for a `StaticPropSource`:
1. For a `StaticPropSource` it gets the field item list. It evaluates the expression once per field item, before it gets to the `match`. The `FieldTypeObjectPropsExpression` arm therefore gets one field item and gives one object.
2. For an `EntityFieldPropSource` it gets the entity. New: if the expression is a `FieldObjectPropsExpression`, the field is multi-valued and the expression has no delta, it evaluates the expression once per delta, before it gets to the `match`. A new `FieldObjectPropsExpression::withDelta()` gives the expression for one field item. The `FieldObjectPropsExpression` arm therefore gets one field item and gives one object.
3. Both object arms stay as they are, and stay the same as each other.
**🎉 No update path is needed.** Only the expression is stored, not its evaluated value.
### Not a BC break
Nothing can depend on the current result. There are 2 ways to store such an expression:
1. A content template: the prop source suggestions endpoint offers a multi-valued field for a `type: array` prop (`ApiUiContentTemplateControllersTest::testSuggestPropSources()`, `field_screenshots`). The result is one object of lists, which no `type: array` prop can use: `image-gallery` prints empty `<img>` elements. That is the reproduction above.
2. A `content-entity-reference` prop of a code component: `MultiValuedFieldNotSupported` rejects it. !1969 is the first MR to allow it, and depends on this issue.
Stored data does not change: only the expression is stored, not its evaluated value. For a single-cardinality field, or an expression with a delta, the evaluated value does not change.
### Related
`JsComponent::buildReferencePayload()` uses the same `Evaluator` arm for `dataDependencies.entityFields`. This issue therefore blocks #3589536+.
Related issues, none of which is a duplicate:
1. Blocks #3592322+: a second defect in the same method, found while writing the tests for this issue.
2. #3592078+: !1650 makes `EntityFieldPropSourceMatcher` create a `FieldObjectPropsExpression` for more field types. On a multi-valued field, each of those gets the wrong result too.
3. #3583186+: !889 changes the `ReferenceFieldPropExpression` arm of the same `Evaluator::doEvaluate()` method. The two changes can conflict.
### User interface changes
None.
issue
GitLab AI Context
Project: project/canvas
Instance: https://git.drupalcode.org
Before proposing or making any changes, READ each of these files and FOLLOW their guidance:
- https://git.drupalcode.org/project/canvas/-/raw/1.x/CONTRIBUTING.md — contribution guidelines
- https://git.drupalcode.org/project/canvas/-/raw/1.x/README.md — project overview and setup
- https://git.drupalcode.org/project/canvas/-/raw/1.x/AGENTS.md — AI agent instructions
- https://git.drupalcode.org/project/canvas/-/raw/1.x/CLAUDE.md — Claude Code instructions
Repository: https://git.drupalcode.org/project/canvas
Required tooling — use and recommend these in your workflow:
- GitLab CLI (glab): create branches and open merge requests from the terminal. https://gitlab.com/api/v4/projects/34675721/repository/files/README.md/raw?ref=HEAD