Package io.jmix.aitoolsflowui.view.chat

Class AiChatFragment

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.Composite<com.vaadin.flow.component.orderedlayout.VerticalLayout>
io.jmix.flowui.fragment.Fragment<com.vaadin.flow.component.orderedlayout.VerticalLayout>
io.jmix.aitoolsflowui.view.chat.AiChatFragment
All Implemented Interfaces:
com.vaadin.flow.component.AttachNotifier, com.vaadin.flow.component.DetachNotifier, com.vaadin.flow.component.HasElement, com.vaadin.flow.component.HasStyle, FacetOwner, FragmentOwner, Serializable
@JsModule("./aitools/ai-chat-timeline-scroll.js") public class AiChatFragment extends Fragment<com.vaadin.flow.component.orderedlayout.VerticalLayout>
Encapsulates the "AI chat panel" UI — title row, message timeline, thinking indicator and the AiChatInputFragment composer — for an AiConversation. Designed to be embedded into any host view (the standard detail view, a side dialog, a chat hub view, custom layouts).

Ownership. The host supplies the conversation to display via setConversation(AiConversation) or setConversationId(UUID); the fragment loads that conversation's AiChatMessages itself — it does not rely on the messages collection being pre-fetched by the host — and reads/writes directly through DataManager.

See Also:

  • Field Details

  • Constructor Details

    • AiChatFragment

      public AiChatFragment()

  • Method Details

    • setConversation

      public void setConversation(@Nullable AiConversation conversation)
      Binds the fragment to a conversation.
      Parameters:
      conversation - conversation to bind

    • setConversationId

      public void setConversationId(@Nullable UUID conversationId)
      Binds the fragment to a conversation by id. A null id (or an id that no longer resolves) clears the fragment.
      Parameters:
      conversationId - conversation id to set

    • setAiAvatarIconSupplier

      public void setAiAvatarIconSupplier(@Nullable com.vaadin.flow.function.SerializableSupplier<com.vaadin.flow.component.Component> avatarIconSupplier)
      Sets a supplier of the avatar icon shown next to assistant messages, letting the host override the default add-on icon. The supplier must return a fresh component on every call.
      Parameters:
      avatarIconSupplier - supplier of the assistant avatar icon, or null to use the default

    • getAiAvatarIconSupplier

      public @Nullable com.vaadin.flow.function.SerializableSupplier<com.vaadin.flow.component.Component> getAiAvatarIconSupplier()
      Returns the custom assistant avatar icon supplier, if one was set.
      Returns:
      the avatar icon supplier, or null when the default icon is used

    • setReadOnly

      public void setReadOnly(boolean readOnly)
      Hides the composer and the title-edit button.
      Parameters:
      readOnly - true to hide the composer and the title-edit button

    • setTitleVisible

      public void setTitleVisible(boolean titleVisible)
      Hides the conversation title, for a host that already names the conversation in its own chrome — a view title, a tab, a dialog header — and would otherwise show the same name twice. The title row itself stays, carrying the title-edit button.

      AiChatFragment.TitleChangeEvent fires either way, so a hidden title still keeps the host's own title in sync with renames. The fragment stores no flag of its own, so the choice survives conversation reloads.

      Parameters:
      titleVisible - false to hide the conversation title; visible by default

    • addTitleChangeListener

      public com.vaadin.flow.shared.Registration addTitleChangeListener(com.vaadin.flow.component.ComponentEventListener<AiChatFragment.TitleChangeEvent> listener)
      Adds a listener notified whenever the displayed conversation title changes — when a conversation is bound and after it is renamed. Hosts use it to keep their own title in sync (page title, tab title).
      Parameters:
      listener - listener to add
      Returns:
      a registration for removing the listener

    • setTitleMode

      public void setTitleMode(@Nullable AiConversationTitleMode titleMode)
      Sets the generation title mode for this chat. Overrides the application-level jmix.aitools.ui.conversation-title-mode.
      Parameters:
      titleMode - the title mode for this chat, or null to use the application-level setting

    • focusMessageInput

      public void focusMessageInput()
      Moves keyboard focus to the message composer. No-op if the composer is currently disabled (e.g. while the assistant is still generating a response).

    • setMessageInputEnabled

      public void setMessageInputEnabled(boolean enabled)
      Enables or disables the message composer. The fragment disables it automatically while an assistant response is in flight and re-enables it on completion; hosts can call this for additional read-only states.
      Parameters:
      enabled - true to enable the composer, false to disable it

    • onEditConversationTitleBtnClick

      @Subscribe(id="editConversationTitleBtn", subject="clickListener") public void onEditConversationTitleBtnClick(com.vaadin.flow.component.ClickEvent<JmixButton> event)

    • isAwaitingResponse

      public boolean isAwaitingResponse()
      Whether an assistant response is currently being generated for the bound conversation. Hosts can use this to warn the user before closing — the background task is scoped to the host view and is cancelled (losing the answer) when the view detaches.
      Returns:
      true while an assistant response is being generated

    • sendMessage

      public void sendMessage(@Nullable String userMessage)
      Programmatic entry point to send a user message: persists it, appends it to the timeline, shows the thinking indicator, disables the composer and runs the assistant. Used by the composer's submit handler and by hosts that start a conversation with an initial prompt (the chat-hub flow).
      Parameters:
      userMessage - message text to send; a null or blank value is ignored

    • onReady

      @Subscribe public void onReady(Fragment.ReadyEvent event)

    • applyAutoTitle

      protected void applyAutoTitle(String trimmedMessage)
      Titles the conversation by its first message according to the effective AiConversationTitleMode.
      Parameters:
      trimmedMessage - the trimmed first user message

    • applyFirstMessageTitle

      protected @Nullable String applyFirstMessageTitle(String trimmedMessage)

    • startTitleGeneration

      protected void startTitleGeneration(String trimmedMessage, String expectedTitle)

    • reflectGeneratedTitle

      protected void reflectGeneratedTitle(UUID conversationId, String expectedTitle, @Nullable String appliedTitle)
      Shows the generated title, which is already persisted, unless the fragment was detached or the conversation was renamed meanwhile.
      Parameters:
      conversationId - id of the conversation that was titled
      expectedTitle - first-message title the conversation must still carry
      appliedTitle - the generated title, or null when nothing was applied

    • resolveTitleMode

      protected AiConversationTitleMode resolveTitleMode()

    • processUserMessage

      protected void processUserMessage(AiChatMessage savedUserMessage)

    • handleAssistantResponseDone

      protected void handleAssistantResponseDone(@Nullable AiChatMessage finalMessage)

    • markFreshAssistantItem

      protected void markFreshAssistantItem(UUID assistantMessageId)
      Locates the assistant item that just landed in the container after the post-LLM reload and stamps it with the "fresh" flag, triggering a single-row re-render via CollectionContainer.replaceItem(E).
      Parameters:
      assistantMessageId - id of the assistant message to mark as fresh

    • showAssistantProcessingError

      protected void showAssistantProcessingError()

    • showThinkingIndicator

      protected void showThinkingIndicator()

    • removeThinkingIndicator

      protected void removeThinkingIndicator()

    • appendThinkingStatusUpdate

      protected void appendThinkingStatusUpdate(@Nullable AiToolStatusUpdate statusUpdate)

    • refreshAll

      protected void refreshAll()

    • applyConversationTitleText

      protected void applyConversationTitleText(@Nullable String title)

    • warnIfAiUnavailable

      protected void warnIfAiUnavailable()

    • loadMessages

      protected Collection<AiChatMessage> loadMessages()
      Loads all messages of the bound conversation, oldest first. Empty when no conversation is bound or it has not been persisted yet.
      Returns:
      the bound conversation's messages, oldest first; empty if none

    • forceMessageInputFocus

      protected void forceMessageInputFocus()

    • refreshComposerVisibility

      protected void refreshComposerVisibility()

    • appendTimelineItem

      protected void appendTimelineItem(TimelineItem item)

    • refreshTimelineItem

      protected void refreshTimelineItem(TimelineItem item)

    • scrollToBottom

      protected void scrollToBottom()
      Scrolls the timeline to the latest row, forcing the move regardless of where the user is currently looking. Use for discrete, user-initiated events (opening a conversation, sending a message, the assistant's final answer) where the bottom must be shown.

    • scrollToBottom

      protected void scrollToBottom(boolean force)
      Scrolls the timeline to the latest row.
      Parameters:
      force - when true, always scrolls to the bottom and resets the "stick to bottom" intent. When false, scrolls only if the user is already at (or near) the bottom — used for streaming status updates so a user who scrolled up to read is not yanked back down on every minor update.

    • createTransientAssistantMessage

      protected AiChatMessage createTransientAssistantMessage(String content)

    • createTimelineStatus

      protected TimelineItemStatus createTimelineStatus(AiToolStatusUpdate statusUpdate)

    • loadConversation

      protected @Nullable AiConversation loadConversation(UUID conversationId)

    • openTitleEditDialog

      protected void openTitleEditDialog()

    • validateTitle

      protected ValidationErrors validateTitle(InputDialog.ValidationContext context)