@talkjs/web-components 0.1.6 → 0.1.7

package/default.d.ts

@@ -1,5 +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';
@@ -9,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';
@@ -191,6 +196,21 @@ export declare interface BaseChatboxProps {
      * 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.
@@ -281,6 +301,16 @@ export declare interface BaseChatboxProps {
      * 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.
      *
@@ -327,6 +357,10 @@ export declare interface BaseConversationListProps {
      * 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.
      */
@@ -489,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
      *
@@ -506,13 +541,55 @@ export declare class ChatboxController {
      */
     focusMessageField(): void;
     /**
-     * Emits a {@link ChatboxController.onBackButtonClick} event.
+     * 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
-     * Called from the default ChatHeader theme component for the "back" button
-     * which is shown when the chatbox is part of an inbox that's being rendered
-     * in mobile mode.
+     * 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;
 }
 
@@ -534,7 +611,7 @@ export declare interface ChatboxProps extends BaseChatboxProps {
      *
      * @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
+     * 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
@@ -606,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.
  *
@@ -642,7 +749,7 @@ 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;
     /**
@@ -659,13 +766,23 @@ export declare interface CommonChatboxProps {
      */
     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;
 }
 
 /**
@@ -700,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;
     /**
@@ -763,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
@@ -777,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 | null): void;
+    selectConversation(conversationId: string | null, focusedMessageId?: string): Promise<void>;
 }
 
 /**
@@ -841,6 +962,10 @@ export declare interface ConversationListProps extends BaseConversationListProps
     tokenFetcher?: () => string | Promise<string>;
 }
 
+export { ConversationSearch }
+
+export { ConversationSearchState }
+
 export { ConversationSnapshot }
 
 /**
@@ -900,18 +1025,46 @@ export declare interface DeviceFeatures {
 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;
 }
 
@@ -1011,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.
@@ -1055,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
  */
@@ -1074,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.
  *
@@ -1176,22 +1430,6 @@ export declare class InboxController {
      * ```
      */
     get chatbox(): ChatboxController;
-    /**
-     * Select a conversation.
-     *
-     * @remarks
-     * This method is called from the theme's ConversationListItem component when
-     * the user clicks on the given conversation. You can also call it
-     * programmatically from elsewhere to simulate a user click.
-     *
-     * This method will trigger the {@link InboxProps.onSelectConversation} event.
-     * In most cases, if you want to change the selected conversation
-     * programmatically from outside the conversation list, it's better to pass a
-     * different value to the {@link InboxProps.selectedConversationId} prop
-     * instead, as that lets you keep your local state in sync with the props
-     * passed to the conversation list.
-     */
-    selectConversation(conversationId: string): void;
 }
 
 /**
@@ -1442,6 +1680,10 @@ export declare interface MessageProps {
     permissions: MessagePermissions;
 }
 
+export { MessageSearch }
+
+export { MessageSearchState }
+
 export { MessageSnapshot }
 
 /**
@@ -1625,6 +1867,13 @@ 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.
@@ -1634,9 +1883,14 @@ export declare interface ReplyBarProps {
 export declare interface SelectConversationEvent {
     currentUser: UserSnapshot;
     /**
-     * The newly-selected conversation.
+     * The newly-selected conversation, or `null` if a conversation was
+     * de-selected.
      */
     conversation: ConversationSnapshot | null;
+    /**
+     * The message that was scrolled into view within the conversation
+     */
+    focusedMessage?: MessageSnapshot;
 }
 
 /**
@@ -1730,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>;
@@ -1750,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>;
 }
 
 /**
@@ -1873,6 +2131,10 @@ export 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 }
@@ -1929,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 }
@@ -2008,7 +2274,7 @@ export declare interface VideoBlockProps {
  *
  * Uses the provided props to compose a complete {@link MessageSnapshot} object,
  * which is then passed to the
- * {@link /UI_Components/Theme/Theme_components/Message | Message} component
+ * {@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