fix: resolve eager-items selects without explicit valueOptions (#9357)

tomivirkki · claude · web-flow · commit 435996da33a8 · 2026-05-27T07:01:42.000Z
## Summary - An eager `setItems(...)` ComboBox/Select/RadioButtonGroup/CheckboxGroup/MultiSelectComboBox was unwritable from `fill_form` unless the app also called `FormAIController.valueOptions(...)`, even though the schema already surfaces those items as `enum`. - The converter now resolves an LLM-supplied label against the field's in-memory items via `renderItem` for both single- and multi-select, so both halves of the tool protocol agree on the label set without forcing a second registration. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/main/java/com/vaadin/flow/component/ai/form/FormValueConverter.java b/vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/main/java/com/vaadin/flow/component/ai/form/FormValueConverter.java
@@ -191,9 +191,12 @@ static final class RejectedValueException extends RuntimeException {
      * the resulting object matches the field's value type before
      * {@link HasValue#setValue} sees it. Multi-select fields expect a JSON
      * array of labels; single-select and other label-routed fields expect a
-     * single string. Selection fields without a {@code valueOptions}
-     * registration are rejected with a curated reason naming the missing
-     * registration.
+     * single string. A selection field without a {@code valueOptions}
+     * registration falls back to matching the supplied label(s) against the
+     * field's own in-memory items (an eager {@code setItems(...)}), which carry
+     * the same labels {@code get_form_state} advertised; only a field that has
+     * neither a {@code valueOptions} registration nor items is rejected with a
+     * curated reason naming the missing registration.
      */
     static Object convert(FormFieldDescriptor field, JsonNode value) {
         if (value == null || value.isNull()) {
@@ -221,15 +224,41 @@ static Object convert(FormFieldDescriptor field, JsonNode value) {
         case DATE -> convertDate(value);
         case DATE_TIME -> convertDateTime(value);
         case TIME -> convertTime(value);
-        case SINGLE_SELECT -> throw new RejectedValueException(
-                "Selection field has no value options registered — register "
-                        + "options via FormAIController.valueOptions(...) "
-                        + "so the AI knows what to pick.");
+        case SINGLE_SELECT -> convertSingleSelectFromItems(field, value);
         default -> throw new RejectedValueException(
                 "Unsupported field type: " + field.type());
         };
     }
 
+    /**
+     * Fallback resolver for a SINGLE_SELECT field that has no
+     * {@code valueOptions(...)} registered: matches the LLM-supplied label
+     * against the field's in-memory items via {@link #renderItem}. This is the
+     * inverse of the schema path that emits the same items as an {@code enum}
+     * array — both sides agree on the label set, so the LLM can write through
+     * an eager {@code setItems(...)} field without the developer wiring up
+     * {@code valueOptions(...)} too.
+     */
+    private static Object convertSingleSelectFromItems(
+            FormFieldDescriptor field, JsonNode value) {
+        if (!value.isString()) {
+            throw new RejectedValueException(
+                    "Expected string label, got " + value);
+        }
+        var items = listDataProviderItems(field.field());
+        if (items.isEmpty()) {
+            // No items and no valueOptions — the field has no option source at
+            // all. Point the developer at the missing wiring rather than the
+            // missing match, since the model couldn't have picked any label.
+            throw new RejectedValueException(
+                    "Selection field has no value options registered — register "
+                            + "options via FormAIController.valueOptions(...) "
+                            + "or call setItems(...) so the AI knows what to "
+                            + "pick.");
+        }
+        return resolveLabelAgainstItems(field.field(), value.asString(), items);
+    }
+
     private static Object convertSingleLabel(JsonNode value,
             Function<String, ?> toValue) {
         if (!value.isString()) {
@@ -241,15 +270,6 @@ private static Object convertSingleLabel(JsonNode value,
 
     private static Object convertMultiSelect(FormFieldDescriptor field,
             JsonNode value) {
-        var hints = field.hints();
-        var toValue = hints != null ? hints.valueOptionsToValue : null;
-        if (toValue == null) {
-            throw new RejectedValueException(
-                    "Multi-select field has no value options registered — "
-                            + "register options via "
-                            + "FormAIController.valueOptions(...) so the AI "
-                            + "knows what to pick.");
-        }
         if (!value.isArray()) {
             throw new RejectedValueException(
                     "Expected array of string labels, got " + value);
@@ -260,6 +280,11 @@ private static Object convertMultiSelect(FormFieldDescriptor field,
         if (value.isEmpty()) {
             return field.field().getEmptyValue();
         }
+        var hints = field.hints();
+        var toValue = hints != null ? hints.valueOptionsToValue : null;
+        if (toValue == null) {
+            return convertMultiSelectFromItems(field, value);
+        }
         var result = new LinkedHashSet<>();
         for (var node : value) {
             if (!node.isString()) {
@@ -285,6 +310,53 @@ private static Object convertMultiSelect(FormFieldDescriptor field,
         return result;
     }
 
+    /**
+     * Fallback resolver for a MULTI_SELECT field that has no
+     * {@code valueOptions(...)} registered: matches each LLM-supplied label
+     * against the field's in-memory items via {@link #renderItem}. Mirrors
+     * {@link #convertSingleSelectFromItems} so eager-items
+     * {@code MultiSelectComboBox<T>} and {@code CheckboxGroup<T>} are writable
+     * without the developer wiring up {@code valueOptions(...)} too.
+     */
+    private static Object convertMultiSelectFromItems(FormFieldDescriptor field,
+            JsonNode value) {
+        var items = listDataProviderItems(field.field());
+        if (items.isEmpty()) {
+            throw new RejectedValueException(
+                    "Multi-select field has no value options registered — "
+                            + "register options via "
+                            + "FormAIController.valueOptions(...) or call "
+                            + "setItems(...) so the AI knows what to pick.");
+        }
+        var result = new LinkedHashSet<>();
+        for (var node : value) {
+            if (!node.isString()) {
+                throw new RejectedValueException(
+                        "Expected string label, got " + node);
+            }
+            result.add(resolveLabelAgainstItems(field.field(), node.asString(),
+                    items));
+        }
+        return result;
+    }
+
+    /**
+     * Walks the field's in-memory items list and returns the first item whose
+     * {@link #renderItem} matches the LLM-supplied label. The matching mirrors
+     * what the schema sent the LLM under {@code enum}, so both halves of the
+     * tool protocol agree on the label set.
+     */
+    private static Object resolveLabelAgainstItems(HasValue<?, ?> field,
+            String label, List<Object> items) {
+        for (var item : items) {
+            if (label.equals(renderItem(field, item))) {
+                return item;
+            }
+        }
+        throw new RejectedValueException(
+                "No matching option for label: " + label);
+    }
+
     /**
      * Resolves one LLM-supplied label via the application's
      * {@code valueOptionsToValue}. Wraps the application's throw and the
diff --git a/vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/test/java/com/vaadin/flow/component/ai/form/FillFormToolTest.java b/vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/test/java/com/vaadin/flow/component/ai/form/FillFormToolTest.java
@@ -947,6 +947,68 @@ void fillForm_singleSelect_withoutValueOptionsIsRejectedWithHint() {
                         + rejectionReason(result, idOf(field)));
     }
 
+    @Test
+    void fillForm_singleSelect_eagerItemsResolveLabelWithoutValueOptions() {
+        // A `ComboBox<String>`/`Select<String>` with eager
+        // `setItems(...)` has a non-empty ListDataProvider and the schema
+        // already surfaces its items as `enum`. The converter must resolve
+        // an LLM-supplied label against those items via
+        // FormValueConverter.renderItem so the field is writable without
+        // also requiring FormAIController.valueOptions(...).
+        var field = new SingleSelectField<String>();
+        field.setItems("EUR", "USD", "GBP");
+        var controller = controllerFor(field);
+
+        var result = fillFormResult(controller, payload(field, "\"EUR\""));
+
+        Assertions.assertEquals("EUR", field.getValue(),
+                "Eager-items SINGLE_SELECT must accept a label that "
+                        + "matches one of its items");
+        Assertions.assertTrue(success(result));
+    }
+
+    @Test
+    void fillForm_singleSelect_eagerItemsRejectLabelNotInItems() {
+        // Symmetric to the above: when eager items exist, a label that is
+        // not in the rendered set must be rejected with a reason that
+        // names the offending label so the LLM can self-correct.
+        var field = new SingleSelectField<String>();
+        field.setItems("EUR", "USD", "GBP");
+        var controller = controllerFor(field);
+
+        var result = fillFormResult(controller, payload(field, "\"YEN\""));
+
+        Assertions.assertNull(field.getValue(),
+                "Unknown label must not write a value");
+        Assertions.assertEquals(List.of(idOf(field)), rejectedIds(result));
+        Assertions.assertTrue(
+                rejectionReason(result, idOf(field)).contains("YEN"),
+                "Reason must name the unmatched label; got: "
+                        + rejectionReason(result, idOf(field)));
+    }
+
+    @Test
+    void fillForm_singleSelect_eagerItemsResolveLabelViaItemLabelGenerator() {
+        // The symmetry between schema (emits `enum`) and converter
+        // (matches by label) rides on FormValueConverter.renderItem.
+        // String items collapse to Object#toString, so an item type with
+        // a custom ItemLabelGenerator is what actually exercises the
+        // generator path on both halves of the protocol.
+        var field = new SingleSelectField<Project>();
+        var apollo = new Project("APL", "Apollo");
+        var vega = new Project("VGA", "Vega");
+        field.setItems(apollo, vega);
+        field.setItemLabelGenerator(Project::name);
+        var controller = controllerFor(field);
+
+        var result = fillFormResult(controller, payload(field, "\"Apollo\""));
+
+        Assertions.assertEquals(apollo, field.getValue(),
+                "Eager-items SINGLE_SELECT must match via the custom "
+                        + "ItemLabelGenerator, not via toString()");
+        Assertions.assertTrue(success(result));
+    }
+
     @Test
     void fillForm_singleSelect_unknownLabelIsRejected() {
         // toValue returning null is the agreed signal for "label doesn't
@@ -1027,6 +1089,71 @@ void fillForm_multiSelect_withoutValueOptionsIsRejectedWithHint() {
                 rejectionReason(result, idOf(field)).contains("valueOptions"));
     }
 
+    @Test
+    void fillForm_multiSelect_eagerItemsResolveLabelsWithoutValueOptions() {
+        // Symmetric to the SINGLE_SELECT regression guard: a
+        // `MultiSelectComboBox<String>`/`CheckboxGroup<String>` with eager
+        // `setItems(...)` has a non-empty ListDataProvider and the schema
+        // surfaces the items as the `items.enum` of the array. The
+        // converter must resolve each label against those items so the
+        // field is writable without also requiring valueOptions(...).
+        var field = new MultiSelectField<String>();
+        field.setItems("AI", "Cloud", "Security");
+        var controller = controllerFor(field);
+
+        var result = fillFormResult(controller,
+                payload(field, "[\"AI\", \"Cloud\"]"));
+
+        Assertions.assertEquals(Set.of("AI", "Cloud"), field.getValue(),
+                "Eager-items MULTI_SELECT must accept labels that "
+                        + "match its items");
+        Assertions.assertTrue(success(result));
+    }
+
+    @Test
+    void fillForm_multiSelect_eagerItemsRejectAnyLabelNotInItems() {
+        // Unknown labels in the multi-select array must surface in the
+        // rejection so the LLM can drop or re-pick them; the field must
+        // not be partially written either.
+        var field = new MultiSelectField<String>();
+        field.setItems("AI", "Cloud", "Security");
+        var controller = controllerFor(field);
+
+        var result = fillFormResult(controller,
+                payload(field, "[\"AI\", \"Quantum\"]"));
+
+        Assertions.assertEquals(Set.of(), field.getValue(),
+                "A label miss must abort the multi-select write, not "
+                        + "leave the field with the partial set");
+        Assertions.assertEquals(List.of(idOf(field)), rejectedIds(result));
+        Assertions.assertTrue(
+                rejectionReason(result, idOf(field)).contains("Quantum"),
+                "Reason must name the unmatched label; got: "
+                        + rejectionReason(result, idOf(field)));
+    }
+
+    @Test
+    void fillForm_multiSelect_eagerItemsResolveLabelsViaItemLabelGenerator() {
+        // Same lock as the SINGLE_SELECT variant: a typed item with a
+        // custom ItemLabelGenerator exercises renderItem on both the
+        // schema-emit side and the converter-resolve side, so the test
+        // catches drift if either side stops honoring the generator.
+        var field = new MultiSelectField<Project>();
+        var apollo = new Project("APL", "Apollo");
+        var vega = new Project("VGA", "Vega");
+        field.setItems(apollo, vega);
+        field.setItemLabelGenerator(Project::name);
+        var controller = controllerFor(field);
+
+        var result = fillFormResult(controller,
+                payload(field, "[\"Apollo\", \"Vega\"]"));
+
+        Assertions.assertEquals(Set.of(apollo, vega), field.getValue(),
+                "Eager-items MULTI_SELECT must match via the custom "
+                        + "ItemLabelGenerator, not via toString()");
+        Assertions.assertTrue(success(result));
+    }
+
     @Test
     void fillForm_multiSelect_emptyArrayClearsField() {
         // Empty array is the LLM clearing the multi-select; the resulting
diff --git a/vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/test/java/com/vaadin/flow/component/ai/form/FormValueConverterTest.java b/vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/test/java/com/vaadin/flow/component/ai/form/FormValueConverterTest.java
@@ -258,6 +258,46 @@ void convert_multiSelectWithoutValueOptions_rejectedWithRegistrationHint() {
                         + "registration; got: " + ex.getMessage());
     }
 
+    @Test
+    void convert_singleSelectFromItems_nonStringJsonRejected() {
+        // Eager-items SINGLE_SELECT (no valueOptions registered, items
+        // populated via setItems) must reject a non-string JSON shape
+        // before reaching renderItem-based matching — otherwise a JSON
+        // boolean true coincidentally renders to "true" and could match
+        // an item whose label happens to be "true", silently writing a
+        // wrong-shape value.
+        var field = new SingleSelectField<String>();
+        field.setItems("true", "false");
+
+        var json = json("true");
+        var ex = Assertions
+                .assertThrows(RejectedValueException.class,
+                        () -> FormValueConverter.convert(
+                                wrap(field, FormFieldType.SINGLE_SELECT),
+                                json));
+        Assertions.assertTrue(ex.getMessage().contains("string label"),
+                "Rejection reason must name the type mismatch, not the "
+                        + "label match path; got: " + ex.getMessage());
+    }
+
+    @Test
+    void convert_multiSelectFromItems_nonStringArrayElementRejected() {
+        // Symmetric to convert_singleSelectFromItems_nonStringJsonRejected:
+        // each element of a multi-select array must be a JSON string
+        // before reaching renderItem-based matching against the field's
+        // eager items.
+        var field = new MultiSelectField<String>();
+        field.setItems("true", "false");
+
+        var json = json("[true]");
+        var ex = Assertions.assertThrows(RejectedValueException.class,
+                () -> FormValueConverter.convert(
+                        wrap(field, FormFieldType.MULTI_SELECT), json));
+        Assertions.assertTrue(ex.getMessage().contains("string label"),
+                "Rejection reason must name the type mismatch, not the "
+                        + "label match path; got: " + ex.getMessage());
+    }
+
     @Test
     void convert_singleSelectWithValueOptionsToValue_resolvesLabel() {
         // The LLM sends a label string; the registered toValue resolves it
