Package com.vaadin.flow.component.ai.form

Class ValueOptions<V>

java.lang.Object
com.vaadin.flow.component.ai.form.ValueOptions<V>
Type Parameters:
V - the item type — the field's value type for single-value fields, the per-element type for multi-select fields
public final class ValueOptions<V> extends Object
Per-field registration of the items the LLM may pick from. Items carry the field's value type — a ComboBox<Project> registration passes Project items, not pre-rendered strings. Pass the configured registration to controller.fieldValueOptions(...) to apply it.

The item set is either fixed (options(Collection)) or supplied on demand by a callback (options(BiFunction)); exactly one must be set, with the last call winning. Each item is rendered to an LLM-facing label through this chain: the explicit itemLabelGenerator(ItemLabelGenerator) if set, otherwise the field's own setItemLabelGenerator(...) (read reflectively), otherwise String.valueOf(Object). The controller resolves a chosen label back to an item by applying the same chain to each registered item and returning the first whose label matches, so the field's UI label generator drives the AI labels automatically.

Since:
25.2
Author:
Vaadin Ltd

  • Method Details

    • forField

      public static <V> ValueOptions<V> forField(com.vaadin.flow.component.HasValue<?,V> field)
      Starts an options registration for a single-value field. The field's value type V flows through unchanged.
      Type Parameters:
      V - the field's value type
      Parameters:
      field - the single-value field whose options the LLM may pick from, not null
      Returns:
      a fresh registration ready to receive options(Collection) or options(BiFunction)

    • forField

      public static <T, C extends com.vaadin.flow.component.Component> ValueOptions<T> forField(com.vaadin.flow.data.selection.MultiSelect<C,T> field)
      Starts an options registration for a multi-select field. Picked by the compiler over forField(HasValue) whenever the reference is statically typed as MultiSelect. The per-element type T flows through unchanged; resolved items are aggregated into a LinkedHashSet before HasValue.setValue(V).
      Type Parameters:
      T - the per-element type
      C - the field's source-component type
      Parameters:
      field - the multi-select field whose options the LLM may pick from, not null
      Returns:
      a fresh registration ready to receive options(Collection) or options(BiFunction)

    • options

      public ValueOptions<V> options(Collection<V> options)
      Sets a fixed item list. A defensive copy is taken so later mutations of the caller's collection have no effect. Use this when the option set is known up front and small enough to enumerate; for large or dynamic sets use options(BiFunction) instead. Mutually exclusive with options(BiFunction) — calling either clears the other.
      Parameters:
      options - the items the LLM may pick from, not null and not empty; each item is rendered to an LLM-facing label through the chain documented on the class JavaDoc
      Returns:
      this registration, for chaining
      Throws:
      IllegalArgumentException - if options is empty — registering an empty fixed list leaves the field un-fillable and is always a developer mistake

    • options

      public ValueOptions<V> options(BiFunction<String,Integer,List<V>> query)
      Sets a callback the controller invokes whenever the LLM needs to see the field's options. Use this when the option set is too large or too dynamic for a fixed list via options(Collection) — for example options that come from a database query or a remote service. The callback returns items the LLM may pick from; each item is rendered to an LLM-facing label through the chain documented on the class JavaDoc. Mutually exclusive with options(Collection) — calling either clears the other.
      Parameters:
      query - invoked with two arguments: a filter string the LLM picked, and a positive limit on how many items to return. Returns the matching items in display order, not null (an empty list signals "no matches" to the LLM)
      Returns:
      this registration, for chaining

    • itemLabelGenerator

      public ValueOptions<V> itemLabelGenerator(com.vaadin.flow.component.ItemLabelGenerator<V> generator)
      Sets the item-to-label function the controller uses to derive the LLM-facing label for each item. Optional — when unset, the controller falls back to the field's own getItemLabelGenerator() (read reflectively), then to String.valueOf(Object) as a last resort. Set this when the field's UI label generator is absent or when the LLM needs a different label from the UI (for example a code rather than a display name). Calling this multiple times overwrites the previous value.

      Two items rendering to the same label are resolvable but ambiguous: resolution picks the first matching item in registration order, and the controller logs a warning at registration when this happens. Emit unique labels per item if disambiguation matters.

      Parameters:
      generator - the per-item label generator, not null
      Returns:
      this registration, for chaining
      Since:
      25.3