Skip to content

Commit bc9d6bb

Browse files
refactor!: rename FormAIController API to include field (#9544) (CP: 25.2) (#9547)
This PR cherry-picks changes from the original PR #9544 to branch 25.2. --- #### Original PR description > ## Description > > This PR renames `FormAIController` APIs to include "field" in order to make it clearer for the developer. > > | Old | New | > | --- | --- | > | ignore | ignoreField | > | describe | describeField | > | valueOptions | fieldValueOptions | > | setValuesHidden | setFieldValuesHidden | > | isValuesHidden | isFieldValuesHidden | > | showHighlight | showFieldHighlight | > | hideHighlight | hideFieldHighlight | > > Based on DX test session findings. > > No related issue. > > ## Type of change > > - [ ] Bugfix > - [ ] Feature > - [x] Refactor > > ## Checklist > > - [x] I have read the contribution guide: https://vaadin.com/docs/latest/contributing/overview > - [x] 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. > - [x] New and existing tests are passing locally with my change. > - [x] I have performed self-review and corrected misspellings. Co-authored-by: Ugur Saglam <106508695+ugur-vaadin@users.noreply.github.com>
1 parent 2ad5546 commit bc9d6bb

14 files changed

Lines changed: 312 additions & 289 deletions

File tree

‎vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/main/java/com/vaadin/flow/component/ai/form/FormAIController.java‎

Lines changed: 65 additions & 58 deletions
Large diffs are not rendered by default.

‎vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/main/java/com/vaadin/flow/component/ai/form/FormFieldHighlighter.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,8 @@
1919
import com.vaadin.flow.dom.Element;
2020

2121
/**
22-
* Bridges {@link FormAIController#showHighlight} /
23-
* {@link FormAIController#hideHighlight} to the
22+
* Bridges {@link FormAIController#showFieldHighlight} /
23+
* {@link FormAIController#hideFieldHighlight} to the
2424
* {@code vaadin-field-highlighter} web component. Each controller passes its
2525
* own {@code userId} so the AI user does not collide with any other user the
2626
* application may keep on the same field.

‎vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/main/java/com/vaadin/flow/component/ai/form/FormFieldHints.java‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -23,14 +23,14 @@
2323
* Mutable per-field hint state held by {@link FormAIController}, keyed by the
2424
* field's opaque id.
2525
* <p>
26-
* Set by {@link FormAIController#valueOptions(ValueOptions)
27-
* controller.valueOptions(...)}: {@link #valueOptionsQuery} carries the filter
28-
* callback (or a fixed-options snapshot wrapped in one), {@link #fixedOptions}
29-
* flags whether the schema should render the options as {@code enum} or
30-
* {@code queryable}, and {@link #valueOptionsToValue} resolves one label to one
31-
* element. For multi-select fields the controller wraps the resolved elements
32-
* into a {@link java.util.LinkedHashSet} before {@code setValue}; the hint
33-
* state is the same shape in both cases.
26+
* Set by {@link FormAIController#fieldValueOptions(ValueOptions)
27+
* controller.fieldValueOptions(...)}: {@link #valueOptionsQuery} carries the
28+
* filter callback (or a fixed-options snapshot wrapped in one),
29+
* {@link #fixedOptions} flags whether the schema should render the options as
30+
* {@code enum} or {@code queryable}, and {@link #valueOptionsToValue} resolves
31+
* one label to one element. For multi-select fields the controller wraps the
32+
* resolved elements into a {@link java.util.LinkedHashSet} before
33+
* {@code setValue}; the hint state is the same shape in both cases.
3434
*
3535
* @author Vaadin Ltd
3636
*/

‎vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/main/java/com/vaadin/flow/component/ai/form/FormFieldSchema.java‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -99,10 +99,10 @@ private static void applyType(ObjectNode node, HasValue<?, ?> field,
9999
applySelectionOptions(items, field, hints);
100100
return;
101101
}
102-
// valueOptions turns any field into a constrained-choice field from
103-
// the LLM's perspective: the LLM picks a label, valueOptionsToValue
104-
// converts back. Emit type=string + enum/queryable so the LLM sees the
105-
// signal regardless of the underlying value type.
102+
// fieldValueOptions turns any field into a constrained-choice field
103+
// from the LLM's perspective: the LLM picks a label,
104+
// valueOptionsToValue converts back. Emit type=string + enum/queryable
105+
// so the LLM sees the signal regardless of the underlying value type.
106106
if (type == FormFieldType.SINGLE_SELECT || hasValueOptions(hints)) {
107107
node.put(FIELD_TYPE, TYPE_STRING);
108108
applySelectionOptions(node, field, hints);
@@ -168,9 +168,9 @@ private static void applyValue(ObjectNode node, HasValue<?, ?> field,
168168
node.putNull(FIELD_VALUE);
169169
return;
170170
}
171-
// valueOptions rewrites the schema type to "string" + enum/queryable
172-
// for non-selection fields; render the value as a string so the two
173-
// halves of the payload agree.
171+
// fieldValueOptions rewrites the schema type to "string" +
172+
// enum/queryable for non-selection fields; render the value as a
173+
// string so the two halves of the payload agree.
174174
if (hasValueOptions(hints) && type != FormFieldType.SINGLE_SELECT
175175
&& type != FormFieldType.MULTI_SELECT) {
176176
node.put(FIELD_VALUE, FormValueConverter.renderItem(field, value));

‎vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/main/java/com/vaadin/flow/component/ai/form/FormValueConverter.java‎

Lines changed: 28 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -181,36 +181,38 @@ static final class RejectedValueException extends RuntimeException {
181181
* {@link HasValue#setValue}. Returns the field's empty value when the JSON
182182
* node is {@code null} or a JSON {@code null}. Throws
183183
* {@link RejectedValueException} when the JSON shape doesn't match the
184-
* field's type, or when the registered {@code valueOptions} cannot resolve
185-
* a label.
184+
* field's type, or when the registered {@code fieldValueOptions} cannot
185+
* resolve a label.
186186
* <p>
187-
* <b>Selection and {@code valueOptions} routing:</b> when a field has a
188-
* {@code valueOptionsToValue} registered, the LLM sees the field as an
187+
* <b>Selection and {@code fieldValueOptions} routing:</b> when a field has
188+
* a {@code valueOptionsToValue} registered, the LLM sees the field as an
189189
* {@code enum} or {@code queryable} string in {@code get_form_state} and
190190
* picks one or more labels. The label-to-value resolution happens here so
191191
* the resulting object matches the field's value type before
192192
* {@link HasValue#setValue} sees it. Multi-select fields expect a JSON
193193
* array of labels; single-select and other label-routed fields expect a
194-
* single string. A selection field without a {@code valueOptions}
194+
* single string. A selection field without a {@code fieldValueOptions}
195195
* registration falls back to matching the supplied label(s) against the
196196
* field's own in-memory items (an eager {@code setItems(...)}), which carry
197197
* the same labels {@code get_form_state} advertised; only a field that has
198-
* neither a {@code valueOptions} registration nor items is rejected with a
199-
* curated reason naming the missing registration.
198+
* neither a {@code fieldValueOptions} registration nor items is rejected
199+
* with a curated reason naming the missing registration.
200200
*/
201201
static Object convert(FormFieldDescriptor field, JsonNode value) {
202202
if (value == null || value.isNull()) {
203203
return field.field().getEmptyValue();
204204
}
205205
// Multi-select takes an array of labels and applies toValue per
206-
// element; handled before the valueOptions check so the array shape
207-
// is enforced even on fields whose value type is itself a String set.
206+
// element; handled before the fieldValueOptions check so the array
207+
// shape is enforced even on fields whose value type is itself a String
208+
// set.
208209
if (field.type() == FormFieldType.MULTI_SELECT) {
209210
return convertMultiSelect(field, value);
210211
}
211-
// Once valueOptions is registered the LLM picks a label, regardless
212-
// of the field's underlying value type — type-driven parsing would
213-
// hand setValue a raw String and the field would reject it.
212+
// Once fieldValueOptions is registered the LLM picks a label,
213+
// regardless of the field's underlying value type — type-driven
214+
// parsing would hand setValue a raw String and the field would reject
215+
// it.
214216
var hints = field.hints();
215217
if (hints != null && hints.valueOptionsToValue != null) {
216218
return convertSingleLabel(value, hints.valueOptionsToValue);
@@ -232,12 +234,12 @@ static Object convert(FormFieldDescriptor field, JsonNode value) {
232234

233235
/**
234236
* Fallback resolver for a SINGLE_SELECT field that has no
235-
* {@code valueOptions(...)} registered: matches the LLM-supplied label
237+
* {@code fieldValueOptions(...)} registered: matches the LLM-supplied label
236238
* against the field's in-memory items via {@link #renderItem}. This is the
237239
* inverse of the schema path that emits the same items as an {@code enum}
238240
* array — both sides agree on the label set, so the LLM can write through
239241
* an eager {@code setItems(...)} field without the developer wiring up
240-
* {@code valueOptions(...)} too.
242+
* {@code fieldValueOptions(...)} too.
241243
*/
242244
private static Object convertSingleSelectFromItems(
243245
FormFieldDescriptor field, JsonNode value) {
@@ -247,14 +249,15 @@ private static Object convertSingleSelectFromItems(
247249
}
248250
var items = listDataProviderItems(field.field());
249251
if (items.isEmpty()) {
250-
// No items and no valueOptions — the field has no option source at
251-
// all. Point the developer at the missing wiring rather than the
252-
// missing match, since the model couldn't have picked any label.
252+
// No items and no fieldValueOptions — the field has no option
253+
// source at all. Point the developer at the missing wiring rather
254+
// than the missing match, since the model couldn't have picked any
255+
// label.
253256
throw new RejectedValueException(
254257
"Selection field has no value options registered — register "
255-
+ "options via FormAIController.valueOptions(...) "
256-
+ "or call setItems(...) so the AI knows what to "
257-
+ "pick.");
258+
+ "options via "
259+
+ "FormAIController.fieldValueOptions(...) or call "
260+
+ "setItems(...) so the AI knows what to pick.");
258261
}
259262
return resolveLabelAgainstItems(field.field(), value.asString(), items);
260263
}
@@ -298,11 +301,11 @@ private static Object convertMultiSelect(FormFieldDescriptor field,
298301

299302
/**
300303
* Fallback resolver for a MULTI_SELECT field that has no
301-
* {@code valueOptions(...)} registered: matches each LLM-supplied label
302-
* against the field's in-memory items via {@link #renderItem}. Mirrors
303-
* {@link #convertSingleSelectFromItems} so eager-items
304+
* {@code fieldValueOptions(...)} registered: matches each LLM-supplied
305+
* label against the field's in-memory items via {@link #renderItem}.
306+
* Mirrors {@link #convertSingleSelectFromItems} so eager-items
304307
* {@code MultiSelectComboBox<T>} and {@code CheckboxGroup<T>} are writable
305-
* without the developer wiring up {@code valueOptions(...)} too.
308+
* without the developer wiring up {@code fieldValueOptions(...)} too.
306309
*/
307310
private static Object convertMultiSelectFromItems(FormFieldDescriptor field,
308311
JsonNode value) {
@@ -311,7 +314,7 @@ private static Object convertMultiSelectFromItems(FormFieldDescriptor field,
311314
throw new RejectedValueException(
312315
"Multi-select field has no value options registered — "
313316
+ "register options via "
314-
+ "FormAIController.valueOptions(...) or call "
317+
+ "FormAIController.fieldValueOptions(...) or call "
315318
+ "setItems(...) so the AI knows what to pick.");
316319
}
317320
var result = new LinkedHashSet<>();

‎vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/main/java/com/vaadin/flow/component/ai/form/ValueOptions.java‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -31,15 +31,15 @@
3131
* The label set is either fixed ({@link #options(Collection)}) or supplied on
3232
* demand by a callback ({@link #options(BiFunction)}); exactly one of the two
3333
* must be set, with the last call winning. Pass the configured registration to
34-
* {@link FormAIController#valueOptions(ValueOptions)
35-
* controller.valueOptions(...)} to apply it; the labels are then presented to
36-
* the LLM as the field's choices.
34+
* {@link FormAIController#fieldValueOptions(ValueOptions)
35+
* controller.fieldValueOptions(...)} to apply it; the labels are then presented
36+
* to the LLM as the field's choices.
3737
* <p>
3838
* Labels are always {@link String} values, regardless of the field's value
3939
* type. For a non-{@link String} field, supply a label-to-value converter
40-
* through {@link FormAIController#valueOptions(ValueOptions, Function)
41-
* valueOptions(config, toValue)} — the converter resolves a chosen label to the
42-
* field's value type before the controller writes it.
40+
* through {@link FormAIController#fieldValueOptions(ValueOptions, Function)
41+
* fieldValueOptions(config, toValue)} — the converter resolves a chosen label
42+
* to the field's value type before the controller writes it.
4343
*
4444
* @param <I>
4545
* the per-label item type the converter must produce — the field's
@@ -64,9 +64,9 @@ private ValueOptions(HasValue<?, ?> field, boolean multi) {
6464
* Starts an options registration for a single-value field. The field's
6565
* value type {@code V} flows through; for any {@code V} other than
6666
* {@link String}, the controller's two-argument
67-
* {@link FormAIController#valueOptions(ValueOptions, Function)} overload
68-
* must be used to supply a label-to-value converter (a compile-time
69-
* requirement, not a runtime check).
67+
* {@link FormAIController#fieldValueOptions(ValueOptions, Function)}
68+
* overload must be used to supply a label-to-value converter (a
69+
* compile-time requirement, not a runtime check).
7070
*
7171
* @param field
7272
* the single-value field whose options the LLM may pick from,
@@ -87,9 +87,9 @@ public static <V> ValueOptions<V> forField(HasValue<?, V> field) {
8787
* statically typed as {@link MultiSelect}. The per-element type {@code T}
8888
* flows through; for any {@code T} other than {@link String}, the
8989
* controller's two-argument
90-
* {@link FormAIController#valueOptions(ValueOptions, Function)} overload
91-
* must be used. The controller aggregates resolved per-label items into a
92-
* {@link LinkedHashSet} before {@link HasValue#setValue}.
90+
* {@link FormAIController#fieldValueOptions(ValueOptions, Function)}
91+
* overload must be used. The controller aggregates resolved per-label items
92+
* into a {@link LinkedHashSet} before {@link HasValue#setValue}.
9393
*
9494
* @param field
9595
* the multi-select field whose options the LLM may pick from,

‎vaadin-ai-components-flow-parent/vaadin-ai-components-flow/src/test/java/com/vaadin/flow/component/ai/AIComponentsSerializableTest.java‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,8 @@ protected Stream<String> getExcludedPatterns() {
9494
"com\\.vaadin\\.flow\\.component\\.ai\\.form\\.BinderReflection(\\$\\d+)?",
9595
// ValueOptions is a transient registration helper: the
9696
// controller copies its state into FormFieldHints during
97-
// valueOptions(...) and discards the instance. It is not part
97+
// fieldValueOptions(...) and discards the instance. It is not
98+
// part
9899
// of any serialized session state.
99100
"com\\.vaadin\\.flow\\.component\\.ai\\.form\\.ValueOptions(\\$\\d+)?"));
100101
}

0 commit comments

Comments
 (0)