feat!: switch form filler value options to items-based resolution

[ugur-vaadin]

Description

In form filler DX test sessions, the return type of value options APIs was a pain point. Even after updating examples and clarifying it in the documentation, it still was not intuitive: the developer had to think in labels (strings) when the rest of their codebase thought in domain objects, and had to supply a toValue converter that re-encoded the label-to-value mapping the field's ItemLabelGenerator already expressed.

This PR replaces that shape with an items-based resolution path:

• Registrations now carry the domain objects, not pre-rendered labels. Aligned with how the rest of the codebase models selection options.
• Labels for the LLM are derived through one ItemLabelGenerator. By default, the controller reflects the field's own setItemLabelGenerator(...) so common cases need no extra wiring; an explicit one can be supplied on ValueOptions for custom components or cases where the LLM should see a different label than the UI.
• When the LLM picks a label, the controller walks the registration's items, applies the same generator per item, and writes the first matching item to the field. The bijection lives in one place — the label generator — and the toValue converter is no longer needed and has been removed.

Changed in ValueOptions:

• options(Collection<String>) → options(Collection<V>)
• options(BiFunction<String, Integer, List<String>>) → options(BiFunction<String, Integer, List<V>>)

New in ValueOptions:

• itemLabelGenerator(ItemLabelGenerator<V>) — optional; falls back to the field's own labeler, then to String.valueOf(item).

Changed in FormAIController:

• fieldValueOptions(ValueOptions<String>) → fieldValueOptions(ValueOptions<V>)
• fieldValueOptions(ValueOptions<V>, Function<String, V> toValue) removed.

Other behavior:

• Items with duplicate labels resolve to the first in registration order; a fixed-options registration logs a warning at registration so the developer notices.
• A query-mode fill_form that arrives before any query_field_options call is rejected with a reason naming query_field_options so the LLM can recover on the next turn.

Warning

The two-argument fieldValueOptions(ValueOptions, Function<String, V>) overload and the String-only generics on the single-argument variant are gone.

Based on DX test findings.

No related issue.

Type of change

• Bugfix
• Feature

Checklist

• I have read the contribution guide: https://vaadin.com/docs/latest/contributing/overview
• I have added a description following the guideline.
• The issue is created in the corresponding repository and I have referenced it.
• I have added tests to ensure my change is effective and works as intended.
• New and existing tests are passing locally with my change.
• I have performed self-review and corrected misspellings.
• Enhancement / new feature was discussed in a corresponding GitHub issue and Acceptance Criteria were created.

[sissbruecker]

The JavaDoc says:

Each item is also the label the LLM sees — the chosen label is itself the value written to the field, with no converter needed

But it runs the same applyValueOptions method that applies a potential item labeler. So when you provide a label function through the value options (and presumably also when through the field), the labels and values differ.

From my understanding this method should not use an item labeler, and potentially log a warning if one is configured in the options.

[ugur-vaadin]

Dropped the Function.identity() along with the two-arg overload entirely. For duplicate labels: first registered item wins, and the registration logs a warning including the duplicates and pointing at ItemLabelGenerator.

[sissbruecker]

It might be worth pointing out explicitly that toValue must produce the reverse of whatever an item label generator produced. Currently this is connection is only implicit.

I feel this surfaces a gap in the design where you configure model -> label and label -> model converters in separate places, which has a higher chance for a misconfiguration. It's also problematic that this uses the label generator from the field as a fallback: That one can be easily changed in the UI code for whatever reason, but then you also need to remember to update the converter in the code that configures the form controller to resolve the model from the changed label.

I wonder if toValue is even necessary? We already keep references to the items in the value options now, so could we also add a lookup for the reverse mapping? Or was there some concern about stale data?

[ugur-vaadin]

Dropped toValue. We iterated on this API quite a bit and I agree that it doesn't provide much value anymore, and it creates more confusion.

[sissbruecker]

Would it make sense to use a map to automatically dedupe, instead of keeping lots of object references that will never be used because we only pick the first one? Also the lookups would become easier / cheaper.

[ugur-vaadin]

Done. We not use a LinkedHashMap that uses insertion order.

[sissbruecker]

This doesn't look correct, as it keeps adding potentially the same instances over and over if multiple queries match them. A map could fix this part as well.

Other than that it's questionable if this should keep previous entries, in case the application has removed data or updated it. Maybe it should clear on every query, or there might be some other point in the workflow where that is sensible.

[ugur-vaadin]

Updated the code to use the map. It should fix the potential inflation issue. For the second part, the controller now refreshes every value options binding at the start of each turn. It re-reads the field's labeler, repopulates the fixed options map from its item list, and clears the query options map.

[sonarqubecloud]

Quality Gate passed

Issues
6 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud