Package com.flowingcode.vaadin.addons.chatassistant

Class ChatAssistant<T extends Message>

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.HtmlComponent
com.vaadin.flow.component.HtmlContainer
com.vaadin.flow.component.html.Div
com.flowingcode.vaadin.addons.chatassistant.ChatAssistant<T>
All Implemented Interfaces:
AttachNotifier, ClickNotifier<Div>, DetachNotifier, HasComponents, HasElement, HasEnabled, HasOrderedComponents, HasSize, HasStyle, HasText, Serializable
@JsModule("./fc-chat-assistant-movement.js") @JsModule("./fc-chat-assistant-resize.js") @CssImport("./styles/fc-chat-assistant-style.css") @Tag("animated-fab") public class ChatAssistant<T extends Message> extends Div
Component that allows to create a floating chat button that will open a chat window that can be used to provide a chat assistant feature.

Only one ChatAssistant is supported per UI: the FAB and chat window are UI-level surfaces. If a second instance is attached to the same UI it stays inactive and hidden (a warning is logged) instead of competing with the already-attached instance.

Author:
mmlopez
See Also:

  • Field Details

    • fabIcon

      protected Component fabIcon

    • fab

      protected final Button fab

    • unreadBadge

      protected final Div unreadBadge

    • fabWrapper

      protected final Div fabWrapper

    • chatWindow

      protected final Popover chatWindow

    • overlay

      protected final Div overlay

    • container

      protected final VerticalLayout container

    • DEFAULT_FAB_SIZE

      protected static final int DEFAULT_FAB_SIZE
      See Also:

    • DEFAULT_FAB_ICON_SIZE

      protected static final int DEFAULT_FAB_ICON_SIZE
      See Also:

    • DEFAULT_FAB_MARGIN

      protected static final int DEFAULT_FAB_MARGIN
      See Also:

    • DEFAULT_RESIZER_SIZE

      protected static final int DEFAULT_RESIZER_SIZE
      See Also:

    • DEFAULT_MAX_RESIZER_SIZE

      protected static final int DEFAULT_MAX_RESIZER_SIZE
      See Also:

    • DEFAULT_DRAG_SENSITIVITY

      protected static final int DEFAULT_DRAG_SENSITIVITY
      See Also:

  • Constructor Details

    • ChatAssistant

      public ChatAssistant(List<T> messages, boolean markdownEnabled)
      Creates a ChatAssistant with the given initial messages, using the defaults for every other setting. The messages are copied defensively: later changes to the supplied list are not reflected, and the component's own updates do not leak back into it. Mutate the conversation through sendMessage(Message) rather than the supplied list.

      To configure multiple aspects at construction time, prefer ChatAssistant.builder().

      Parameters:
      messages - the initial messages
      markdownEnabled - flag to enable or disable markdown support

    • ChatAssistant

      public ChatAssistant()
      Creates a ChatAssistant with no messages, using the defaults for every setting.

      To configure multiple aspects at construction time, prefer ChatAssistant.builder().

    • ChatAssistant

      public ChatAssistant(boolean markdownEnabled)
      Creates a ChatAssistant with no messages, using the defaults for every other setting.

      To configure multiple aspects at construction time, prefer ChatAssistant.builder().

      Parameters:
      markdownEnabled - flag to enable or disable markdown support

  • Method Details

    • onAttach

      protected void onAttach(AttachEvent attachEvent)
      Overrides:
      onAttach in class Component

    • onDetach

      protected void onDetach(DetachEvent detachEvent)
      Overrides:
      onDetach in class Component

    • onMobileModeChange

      @ClientCallable protected void onMobileModeChange(boolean mobile)
      Receives mobile mode changes from the client when the viewport crosses the breakpoint.

    • onScreenSizeChange

      @ClientCallable protected void onScreenSizeChange(int key, boolean matches)
      Receives chat-window size threshold crossings from the client and dispatches to the matching listener.

    • onClick

      @ClientCallable protected void onClick()
      Toggles the chat window's opened state. Called from the client on FAB click.

    • addComponentRefreshedListener

      protected void addComponentRefreshedListener(String uniqueFlag, String executable, Serializable... parameters)
      Runs the given JavaScript once per component instance, using a flag on the element to avoid registering duplicate client-side listeners across refreshes.
      Parameters:
      uniqueFlag - a unique identifier for this registration
      executable - the JavaScript to execute
      parameters - parameters for the executable

    • setFabIcon

      public void setFabIcon(Component icon)
      Sets the icon for the floating action button. The icon's size is automatically adjusted to fit within the current FAB size.
      Parameters:
      icon - the icon component, it cannot be null

    • setFabIcon

      public void setFabIcon(Component icon, int size)
      Sets the icon for the floating action button with a custom size. The size is capped at the current FAB size.
      Parameters:
      icon - the icon component, it cannot be null
      size - the icon size in pixels, it must be greater than 0

    • addFabThemeVariants

      public void addFabThemeVariants(FabVariant... variants)
      Adds the given theme variants to the FAB. Color variants are applied to the underlying button and accumulate; the size variants FabVariant.SMALL and FabVariant.LARGE instead resize the FAB (and its icon) to a predefined diameter and are mutually exclusive, so if both are added the last one wins.
      Parameters:
      variants - the variants to add
      Since:
      5.1.0

    • removeFabThemeVariants

      public void removeFabThemeVariants(FabVariant... variants)
      Removes the given theme variants from the FAB. Removing the currently active size variant (FabVariant.SMALL/FabVariant.LARGE) resets the FAB to its default size.
      Parameters:
      variants - the variants to remove
      Since:
      5.1.0

    • setOpened

      public void setOpened(boolean opened)
      Sets the opened state of the chat window. If true, opens the window; if false, closes it.

    • open

      public void open()
      Opens the chat window.

    • close

      public void close()
      Closes the chat window.

    • isOpened

      public boolean isOpened()
      Returns true if the chat window is opened, false otherwise.

    • setWindowResizable

      public void setWindowResizable(boolean resizable)
      Sets whether the chat window is resizable.
      Parameters:
      resizable - whether the chat window can be resized
      Since:
      5.1.0

    • isWindowResizable

      public boolean isWindowResizable()
      Returns whether the chat window is resizable.
      Returns:
      true if the chat window is resizable
      Since:
      5.1.0

    • setResizeIndicatorsVisible

      public void setResizeIndicatorsVisible(boolean visible)
      Sets whether a small arrowhead is shown on each resize handle, pointing in that handle's resize direction, to hint where the chat window can be dragged. The indicators are subtle, hidden by default, and only shown on the handles that can currently be dragged given the window's position.
      Parameters:
      visible - whether the resize direction indicators are visible
      Since:
      5.1.0

    • isResizeIndicatorsVisible

      public boolean isResizeIndicatorsVisible()
      Returns true if the resize direction indicators are visible, false otherwise.
      Since:
      5.1.0

    • setFabMovable

      public void setFabMovable(boolean movable)
      Sets whether the FAB is movable. In ChatAssistantMode.DESKTOP mode this also becomes the preference restored when returning from ChatAssistantMode.MOBILE mode (which always forces the FAB non-movable). Has no effect while the FAB is not anchored to the viewport (see setFabAnchoredToViewport(boolean)), since a container-positioned FAB is never draggable.
      Parameters:
      movable - whether the FAB can be dragged
      Since:
      5.1.0

    • isFabMovable

      public boolean isFabMovable()
      Returns whether the FAB is currently movable. Only a FAB anchored to the viewport can be moved, and the FAB is not movable by default while in ChatAssistantMode.MOBILE mode.
      Returns:
      true if the FAB is currently movable
      Since:
      5.1.0

    • setFabAnchoredToViewport

      public void setFabAnchoredToViewport(boolean anchoredToViewport)
      Sets whether the FAB is anchored to the viewport. When true (the default) the FAB floats over the viewport; when false it is positioned within its container, so it can be placed inside a bounded element. A FAB that is not anchored to the viewport is not movable.
      Since:
      5.1.0

    • isFabAnchoredToViewport

      public boolean isFabAnchoredToViewport()
      Returns true if the FAB is anchored to the viewport, false if positioned within its container.
      Since:
      5.1.0

    • setFabPosition

      public void setFabPosition(FabPosition fabPosition)
      Moves the FAB to the given corner. This also becomes the position the FAB returns to when resetFabPosition() is called.
      Parameters:
      fabPosition - the corner to move the FAB to, it cannot be null
      Since:
      5.1.0

    • getFabPosition

      public FabPosition getFabPosition()
      Returns the FAB's configured corner.
      Since:
      5.1.0

    • resetFabPosition

      public void resetFabPosition()
      Moves the FAB back to its configured corner.
      Since:
      5.1.0

    • setWindowMinWidth

      public void setWindowMinWidth(String minWidth)
      Sets the chat window minimum width, the lower bound enforced while resizing.
      Parameters:
      minWidth - the minimum width as a CSS length (e.g. "150px")

    • setWindowMinWidth

      public void setWindowMinWidth(int minWidth)
      Sets the chat window minimum width, the lower bound enforced while resizing.
      Parameters:
      minWidth - the minimum width in px (e.g. 150)
      Since:
      5.1.0

    • setWindowMinHeight

      public void setWindowMinHeight(int minHeight)
      Sets the chat window minimum height, the lower bound enforced while resizing.
      Parameters:
      minHeight - the minimum height in px (e.g. 150)
      Since:
      5.1.0

    • setWindowMinHeight

      public void setWindowMinHeight(String minHeight)
      Sets the chat window minimum height, the lower bound enforced while resizing.
      Parameters:
      minHeight - the minimum height as a CSS length (e.g. "150px")

    • setWindowMaxWidth

      public void setWindowMaxWidth(String maxWidth)
      Sets the chat window maximum width, the upper bound enforced while resizing.
      Parameters:
      maxWidth - the maximum width as a CSS length

    • setWindowMaxWidth

      public void setWindowMaxWidth(int maxWidth)
      Sets the chat window maximum width, the upper bound enforced while resizing.
      Parameters:
      maxWidth - the maximum width in px (e.g. 150)
      Since:
      5.1.0

    • setWindowMaxHeight

      public void setWindowMaxHeight(String maxHeight)
      Sets the chat window maximum height, the upper bound enforced while resizing.
      Parameters:
      maxHeight - the maximum height as a CSS length

    • setWindowMaxHeight

      public void setWindowMaxHeight(int maxHeight)
      Sets the chat window maximum height, the upper bound enforced while resizing.
      Parameters:
      maxHeight - the maximum height in px (e.g. 150)
      Since:
      5.1.0

    • setWindowHeight

      public void setWindowHeight(String height)
      Sets the chat window's initial height. Prefer absolute or viewport-relative units (e.g. "400px", "60vh"); a percentage resolves against the popover, not the viewport, and may not behave as expected.
      Parameters:
      height - the height as a CSS length

    • setWindowHeight

      public void setWindowHeight(int height)
      Sets the chat window's initial height. Use absolute units (e.g. 400).
      Parameters:
      height - the height in px (e.g. 400)
      Since:
      5.1.0

    • setWindowWidth

      public void setWindowWidth(String width)
      Sets the chat window's initial width. Prefer absolute or viewport-relative units (e.g. "400px", "40vw"); a percentage resolves against the popover, not the viewport, and may not behave as expected.
      Parameters:
      width - the width as a CSS length

    • setWindowWidth

      public void setWindowWidth(int width)
      Sets the chat window's initial width. Use absolute units (e.g. 400).
      Parameters:
      width - the width in px (e.g. 400)
      Since:
      5.1.0

    • initializeHeader

      protected void initializeHeader()

    • initializeFooter

      protected void initializeFooter()

    • initializeContent

      protected void initializeContent(boolean markdownEnabled)

    • initializeChatWindow

      protected void initializeChatWindow()

    • setDataProvider

      public void setDataProvider(DataProvider<T,?> dataProvider)

    • setWhoIsTyping

      public void setWhoIsTyping(String whoIsTyping)
      Uses the provided string as the text shown over the message input to indicate that someone is typing.
      Parameters:
      whoIsTyping - string to be shown as an indication of someone typing

    • getWhoIsTyping

      public String getWhoIsTyping()
      Returns the current text shown over the message input to indicate that someone is typing.
      Returns:
      the current text or null if not configured

    • clearWhoIsTyping

      public void clearWhoIsTyping()
      Clears the text shown over the message input to indicate that someone is typing.

    • setSubmitListener

      public Registration setSubmitListener(ComponentEventListener<MessageInput.SubmitEvent> listener)
      Sets the SubmitListener that will be notified when the user submits a message on the underlying messageInput.
      Parameters:
      listener - the listener that will be notified when the SubmitEvent is fired
      Returns:
      registration for removal of the listener

    • refreshContent

      public void refreshContent()

    • sendMessage

      public void sendMessage(T message)
      Sends a message programmatically to the component. Should not be used when a custom DataProvider is used. Instead, just refresh the custom DataProvider.
      Parameters:
      message - the message to be sent programmatically

    • updateMessage

      public void updateMessage(T message)
      Updates a previously entered message.
      Parameters:
      message - the message to be updated

    • setMinimized

      @Deprecated(since="5.0.0") public void setMinimized(boolean minimized)
      Deprecated.
      use setOpened(boolean) instead
      Shows or hides chat window.
      Parameters:
      minimized - true for hiding the chat window and false for displaying it

    • isMinimized

      @Deprecated(since="5.0.0") public boolean isMinimized()
      Deprecated.
      use isOpened() instead
      Returns the visibility of the chat window.
      Returns:
      true if the chat window is minimized false otherwise

    • setHeaderComponent

      public void setHeaderComponent(Component component)
      Allows changing the header of the chat window.
      Parameters:
      component - to be used as a replacement for the header

    • getHeaderComponent

      public Component getHeaderComponent()
      Returns the current component configured as the header of the chat window.

    • setFooterComponent

      public void setFooterComponent(Component component)
      Allows changing the footer of the chat window.
      Parameters:
      component - to be used as a replacement for the footer, it cannot be null

    • getFooterComponent

      public Component getFooterComponent()
      Returns the current component configured as the footer of the chat window.
      Returns:
      component used as the footer of the chat window

    • scrollToIndex

      public void scrollToIndex(int position)
      Scrolls to the given position. Scrolls so that the element is shown at the start of the visible area whenever possible.

      If the index parameter exceeds current item set size the grid will scroll to the end.

      Parameters:
      position - zero based index of the item to scroll to in the current view.

    • scrollToStart

      public void scrollToStart()
      Scrolls to the first element.

    • scrollToEnd

      public void scrollToEnd()
      Scrolls to the last element of the list.

    • setMessagesRenderer

      public void setMessagesRenderer(Renderer<T> renderer)
      Allows changing the renderer used to display messages in the chat window.
      Parameters:
      renderer - the renderer to use for rendering Message objects, it cannot be null

    • setAvatarProvider

      @Deprecated(since="5.0.0", forRemoval=true) public void setAvatarProvider(SerializableSupplier<Avatar> avatarProvider)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use setFabIcon(Component) instead
      Sets the avatar provider that will be used to create the avatar
      Parameters:
      avatarProvider - the avatar provider that will be used to create the avatar

    • getUnreadMessages

      public int getUnreadMessages()
      Returns the number of unread messages displayed in the chat assistant.
      Returns:
      the number of unread messages

    • setUnreadMessages

      public void setUnreadMessages(int unreadMessages)
      Sets the number of unread messages shown on the FAB badge. The value is clamped to the 0–99 range; the badge is hidden when it is 0.
      Parameters:
      unreadMessages - the number of unread messages to set

    • setUnreadBadgeColors

      public void setUnreadBadgeColors(String background, String color)
      Sets the background and text color of the unread badge. If null or empty, the default values are used.
      Parameters:
      background - the background color of the unread badge
      color - the text color of the unread badge
      Since:
      5.1.0

    • setMode

      public void setMode(ChatAssistantMode mode)
      Sets the display mode programmatically. In ChatAssistantMode.MOBILE mode the chat window opens as a full-screen dialog and the FAB is not movable (dragging would compete with touch scrolling, and the full-screen dialog already covers the viewport); the desktop movable preference is preserved and restored when switching back. In ChatAssistantMode.DESKTOP mode the window opens as an anchored popover.

      When automatic switching is enabled (see setMobileModeSwitchingEnabled(boolean)), this value may be overridden the next time the viewport crosses the configured breakpoint. To keep full manual control, disable automatic switching first.

      Parameters:
      mode - the mode to switch to, it cannot be null
      Since:
      5.1.0

    • getMode

      public ChatAssistantMode getMode()
      Returns the current display mode.
      Since:
      5.1.0

    • setMode

      protected void setMode(ChatAssistantMode mode, boolean fromClient)
      Applies the given mode, reconciling the active surface and open state, and fires a ChatAssistant.ModeChangedEvent when the mode actually changes.
      Parameters:
      mode - the mode to switch to
      fromClient - whether the change originated from a client-side breakpoint crossing

    • setMobileMode

      public void setMobileMode(boolean mobileMode)
      Sets the mobile mode programmatically. Convenience wrapper over setMode(ChatAssistantMode).
      Parameters:
      mobileMode - true for ChatAssistantMode.MOBILE, false for ChatAssistantMode.DESKTOP
      Since:
      5.1.0

    • isMobileMode

      public boolean isMobileMode()
      Returns true if the component is currently in ChatAssistantMode.MOBILE mode.
      Since:
      5.1.0

    • addModeChangedListener

      public Registration addModeChangedListener(ComponentEventListener<ChatAssistant.ModeChangedEvent> listener)
      Adds a listener that is notified whenever the component switches between ChatAssistantMode.MOBILE and ChatAssistantMode.DESKTOP mode.
      Parameters:
      listener - the listener to add; it receives the mode the component switched to
      Returns:
      a registration for removing the listener
      Since:
      5.1.0

    • addScreenSizeListener

      public Registration addScreenSizeListener(Integer width, Integer height, ComponentEventListener<ChatAssistant.ScreenSizeEvent> listener)
      Adds a listener that is notified when the chat window's own size crosses the given threshold. At least one of width/height must be non-null; a null axis is not tracked. When both are given, the listener fires only when both are simultaneously satisfied (AND).

      The chat window only has a size while it is open, so the listener observes size changes (drag resize, setWindowWidth(java.lang.String)/setWindowHeight(java.lang.String), or viewport clamping) while open. On each open it is invoked once with the current state, then only when the size crosses the threshold. The threshold is inclusive: a window exactly at the threshold counts as above it (ChatAssistant.ScreenSizeEvent.isAboveThreshold() is true). Each listener only receives events for its own threshold.

      Parameters:
      width - the width threshold in pixels, or null to ignore width
      height - the height threshold in pixels, or null to ignore height
      listener - the listener to add
      Returns:
      a registration for removing the listener
      Since:
      5.1.0

    • getMobileBreakpoint

      public int getMobileBreakpoint()
      Returns the maximum screen width, in pixels, below which mobile mode is activated automatically.
      Returns:
      the breakpoint in pixels
      Since:
      5.1.0

    • setMobileModeSwitchingEnabled

      public void setMobileModeSwitchingEnabled(boolean enabled)
      Enables or disables automatic switching between mobile and desktop mode based on the configured breakpoint. Automatic switching is disabled by default; it is enabled either by defining a breakpoint in the constructor or by calling this method with true. Enable it only after preparing the mobile experience (e.g. providing a way to close the full-screen dialog).

      When disabled, the component is left in whatever mode it is currently in (freeze), and the mode can only be changed manually via setMode(ChatAssistantMode). When enabled, the breakpoint is evaluated against the current viewport width. If no breakpoint was configured, the default (768px) is used.

      Parameters:
      enabled - true to switch automatically on viewport changes, false to freeze
      Since:
      5.1.0

    • isMobileModeSwitchingEnabled

      public boolean isMobileModeSwitchingEnabled()
      Returns whether automatic switching between mobile and desktop mode is enabled.
      Returns:
      true if automatic switching is enabled
      Since:
      5.1.0