@talkjs/web-components 0.1.5 → 0.1.7

package/default.d.ts

@@ -1,4 +1,7 @@
 import { AudioBlock } from '@talkjs/core';
+import { ContentBlock } from '@talkjs/core';
+import { ConversationSearch } from '@talkjs/core';
+import { ConversationSearchState } from '@talkjs/core';
 import { ConversationSnapshot } from '@talkjs/core';
 import { EditMessageParams } from '@talkjs/core';
 import { EditTextMessageParams } from '@talkjs/core';
@@ -8,11 +11,14 @@ import { GenericFileBlock } from '@talkjs/core';
 import { ImageBlock } from '@talkjs/core';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { LocationBlock } from '@talkjs/core';
+import { MessageSearch } from '@talkjs/core';
+import { MessageSearchState } from '@talkjs/core';
 import { MessageSnapshot } from '@talkjs/core';
 import { ParticipantSnapshot } from '@talkjs/core';
 import * as Preact from 'preact/compat';
 import * as React_2 from 'react';
 import { ReferencedMessageSnapshot } from '@talkjs/core';
+import { SearchMessageSnapshot } from '@talkjs/core';
 import { SendMessageParams } from '@talkjs/core';
 import { SendTextMessageParams } from '@talkjs/core';
 import { TalkSession } from '@talkjs/core';
@@ -109,6 +115,8 @@ export declare interface AudioBlockProps {
  * Also, it has some additional settings that let us turn the sound wave display
  * into a series of nice rounded bars. Less signal, but also less distraction. I
  * kinda like it!
+ *
+ * @public
  */
 export declare function AudioPlayer({ src, onError, filename, className, }: AudioPlayerProps): JSX_2.Element;
 
@@ -153,6 +161,247 @@ export declare interface AvatarProps {
     photoUrl: string;
 }
 
+/**
+ * An event object dispatched by the
+ * {@link ChatboxProps.onBackButtonClick} event.
+ *
+ * @public
+ */
+export declare interface BackButtonClickEvent {
+    currentUser: UserSnapshot;
+}
+
+/**
+ * @public
+ */
+export declare interface BaseChatboxProps {
+    /**
+     * @hidden
+     */
+    className?: string;
+    /**
+     * @hidden
+     */
+    style?: React_2.CSSProperties;
+    /**
+     * Your app's unique TalkJS ID. You can find it on the Settings page of the
+     * {@link https://talkjs.com/dashboard | TalkJS dashboard.}
+     */
+    appId: string;
+    /**
+     * The ID of the current user.
+     *
+     * @remarks
+     * If the given user ID doesn't exist, a "Something went wrong" message will
+     * be displayed.
+     */
+    userId: string;
+    /**
+     * The ID of the currently focused message.
+     *
+     * @remarks
+     * Whenever this value changes to a valid message ID, the relevant message
+     * will be scrolled into view.
+     *
+     * If you're using a modern web framework like React or Vue, also include an
+     * {@link onFocusMessage} prop where you'll update your local `focusedMessageId` state
+     * so that it stays in sync with the UI's internals.
+     *
+     * Note that updating the selected conversation through this prop **will not**
+     * trigger the {@link onFocusMessage} callback.
+     */
+    focusedMessageId?: string;
+    /**
+     * Lets you override theme components with your own implementations to
+     * customize them.
+     *
+     * @remarks
+     * See
+     * {@link https://talkjs.com/docs/UI_Components/React/Customization/#custom-theme-components | Custom theme components }
+     * for more info.
+     */
+    theme?: Partial<Theme>;
+    /**
+     * When true, pressing Enter will send a message.
+     *
+     * @remarks
+     * Defaults to `true`.
+     */
+    enterSendsMessage?: boolean;
+    /**
+     * Sets whether the chat header is visible.
+     *
+     * @remarks
+     * Defaults to `true`.
+     */
+    chatHeaderVisible?: boolean;
+    /**
+     * Sets whether the message input field is visible.
+     *
+     * @remarks
+     * Defaults to `true`.
+     */
+    messageFieldVisible?: boolean;
+    /**
+     *  Sets whether spellcheck is enabled in the message field.
+     *
+     * @remarks
+     * Defaults to `false`.
+     */
+    messageFieldSpellcheck?: boolean;
+    /**
+     * Adds custom placeholder text for the message input field.
+     *
+     * @remarks
+     * The default placeholder text is `"Say something..."`
+     */
+    messageFieldPlaceholder?: string;
+    /**
+     * Callback that triggers when the user deletes a message with the TalkJS UI.
+     *
+     * @param event - Event object describing the message deletion
+     */
+    onDeleteMessage?: (event: DeleteMessageEvent) => void;
+    /**
+     * Callback that triggers when the user sends a message with the TalkJS UI.
+     *
+     * @param event - Event object describing the message sending action
+     */
+    onSendMessage?: (event: SendMessageEvent) => void;
+    /**
+     * Callback that triggers when the user initiates an action that will require
+     * a permissions request from the browser, but right before actually
+     * requesting the permission from the browser.
+     *
+     * @remarks
+     * You can use this callback to inform the user that they will need to grant a
+     * browser permission in order to perform an action.
+     *
+     * @param request - Object describing the permission request
+     */
+    beforeBrowserPermissionPrompt?: (request: BrowserPermissionRequest) => void;
+    /**
+     * Callback that triggers when the user attempts to initiate an action that
+     * requires a specific browser permission, but that permission was not
+     * granted.
+     *
+     * @param event - Event object describing the missing permission
+     */
+    onMissingBrowserPermission?: (event: MissingBrowserPermissionEvent) => void;
+    /**
+     * This event fires when the user clicks an action button or an action Link
+     * inside a message.
+     *
+     * @remarks
+     * The event's `action` and `params` fields specify the name of action and its
+     * parameters, if any.
+     *
+     * See
+     * {@link https://talkjs.com/docs/Guides/Web_Components/Action_Buttons_Links/ | Action Buttons and Links }
+     * for more info.
+     */
+    onMessageAction?: (event: MessageActionEvent) => void;
+    /**
+     * Callback that triggers when a message is focused or unfocused.
+     *
+     * @param event - Event object describing the message focus action
+     *
+     * @remarks
+     * Note that updating the focused message through the
+     * {@link focusedMessageId} prop **will not** trigger this callback.
+     */
+    onFocusMessage?: (event: FocusMessageEvent) => void;
+    /**
+     * Arbitrary custom data passed down to the theme.
+     *
+     * @remarks
+     * Whatever data you pass here will be made available for use in theme
+     * components through {@link CommonChatboxProps.themeCustom} for Chatbox
+     * theme components and through
+     * {@link CommonConversationListProps.themeCustom} for ConversationList
+     * theme components.
+     */
+    themeCustom?: any;
+}
+
+/**
+ * @public
+ */
+export declare interface BaseConversationListProps {
+    /**
+     * @hidden
+     */
+    className?: string;
+    /**
+     * @hidden
+     */
+    style?: React_2.CSSProperties;
+    /**
+     * Your app's unique TalkJS ID. You can find it on the Settings page of the
+     * {@link https://talkjs.com/dashboard | TalkJS dashboard.}
+     */
+    appId: string;
+    /**
+     * The ID of the current user.
+     *
+     * @remarks
+     * If the given user ID doesn't exist, a "Something went wrong" message will
+     * be displayed.
+     */
+    userId: string;
+    /**
+     * The ID of the conversation currently selected in the list.
+     *
+     * @remarks
+     *
+     * Changing the value of this prop will cause the ConversationList UI to
+     * update.
+     *
+     * If you're using a modern web framework like React or Vue, also include an
+     * {@link onSelectConversation} prop where you'll update your local `selectedConversationId` state
+     * so that it stays in sync with the UI's internals.
+     *
+     * Note that updating the selected conversation through this prop **will not**
+     * trigger the {@link onSelectConversation} callback.
+     */
+    selectedConversationId?: string;
+    /**
+     * Lets you override theme components with your own implementations to
+     * customize them.
+     *
+     * @remarks
+     * See
+     * {@link https://talkjs.com/docs/UI_Components/React/Customization/#custom-theme-components | Custom theme components }
+     * for more info.
+     */
+    theme?: Partial<Theme>;
+    /**
+     * Callback that triggers when the user selects a conversation from the list.
+     *
+     * @param event - Event object containing the selected conversation
+     *
+     * @remarks
+     * Note that updating the selected conversation through the
+     * {@link selectedConversationId} prop **will not** trigger this callback.
+     *
+     * Use this callback to have an adjacent chatbox show the correct
+     * conversation. See
+     * {@link https://talkjs.com/docs/UI_Components/React/ConversationList/#respond-to-a-select-conversation-event | Respond to a select conversation event.}
+     */
+    onSelectConversation?: (event: SelectConversationEvent) => void;
+    /**
+     * Arbitrary custom data passed down to the theme.
+     *
+     * @remarks
+     * Whatever data you pass here will be made available for use in theme
+     * components through {@link CommonChatboxProps.themeCustom} for Chatbox
+     * theme components and through
+     * {@link CommonConversationListProps.themeCustom} for ConversationList
+     * theme components.
+     */
+    themeCustom?: any;
+}
+
 /**
  * @public
  */
@@ -229,33 +478,24 @@ export declare class ChatboxController {
     #private;
     /**
      * Deletes the message with the given ID.
-     *
-     * @param messageId
      */
     deleteMessage(messageId: string): Promise<void>;
     /**
      * Enable/disable editing of a given message.
      *
-     * @param messageId When `null` is provided, editing mode will be disabled
+     * @param messageId - When `null` is provided, editing mode will be disabled
      */
     setEditing(messageId: string | null): void;
     /**
      * Edit the message with the given ID.
-     *
-     * @param messageId
-     * @param params
      */
     editMessage(messageId: string, params: EditTextMessageParams | EditMessageParams): Promise<void>;
     /**
      * Send a text message to the current conversation.
-     *
-     * @param params
      */
     sendMessage(params: SendTextMessageParams | SendMessageParams): Promise<void>;
     /**
      * Send a file message to the current conversation.
-     *
-     * @param message
      */
     sendFileMessage(params: {
         fileToken: FileToken;
@@ -263,8 +503,6 @@ export declare class ChatboxController {
     }): Promise<void>;
     /**
      * Send a location message to the current conversation.
-     *
-     * @param message
      */
     sendLocationMessage(message: {
         location: Coordinates;
@@ -285,8 +523,9 @@ export declare class ChatboxController {
      *
      * @param messageId - The ID of the message you want to toggle the reaction on. This message must exist in the current conversation.
      * @param emoji - The emoji you want to toggle. Must be a string of a single unicode emoji glyph, eg `"🎉"`.
+     * @param force - If included, turns the toggle into a one way-only operation. Setting to `true` will add this reaction for the current user and setting to `false` will remove it if it was already added for the current user
      */
-    toggleReaction(messageId: string, emoji: string): Promise<void>;
+    toggleReaction(messageId: string, emoji: string, force?: boolean): Promise<void>;
     /**
      * Get the plaintext from the message field
      *
@@ -295,13 +534,63 @@ export declare class ChatboxController {
     getMessageFieldText(): string;
     /**
      * Set the plaintext in the message field
-     * @param text
      */
     setMessageFieldText(text: string): void;
     /**
      * Focus the message field
      */
     focusMessageField(): void;
+    /**
+     * Toggles whether the `ChatSearchBox` should be visible or not.
+     *
+     * @param force - If included, turns the toggle into a one way-only operation. Setting to `true` will enable the search box, and setting to `false` will disable it.
+     */
+    toggleSearchBox(force?: boolean): void;
+    /**
+     * Scrolls to the message with the given messageId and marks it as "focused",
+     * meaning the {@link CommonChatboxProps.focusedMessage} field will be
+     * populated.
+     *
+     * If `null` is passed the `focusedMessage` will be cleared.
+     *
+     * @returns `true` if a message with the given ID was found and was scrolled
+     * to.
+     */
+    focusMessage(messageId: string | null): Promise<MessageSnapshot | null>;
+    /**
+     * Highlights certain strings in messages
+     *
+     * @remarks
+     * The TalkJS search feature includes the ability to highlight certain strings in messages. Call
+     * this method to highlight certain strings without having the user invoke the search feature.
+     * Call again with an empty array to disable highlighting.
+     *
+     * Note: like the search feature, this option only works on the Growth plan and up.
+     */
+    setHighlightedStrings(words: string[]): void;
+    /**
+     * Searches for a message upwards that contains highlighted strings.
+     * If a message is found, the UI will scroll that message into view.
+     *
+     * Strings are highlighted when you explicitly call {@link setHighlightedStrings} or
+     * when a user types a word/phrase into the `ChatSearchBox`.
+     *
+     * @returns A promise resolving to a {@link MessageSnapshot} if a message was found. The promise
+     * resolves to `null` otherwise.
+     */
+    jumpToPreviousHighlight(): Promise<MessageSnapshot | null>;
+    /**
+     * Searches for messages downwards that contains highlighted strings.
+     * If a message is found, the UI will scroll that message into view.
+     *
+     * Strings are highlighted when you explicitly call {@link setHighlightedStrings} or
+     * when a user types a word/phrase into the `ChatSearchBox`.
+     *
+     * @returns A promise resolving to a {@link MessageSnapshot} if a message was found. The promise
+     * resolves to `null` otherwise.
+     */
+    jumpToNextHighlight(): Promise<MessageSnapshot | null>;
+    clickBackButton(): void;
 }
 
 /**
@@ -316,37 +605,38 @@ export declare const ChatboxElement: new () => TalkJS.ChatboxElement;
 /**
  * @public
  */
-export declare interface ChatboxProps {
+export declare interface ChatboxProps extends BaseChatboxProps {
     /**
-     * @hidden
-     */
-    className?: string;
-    /**
-     * @hidden
-     */
-    style?: React_2.CSSProperties;
-    /**
-     * Your app's unique TalkJS ID. You can find it on the Settings page of the
-     * {@link https://talkjs.com/dashboard | TalkJS dashboard.}
-     */
-    appId: string;
-    /**
-     * The ID of the current user.
+     * The ID of the conversation to display.
      *
      * @remarks
-     * If the given user ID doesn't exist, a "Something went wrong" message will
-     * be displayed.
+     * If the conversation doesn't exist or if the current user isn't a
+     * participant of the current conversation, a "Conversation not found" message will be
+     * displayed (after a timeout). If you create the conversation in parallel (eg
+     * via the REST API or via the Data API), it will show in the chatbox
+     * automatically. This means that you can safely point a chatbox at a
+     * conversation that might not yet exist. This way the chatbox UI and the
+     * conversation can load in parallel, which results in snappier UX.
+     *
+     * Passing `null` deselects the current conversation and shows an empty panel.
+     * This may be useful for Inbox-like scenarios where you want to keep the
+     * chatbox loaded, without showing a conversation.
+     *
+     * In the background, the Chatbox keeps active subscriptions to recent
+     * conversations, so that switching back and forth between conversations has
+     * snappy UX.
      */
-    userId: string;
+    conversationId: string | null;
     /**
-     * The ID of the conversation to display.
+     * Fired when the back button in the chat header is clicked.
      *
      * @remarks
-     * If the conversation doesn't exist or if the current user isn't a
-     * participant of the current conversation, a "Chat not found" message will be
-     * displayed.
+     * By default this back button is only shown inside an inbox on small screens.
+     * You can change this behavior in the ChatHeader theme.
+     *
+     * @public
      */
-    conversationId: string;
+    onBackButtonClick?: (event: BackButtonClickEvent) => void;
     /**
      * A token to authenticate the session with.
      *
@@ -371,107 +661,6 @@ export declare interface ChatboxProps {
      * for details and examples.
      */
     tokenFetcher?: () => string | Promise<string>;
-    /**
-     * Lets you override theme components with your own implementations to
-     * customize them.
-     *
-     * @remarks
-     * See
-     * {@link https://talkjs.com/docs/UI_Components/React/Customization/#custom-theme-components | Custom theme components }
-     * for more info.
-     */
-    theme?: Partial<Theme>;
-    /**
-     * When true, pressing Enter will send a message.
-     *
-     * @remarks
-     * Defaults to `true`.
-     */
-    enterSendsMessage?: boolean;
-    /**
-     * Sets whether the chat header is visible.
-     *
-     * @remarks
-     * Defaults to `true`.
-     */
-    chatHeaderVisible?: boolean;
-    /**
-     * Sets whether the message input field is visible.
-     *
-     * @remarks
-     * Defaults to `true`.
-     */
-    messageFieldVisible?: boolean;
-    /**
-     *  Sets whether spellcheck is enabled in the message field.
-     *
-     * @remarks
-     * Defaults to `false`.
-     */
-    messageFieldSpellcheck?: boolean;
-    /**
-     * Adds custom placeholder text for the message input field.
-     *
-     * @remarks
-     * The default placeholder text is `"Say something..."`
-     */
-    messageFieldPlaceholder?: string;
-    /**
-     * Callback that triggers when the user deletes a message with the TalkJS UI.
-     *
-     * @param event Event object describing the message deletion
-     */
-    onDeleteMessage?: (event: DeleteMessageEvent) => void;
-    /**
-     * Callback that triggers when the user sends a message with the TalkJS UI.
-     *
-     * @param event Event object describing the message sending action
-     */
-    onSendMessage?: (event: SendMessageEvent) => void;
-    /**
-     * Callback that triggers when the user initiates an action that will require
-     * a permissions request from the browser, but right before actually
-     * requesting the permission from the browser.
-     *
-     * @remarks
-     * You can use this callback to inform the user that they will need to grant a
-     * browser permission in order to perform an action.
-     *
-     * @param request Object describing the permission request
-     */
-    beforeBrowserPermissionPrompt?: (request: BrowserPermissionRequest) => void;
-    /**
-     * Callback that triggers when the user attempts to initiate an action that
-     * requires a specific browser permission, but that permission was not
-     * granted.
-     *
-     * @param event Event object describing the missing permission
-     */
-    onMissingBrowserPermission?: (event: MissingBrowserPermissionEvent) => void;
-    /**
-     * This event fires when the user clicks an action button or an action Link
-     * inside a message.
-     *
-     * @remarks
-     * The event's `action` and `params` fields specify the name of action and its
-     * parameters, if any.
-     *
-     * See
-     * {@link https://talkjs.com/docs/Guides/Web_Components/Action_Buttons_Links/ | Action Buttons and Links }
-     * for more info.
-     */
-    onMessageAction?: (event: MessageActionEvent) => void;
-    /**
-     * Arbitrary custom data passed down to the theme.
-     *
-     * @remarks
-     * Whatever data you pass here will be made available for use in theme
-     * components through {@link CommonChatboxProps.themeCustom} for Chatbox
-     * theme components and through
-     * {@link CommonConversationListProps.themeCustom} for ConversationList
-     * theme components.
-     */
-    themeCustom?: any;
 }
 
 /**
@@ -494,6 +683,36 @@ export declare interface ChatHeaderProps {
     permissions: UserPermissions;
 }
 
+/**
+ * @public
+ */
+export declare interface ChatSearchBoxProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
+    common: CommonChatboxProps;
+}
+
+/**
+ * The current state of the chat search
+ *
+ * @remarks
+ * This type can have one of these values:
+ *
+ * - `"hidden"` - The {@link Theme.ChatSearchBox} is not shown to the user.
+ *
+ * - `"visible"` - The {@link Theme.ChatSearchBox} is shown to the user.
+ *
+ * - `"searching"` - Waiting for more older messages to be loaded from the server.
+ *
+ * - `"noResults"` - There are 0 messages that contain the phrase entered by the user.
+ *
+ * - `"noMoreResults"` - There are not any more messages in the given direction that contain a match for the phrase entered by the user.
+ *
+ * @public
+ */
+export declare type ChatSearchState = "hidden" | "visible" | "searching" | "noResults" | "noMoreResults";
+
 /**
  * A collection of props that's shared by every themed component used in the Chatbox UI.
  *
@@ -530,21 +749,40 @@ export declare interface CommonChatboxProps {
      */
     device: DeviceFeatures;
     /**
-     * The theme object that the chatbox's is currently using.
+     * The theme object that the chatbox is currently using.
      */
     theme: Theme;
+    /**
+     * The ID of the conversation displayed in the chatbox.
+     *
+     * @remarks
+     * Prefer this field instead of `common.conversation.id` (which always has the
+     * same value), as this enables an optimization that prevents needless
+     * re-renders.
+     */
+    conversationId: string;
     /**
      * The conversation displayed in the chatbox.
      */
     conversation: ConversationSnapshot;
     /**
-     * Tells you which participants are currently typing
+     * Tells you which participants are currently typing.
      */
     typing: TypingSnapshot;
     /**
      * The underlying TalkJS session object that handles sending and receiving chat data.
      */
     session: TalkSession;
+    /**
+     * The message that was most recently scrolled into view as a result of calling one of the following methods:
+     * {@link ChatboxController.focusMessage}, {@link ChatboxController.jumpToPreviousHighlight}
+     * or {@link ChatboxController.jumpToNextHighlight}
+     */
+    focusedMessage: MessageSnapshot | null;
+    /**
+     * The current state of the chat search
+     */
+    chatSearchState: ChatSearchState;
 }
 
 /**
@@ -579,7 +817,7 @@ export declare interface CommonConversationListProps {
      */
     device: DeviceFeatures;
     /**
-     * The theme object that the chatbox's is currently using.
+     * The theme object that the conversation list is currently using.
      */
     theme: Theme;
     /**
@@ -642,7 +880,8 @@ export declare interface ConversationImageProps {
 export declare class ConversationListController {
     #private;
     /**
-     * Select a conversation.
+     * Selects a conversation with the given ID, or de-select a conversation by
+     * passing `null`.
      *
      * @remarks
      * This method is called from the theme's ConversationListItem component when
@@ -656,8 +895,11 @@ export declare class ConversationListController {
      * to the {@link ConversationListProps.selectedConversationId} prop
      * instead, as that lets you keep your local state in sync with the props
      * passed to the conversation list.
+     *
+     * You can also optionally pass a `focusedMessageId` to signify the intent
+     * of scrolling to a particular message within that conversation.
      */
-    selectConversation(conversationId: string): void;
+    selectConversation(conversationId: string | null, focusedMessageId?: string): Promise<void>;
 }
 
 /**
@@ -671,59 +913,29 @@ export declare class ConversationListController {
  */
 export declare const ConversationListElement: new () => TalkJS.ConversationListElement;
 
-export declare interface ConversationListItemProps {
-    /**
-     * A collection of objects which are passed to all ConversationList theme components.
-     */
-    common: CommonConversationListProps;
-    /**
-     * The conversation that's being displayed.
-     */
-    conversation: ConversationSnapshot;
-    /**
-     * If `true`, this conversation is the currently selected one in the
-     * conversation list.
-     */
-    isSelected: boolean;
-}
-
 /**
  * @public
  */
-export declare interface ConversationListProps {
-    /**
-     * @hidden
-     */
-    className?: string;
-    /**
-     * @hidden
-     */
-    style?: React_2.CSSProperties;
-    /**
-     * Your app's unique TalkJS ID. You can find it on the Settings page of the
-     * {@link https://talkjs.com/dashboard | TalkJS dashboard.}
-     */
-    appId: string;
+export declare interface ConversationListItemProps {
     /**
-     * The ID of the current user.
-     *
-     * @remarks
-     * If the given user ID doesn't exist, a "Something went wrong" message will
-     * be displayed.
+     * A collection of objects which are passed to all ConversationList theme components.
      */
-    userId: string;
+    common: CommonConversationListProps;
     /**
-     * The ID of the conversation currently selected in the list.
-     *
-     * @remarks
-     *
-     * Changing the value of this prop will cause the ConversationList UI to
-     * update.
-     *
-     * Note that updating the selected conversation through this prop **will not**
-     * trigger the {@link onSelectConversation} callback.
+     * The conversation that's being displayed.
      */
-    selectedConversationId?: string;
+    conversation: ConversationSnapshot;
+    /**
+     * If `true`, this conversation is the currently selected one in the
+     * conversation list.
+     */
+    isSelected: boolean;
+}
+
+/**
+ * @public
+ */
+export declare interface ConversationListProps extends BaseConversationListProps {
     /**
      * A token to authenticate the session with.
      *
@@ -748,43 +960,12 @@ export declare interface ConversationListProps {
      *  for details and examples.
      */
     tokenFetcher?: () => string | Promise<string>;
-    /**
-     * Lets you override theme components with your own implementations to
-     * customize them.
-     *
-     * @remarks
-     * See
-     * {@link https://talkjs.com/docs/UI_Components/React/Customization/#custom-theme-components | Custom theme components }
-     * for more info.
-     */
-    theme?: Partial<Theme>;
-    /**
-     * Callback that triggers when the user selects a conversation from the list.
-     *
-     * @param event Event object containing the selected conversation
-     *
-     * @remarks
-     * Note that updating the selected conversation through the
-     * {@link selectedConversationId} prop **will not** trigger this callback.
-     *
-     * Use this callback to have an adjacent chatbox show the correct
-     * conversation. See
-     * {@link https://talkjs.com/docs/UI_Components/React/ConversationList/#respond-to-a-select-conversation-event | Respond to a select conversation event.}
-     */
-    onSelectConversation?: (event: SelectConversationEvent) => void;
-    /**
-     * Arbitrary custom data passed down to the theme.
-     *
-     * @remarks
-     * Whatever data you pass here will be made available for use in theme
-     * components through {@link CommonChatboxProps.themeCustom} for Chatbox
-     * theme components and through
-     * {@link CommonConversationListProps.themeCustom} for ConversationList
-     * theme components.
-     */
-    themeCustom?: any;
 }
 
+export { ConversationSearch }
+
+export { ConversationSearchState }
+
 export { ConversationSnapshot }
 
 /**
@@ -838,18 +1019,52 @@ export declare interface DeviceFeatures {
     isMobile: boolean;
 }
 
+/**
+ * @public
+ */
 export declare function Editor({ placeholder, disabled, className, characterLimit, spellcheck, }: EditorProps): JSX_2.Element;
 
+/**
+ * Lets you query and control the message editor.
+ *
+ * @remarks
+ * Available inside the {@link https://talkjs.com/docs/UI_Components/Theme/Theme_components/MessageField | MessageField} theme component.
+ * Connects with the internals of the {@link https://talkjs.com/docs/UI_Components/Theme/System_components/Editor | Editor} system component.
+ *
+ * @public
+ */
 export declare interface EditorController {
-    isTyping: boolean;
+    /**
+     * True if the maximum message length has been exceeded.
+     *
+     * @remarks
+     * Sending should be disabled when true
+     */
     atTextLimit: boolean;
+    /**
+     * True if the editor is empty.
+     */
     isEmpty: boolean;
+    /**
+     * The number of characters in the editor.
+     *
+     * @remarks
+     * Note that this is an estimation, and it may slightly exceed the actual number of characters in the editor.
+     */
     characterCount: number;
+    /**
+     * Whether the emoji picker should be shown. Toggle with {@link toggleEmojiPicker}.
+     */
     showEmojiPicker: boolean;
+    /** Send the message and clear the editor */
     send(): void;
+    /** Open the "share location" dialog */
     shareLocation(): void;
+    /** Open the "attach file" dialog */
     attachFile(): void;
+    /** Open or close the emoji picker */
     toggleEmojiPicker(): void;
+    /** Start recording a voice message */
     recordVoiceMessage(): void;
 }
 
@@ -888,6 +1103,9 @@ export declare interface EditorProps {
     className?: string;
 }
 
+/**
+ * @public
+ */
 export declare function EmojiPicker(props: EmojiPickerProps): JSX_2.Element;
 
 /**
@@ -901,9 +1119,7 @@ export declare interface EmojiPickerProps {
 }
 
 /**
- * Shows a bar with emoji suggestions when the user types eg `:bla`. Shown if `query` is non-empty.
- *
- * Uses the IndexedDB-backed emoji database from "emoji-picker-element".
+ * @public
  */
 export declare function EmojiSuggestBar(props: EmojiSuggestBarProps): JSX_2.Element;
 
@@ -948,6 +1164,18 @@ export declare interface FileBlockProps {
     downloadUrl?: string;
 }
 
+/**
+ * An event object dispatched by the {@link ChatboxProps.onFocusMessage} event.
+ *
+ * @public
+ */
+export declare interface FocusMessageEvent {
+    /**
+     * The message that was focused (or `null` if the focus was cleared)
+     */
+    message: MessageSnapshot | null;
+}
+
 /**
  * Displays the given number of seconds in a human-friendly MM:SS or HH:MM:SS
  * format; whichever's shorter.
@@ -992,6 +1220,79 @@ export declare function getPhotoUrlWithFallback(user: UserSnapshot): string;
  */
 export declare function getRandomColor(id: string): string;
 
+/**
+ * Props passed to the GlobalSearchBox theme component.
+ *
+ * @public
+ */
+export declare interface GlobalSearchBoxProps {
+    /**
+     * A collection of objects which are passed to all ConversationList theme components.
+     */
+    common: CommonConversationListProps;
+    /**
+     * Marks the given message ID or conversation ID as the currently selected search result.
+     */
+    query: string;
+    /**
+     * Sets a search query for the global search
+     */
+    setQuery(query: string): void;
+    /**
+     * Cancels the current search
+     */
+    cancel(): void;
+}
+
+/**
+ * Props passed to the GlobalSearchResultHeader theme component.
+ *
+ * @public
+ */
+export declare interface GlobalSearchResultHeaderProps {
+    /**
+     * A collection of objects which are passed to all ConversationList theme components.
+     */
+    common: CommonConversationListProps;
+    /**
+     * Whether this header is displayed above conversation search results or message search results.
+     */
+    type: "messages" | "conversations";
+    /**
+     * True if more search results can be loaded.
+     */
+    canLoadMore: boolean;
+    /**
+     * Call this function to load more search results.
+     */
+    loadMore(): void;
+}
+
+export declare interface GlobalSearchResultItemProps {
+    /**
+     * A collection of objects which are passed to all GlobalSearchResultItem theme components.
+     */
+    common: CommonConversationListProps;
+    /**
+     * The conversation that's being displayed.
+     */
+    conversation: ConversationSnapshot;
+    /**
+     * The message containing the result item. If it's missing, then the search
+     * match is on the conversation itself.
+     */
+    message?: MessageSnapshot;
+    /**
+     * If `true`, this search result is the currently selected one.
+     */
+    isSelected: boolean;
+}
+
+/**
+ * @public
+ */
+export declare type GlobalSearchStatus = "idle" | "searching" | "noResults";
+
 /**
  * @public
  */
@@ -1011,6 +1312,22 @@ export declare interface GroupChatImageProps {
     participants: ParticipantSnapshot[];
 }
 
+export declare function Highlightable({ text, className }: HighlightableProps): React_2.DetailedReactHTMLElement<{
+    className: string;
+}, HTMLElement>;
+
+/**
+ * @public
+ */
+export declare interface HighlightableProps {
+    /** The text to display */
+    text: string;
+    /**
+     * @hidden
+     */
+    className?: string;
+}
+
 /**
  * Parses a JSX-like React string into a React element tree.
  *
@@ -1084,6 +1401,46 @@ export declare interface ImageBlockProps {
     downloadUrl?: string;
 }
 
+/**
+ * A collection of actions available on the Inbox UI
+ *
+ * @remarks
+ * Exposes a `chatbox` field which, if a conversation is currently selected,
+ * lets you control the chatbox encapsulated by this inbox.
+ *
+ * @public
+ */
+export declare class InboxController {
+    #private;
+    /**
+     * The {@link ChatboxController} object of the underlying chatbox
+     *
+     * @remarks
+     * This lets you programmatically control the chatbox side of this inbox, ie
+     * the right panel. For example, to control the message field text:
+     *
+     * ```js
+     * // Obtain a reference to the inbox object, eg:
+     * // const inbox = inboxRef.current; // react
+     * // const inbox = document.querySelector("t-inbox") // web
+     * // const inbox = inboxRef.value // vue
+     * // etc
+     *
+     * inbox.chatbox.setMessageFieldText("Hey there");
+     * ```
+     */
+    get chatbox(): ChatboxController;
+}
+
+/**
+ * The {@link https://talkjs.com/docs/Features/Chat_UIs/#inbox | Inbox UI. }
+ * Combines a Conversation List with a Chatbox, responsively scaling down on
+ * smaller screens.
+ *
+ * @public
+ */
+export declare const InboxElement: new () => TalkJS.InboxElement;
+
 export { LocationBlock }
 
 /**
@@ -1104,18 +1461,20 @@ export declare interface LocationBlockProps {
     block: LocationBlock;
 }
 
+/**
+ * @public
+ */
 export declare function MentionSuggestList(props: MentionSuggestListProps): JSX_2.Element | null;
 
-export declare interface MentionSuggestList {
-    keydown(key: string): boolean;
-}
-
 /**
  * @public
  */
 export declare interface MentionSuggestListProps {
 }
 
+/**
+ * @public
+ */
 export declare function MenuItem(props: MenuItemProps): JSX_2.Element;
 
 /**
@@ -1170,6 +1529,9 @@ export declare interface MessageActionMenuProps {
     permissions: MessagePermissions;
 }
 
+/**
+ * @public
+ */
 export declare function MessageContent(props: MessageContentProps): JSX_2.Element;
 
 /**
@@ -1318,6 +1680,10 @@ export declare interface MessageProps {
     permissions: MessagePermissions;
 }
 
+export { MessageSearch }
+
+export { MessageSearchState }
+
 export { MessageSnapshot }
 
 /**
@@ -1332,9 +1698,10 @@ export { MessageSnapshot }
  *
  * - `"everyoneRead"` - Everyone in the conversation has read this message. Typically represented using two checkmarks in chat UIs.
  *
+ * - `"virtual"` - a virtual message made with the <VirtualMessage> system component
  * @public
  */
-export declare type MessageStatus = "sending" | "sent" | "everyoneRead";
+export declare type MessageStatus = "sending" | "sent" | "everyoneRead" | "virtual";
 
 /**
  * Sent by {@link ChatboxProps.onMissingBrowserPermission} when the user
@@ -1368,6 +1735,16 @@ export declare interface MissingBrowserPermissionEvent {
     type: BrowserPermission;
 }
 
+/**
+ * @public
+ */
+export declare interface NoConversationSelectedProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
+    common: CommonChatboxProps;
+}
+
 export { ParticipantSnapshot }
 
 /**
@@ -1427,6 +1804,9 @@ export declare interface PopoverButtonProps<T extends object> extends React_2.HT
 
 export { Preact }
 
+/**
+ * @public
+ */
 export declare function ReactionPicker({ messageId, colorScheme, }: ReactionPickerProps): JSX_2.Element;
 
 /**
@@ -1487,16 +1867,30 @@ export declare interface ReplyBarProps {
     referencedMessage: MessageSnapshot;
 }
 
+export declare function SearchInput(props: SearchInputProps): JSX_2.Element;
+
+export declare interface SearchInputProps extends React_2.HTMLAttributes<HTMLInputElement> {
+}
+
+export { SearchMessageSnapshot }
+
 /**
  * An event object dispatched by the
  * {@link ConversationListProps.onSelectConversation} event.
+ *
+ * @public
  */
 export declare interface SelectConversationEvent {
     currentUser: UserSnapshot;
     /**
-     * The newly-selected conversation.
+     * The newly-selected conversation, or `null` if a conversation was
+     * de-selected.
      */
-    conversation: ConversationSnapshot;
+    conversation: ConversationSnapshot | null;
+    /**
+     * The message that was scrolled into view within the conversation
+     */
+    focusedMessage?: MessageSnapshot;
 }
 
 /**
@@ -1590,6 +1984,7 @@ export declare interface Theme {
     TimeAgo: React_2.ComponentType<TimeAgoProps>;
     MessageActionMenu: React_2.ComponentType<MessageActionMenuProps>;
     CompactMessageContent: React_2.ComponentType<CompactMessageContentProps>;
+    ChatSearchBox: React_2.ComponentType<ChatSearchBoxProps>;
     ChatHeader: React_2.ComponentType<ChatHeaderProps>;
     MessageListHeader: React_2.ComponentType<MessageListHeaderProps>;
     Message: React_2.ComponentType<MessageProps>;
@@ -1599,6 +1994,7 @@ export declare interface Theme {
     MessageListFooter: React_2.ComponentType<MessageListFooterProps>;
     BeforeMessages: React_2.ComponentType<BeforeMessagesProps>;
     AfterMessages: React_2.ComponentType<AfterMessagesProps>;
+    NoConversationSelected: React_2.ComponentType<NoConversationSelectedProps>;
     TextBlock: React_2.ComponentType<TextBlockProps>;
     FileBlock: React_2.ComponentType<FileBlockProps>;
     LocationBlock: React_2.ComponentType<LocationBlockProps>;
@@ -1609,6 +2005,9 @@ export declare interface Theme {
     VoiceRecorder: React_2.ComponentType<VoiceRecorderProps>;
     RecordingPreview: React_2.ComponentType<RecordingPreviewProps>;
     ConversationListItem: React_2.ComponentType<ConversationListItemProps>;
+    GlobalSearchResultItem: React_2.ComponentType<GlobalSearchResultItemProps>;
+    GlobalSearchBox: React_2.ComponentType<GlobalSearchBoxProps>;
+    GlobalSearchResultHeader: React_2.ComponentType<GlobalSearchResultHeaderProps>;
 }
 
 /**
@@ -1655,7 +2054,10 @@ export declare interface Translation extends TranslationStrings {
     locale: string;
 }
 
-declare interface TranslationStrings {
+/**
+ * @public
+ */
+export declare interface TranslationStrings {
     YESTERDAY: string;
     TODAY: string;
     DAYS: string;
@@ -1729,6 +2131,10 @@ declare interface TranslationStrings {
     ARIA_MORE_ACTIONS: string;
     ARIA_REPLYING_TO: (senderName: string, content: string) => string;
     REPLY_MODE_LEAVE_ARIA_LABEL: string;
+    SELECT_CONVERSATION: string;
+    SEARCH_RESULTS_CONVERSATIONS: string;
+    SEARCH_RESULTS_MESSAGES: string;
+    SEARCH_RESULTS_SHOW_MORE: string;
 }
 
 export { TypingSnapshot }
@@ -1741,8 +2147,8 @@ export declare type UploadState = "pending" | "done" | "error";
  * It'll initially return an empty list, and re-render the calling component as data participants are loaded.
  * It'll also cause a re-render when any of those participants change, such as when a user's name or photoUrl changes.
  *
- * @param conversationId ID of the conversation
- * @param limit Maximum number of participants to subscribe to. Defaults to 10. The maximum is 100.
+ * @param conversationId - ID of the conversation
+ * @param limit - Maximum number of participants to subscribe to. Defaults to 10. The maximum is 100.
  * @returns List of participant snapshots.
  *
  * @public
@@ -1753,8 +2159,8 @@ export declare function useParticipants(conversationId: string, limit?: number):
  * Returns "Yesterday", "Last Monday", "Tuesday, March 31" or "Monday, March 31
  * 2014", depending on which is most appropriate.
  *
- * @param timestamp The timestamp of the event in milliseconds since Unix epoch.
- * @param t Relevant translation object to get localized output
+ * @param timestamp - The timestamp of the event in milliseconds since Unix epoch.
+ * @param t - Relevant translation object to get localized output
  *
  * @public
  */
@@ -1785,6 +2191,10 @@ export declare interface UserPermissions {
      * True if {@link https://talkjs.com/docs/Features/Messages/Mentions/ | mentions} are enabled.
      */
     canMention: boolean;
+    /**
+     * True if the user can use search and other related features.
+     */
+    canSearch: boolean;
     /**
      * True if
      * {@link https://talkjs.com/docs/Features/Conversations/Status_Indicator/ | online status indicators }
@@ -1852,6 +2262,87 @@ export declare interface VideoBlockProps {
     downloadUrl?: string;
 }
 
+/**
+ * Lets you render a fake message with content and sender of your choice,
+ * without having to compose a complete MessageSnapshot object.
+ *
+ * @remarks
+ * This system component renders a fake message that looks and behaves like a
+ * real chat message, but is never stored or sent through TalkJS. It is useful
+ * for showing contextual prompts such as welcome messages at the top of a
+ * conversation.
+ *
+ * Uses the provided props to compose a complete {@link MessageSnapshot} object,
+ * which is then passed to the
+ * {@link https://talkjs.com/docs/UI_Components/Theme/Theme_components/Message | Message} component
+ * from your theme.
+ *
+ * Because the message isn't a real, stored message, the message is rendered as
+ * if the user has no permissions to perform any actions on this message (such
+ * as reply, edit, etc). This means the built-in action menu will not be
+ * accessible.
+ *
+ * @public
+ */
+export declare function VirtualMessage(props: VirtualMessageProps): JSX_2.Element | null;
+
+/**
+ * @public
+ */
+export declare interface VirtualMessageProps {
+    /**
+     * The text of the message. Accepts formatting markup like the chatbox message field does, eg `*this*` would become bold.
+     *
+     * @remarks
+     * Specify either `text` or `content`, but not both.
+     */
+    text?: string;
+    /**
+     * The content of the message as a content block.
+     *
+     * @remarks
+     * Lets you precisely control the formatting of the message, see
+     * {@link https://talkjs.com/docs/Concepts/Message_Content/#sending-message-content | Message content}.
+     * Specify either `text` or `content`, but not both.
+     */
+    content?: ContentBlock[];
+    /**
+     * The ID of the sender of this message, or a complete UserSnapshot with the
+     * sender's details.
+     *
+     * @remarks
+     * When omitted, the message is rendered as a system message.
+     *
+     * When passing a UserSnapshot, this object is used in full and the user is
+     * not loaded from the database, which means that you can also pass a fake
+     * user that does not really exist.
+     */
+    sender?: string | UserSnapshot;
+    /**
+     * Override the message's timestamp
+     *
+     * @remarks
+     * Defaults to `-1`, which our preset themes interpret as "do not show a timestamp at all"
+     */
+    createdAt?: number;
+    /**
+     * Control the message's delivery status
+     *
+     * @remarks
+     * Defaults to "virtual", which make our preset themes not render status ticks
+     * at all. Set it to eg `"sent"` to show a tickmark, or to `"everyoneRead"` to
+     * show a double tickmark.
+     */
+    status?: MessageStatus;
+    /**
+     * Custom data for the `message` object.
+     *
+     * @remarks
+     * You can read this out in `message.custom` inside the Message theme component.
+     */
+    custom?: Record<string, string>;
+}
+
 export { VoiceBlock }
 
 /**
@@ -1892,7 +2383,7 @@ export declare interface VoiceBlockProps {
  * voice message currently being recorded.
  *
  * @remarks
- * Use {@link EditorController.recordVoiceMessage()} to begin recording a voice
+ * Use {@link EditorController.recordVoiceMessage} to begin recording a voice
  * message.
  *
  * @public
@@ -1984,14 +2475,20 @@ declare global {
         type NullishConversationListProps = {
             [K in keyof Omit<ConversationListProps, "className" | "style">]: ConversationListProps[K] | null | undefined;
         };
+        type NullishInboxProps = {
+            [K in keyof Omit<InboxProps, "className" | "style">]: InboxProps[K] | null | undefined;
+        };
         interface ChatboxElement extends HTMLElement, NullishChatboxProps, ChatboxController {
         }
         interface ConversationListElement extends HTMLElement, NullishConversationListProps, ConversationListController {
         }
+        interface InboxElement extends HTMLElement, NullishInboxProps, InboxController {
+        }
     }
     interface HTMLElementTagNameMap {
         "t-chatbox": TalkJS.ChatboxElement;
         "t-conversation-list": TalkJS.ConversationListElement;
+        "t-inbox": TalkJS.InboxElement;
     }
 }