@talkjs/react-components 0.0.28 → 0.0.30

package/default.d.ts

@@ -1,17 +1,14 @@
 import { AudioBlock } from '@talkjs/core';
 import { ConversationSnapshot } from '@talkjs/core';
-import { CSSProperties } from 'react';
 import { EditMessageParams } from '@talkjs/core';
 import { EditTextMessageParams } from '@talkjs/core';
-import { FileBlock } from '@talkjs/core';
 import { FileToken } from '@talkjs/core';
-import { ForwardRefExoticComponent } from 'react';
+import { GenericFileBlock } from '@talkjs/core';
 import { ImageBlock } from '@talkjs/core';
 import { LocationBlock } from '@talkjs/core';
 import { MessageSnapshot } from '@talkjs/core';
 import { ParticipantSnapshot } from '@talkjs/core';
-import type * as React_2 from 'react';
-import { RefAttributes } from 'react';
+import type * as React from 'react';
 import { ReferencedMessageSnapshot } from '@talkjs/core';
 import { SendMessageParams } from '@talkjs/core';
 import { SendTextMessageParams } from '@talkjs/core';
@@ -22,58 +19,103 @@ import { UserSnapshot } from '@talkjs/core';
 import { VideoBlock } from '@talkjs/core';
 import { VoiceBlock } from '@talkjs/core';
 
-declare type AppId = Brand<string, "App ID">;
-
-declare interface AppMetadata {
-    id: AppId;
+/**
+ * Holds information about your TalkJS app.
+ *
+ * @public
+ */
+declare interface App {
+    /**
+     * Your app's unique TalkJS ID. You can find it on the Settings page of the
+     * {@link https://talkjs.com/dashboard | TalkJS dashboard.}
+     */
+    id: string;
+    /**
+     * The name of your app.
+     */
     name: string;
+    /**
+     * The default locale.
+     *
+     * @remarks
+     * This can be configured from your TalkJS dashboard.
+     */
     defaultLocale: string;
+    /**
+     * Custom data set for this app.
+     *
+     * @remarks
+     * This can be configured from your TalkJS dashboard.
+     */
     custom: Record<string, string>;
 }
 
-declare interface AudioBlockProps extends ContentBlockProps {
+/**
+ * @public
+ */
+declare interface AudioBlockProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
+    common: CommonChatboxProps;
+    /**
+     * The message that this content block belongs to.
+     */
+    message: MessageSnapshot;
+    /**
+     * The audio block to display.
+     */
     block: AudioBlock;
+    /**
+     * The URL used to download the file.
+     *
+     * @remarks
+     * This URL is not the same as `block.url`. When the current user sends a file
+     * message, the `block.url` will hold a temporary `blob:` URL until that file
+     * is uploaded to TalkJS. The user can immediately see their file present in
+     * the chat, which makes for a smoother user experience.
+     *
+     * The `downloadUrl` is the URL of the file once it is uploaded to TalkJS. As
+     * such, this property will be `undefined` until the upload is completed,
+     * while `block.url` will always be defined and should be used for preview
+     * purposes.
+     */
     downloadUrl?: string;
 }
 
+/**
+ * @public
+ */
 declare interface AvatarProps {
+    /**
+     * A collection of objects which are passed to all Chatbox/ConversationList
+     * theme components.
+     *
+     * @remarks
+     * Because this particular theme component can show up in both a `<Chatbox>`
+     * and a `<ConversationList>`, this prop has a union type.
+     */
     common: CommonChatboxProps | CommonConversationListProps;
+    /**
+     * The URL of the image that's to be displayed.
+     */
     photoUrl: string;
 }
 
 /**
- * Brands a base type `T`.
- *
- * @example
- * ```ts
- * type UserId = Brand<string, "UserId">;
- * type MessageId = Brand<string, "MessageId">;
- *
- * const a: UserId = "abc" as UserId;    // works
- * const b: UserId = "abc";              // error
- * const c: UserId = "abc" as MessageId; // error
- * ```
- */
-declare type Brand<T, B extends string> = T & Branding<B>;
-
-declare interface Branding<B extends string> {
-    __tag: Record<B, true>;
-}
-
-/**
- * @public
- *
  * A string that is one of `"notifications" | "microphone" | "geolocation"`.
  *
  * @remarks
  * Note that more possible values may be added in the future, so make sure your
  * handler can deal with unknown permission types gracefully.
+ *
+ * @public
  */
 export declare type BrowserPermission = "notifications" | "microphone" | "geolocation";
 
 /**
- * Passed to `chatbox.beforeBrowserPermissionPrompt` when a browser permission
- * dialog needs to be shown to the user.
+ * Passed to {@link ChatboxProps.beforeBrowserPermissionPrompt} when a
+ * browser permission dialog needs to be shown to the user.
  *
  * @public
  */
@@ -117,175 +159,691 @@ export declare interface BrowserPermissionRequest {
     showPrompt(): Promise<"granted" | "denied">;
 }
 
-export declare const Chatbox: ForwardRefExoticComponent<ChatboxProps & RefAttributes<ChatboxRef>>;
+/**
+ * The
+ * {@link https://talkjs.com/docs/Features/Chat_UIs/#chatbox | TalkJS Chatbox UI. }
+ * Displays a single conversation.
+ *
+ * @public
+ */
+export declare const Chatbox: React.ForwardRefExoticComponent<ChatboxProps & React.RefAttributes<ChatboxController>>;
+
+/**
+ * A collection of actions available on the Chatbox UI.
+ *
+ * @public
+ */
+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
+     */
+    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;
+        custom?: Record<string, string>;
+    }): Promise<void>;
+    /**
+     * Send a location message to the current conversation.
+     *
+     * @param message
+     */
+    sendLocationMessage(message: {
+        location: Coordinates;
+        custom?: Record<string, string>;
+    }): Promise<void>;
+    /**
+     * Set/unset the message that's currently being replied to.
+     *
+     * @param messageId - When `null` is provided, the "replying to" message is cleared
+     */
+    setReferencedMessage(messageId: string | null): void;
+    /**
+     * Toggle the given emoji reaction for the given message. If the current user
+     * already added this reaction, it's removed, and otherwise, it's added.
+     *
+     * Called from the theme's Message component when the user clicks on an
+     * existing emoji reaction.
+     *
+     * @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 `"🎉"`.
+     */
+    toggleReaction(messageId: string, emoji: string): Promise<void>;
+    /**
+     * Get the plaintext from the message field
+     *
+     * @returns The text
+     */
+    getMessageFieldText(): string;
+    /**
+     * Set the plaintext in the message field
+     * @param text
+     */
+    setMessageFieldText(text: string): void;
+    /**
+     * Focus the message field
+     */
+    focusMessageField(): void;
+}
 
+/**
+ * @public
+ */
 export declare interface ChatboxProps {
+    /**
+     * @hidden
+     */
     className?: string;
-    style?: CSSProperties;
+    /**
+     * @hidden
+     */
+    style?: React.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 to display.
+     *
+     * @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.
+     */
     conversationId: string;
+    /**
+     * A token to authenticate the session with.
+     *
+     * @remarks
+     * See the
+     * {@link https://talkjs.com/docs/Features/Security/Authentication/ | Authentication guide }
+     * and
+     * {@link https://talkjs.com/docs/Features/Security/Advanced_Authentication/#token-reference | Token reference }
+     * for details and examples.
+     *
+     * Required when authentication is enabled, otherwise optional.
+     */
     token?: string;
+    /**
+     * A function that fetches and returns a new authentication token from your
+     * server.
+     *
+     * @remarks
+     * TalkJS calls this function whenever the current token is about to expire.
+     * This callback is designed to work with any backend setup. See
+     * {@link https://talkjs.com/docs/Features/Security/Advanced_Authentication/#refreshable-tokens | Refreshable tokens }
+     * 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;
-    onDeleteMessage?: (e: DeleteMessageEvent) => void;
-    onSendMessage?: (e: SendMessageEvent) => void;
+    /**
+     * 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;
-    onMissingBrowserPermission?: (e: MissingBrowserPermissionEvent) => 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.
+     *
+     * 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}
+     */
+    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 {@linkcode CommonChatboxProps.themeCustom} for Chatbox
+     * theme components and through
+     * {@linkcode CommonConversationListProps.themeCustom} for ConversationList
+     * theme components.
+     */
     themeCustom?: any;
 }
 
-export declare interface ChatboxRef {
-    deleteMessage(messageId: string): Promise<void>;
-    setEditing(messageId: string | null): void;
-    editMessage(messageId: string, params: EditTextMessageParams | EditMessageParams): Promise<void>;
-    sendMessage(params: SendTextMessageParams | SendMessageParams): Promise<void>;
-    sendFileMessage(message: {
-        fileToken: FileToken;
-        custom?: Record<string, string>;
-    }): Promise<void>;
-    sendLocationMessage(message: {
-        location: Coordinates;
-        custom?: Record<string, string>;
-    }): Promise<void>;
-    setReferencedMessage(messageId: string | null): void;
-    getMessageFieldText: () => string;
-    setMessageFieldText: (text: string) => void;
-}
-
+/**
+ * @public
+ */
 declare interface ChatHeaderProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
     common: CommonChatboxProps;
+    /**
+     * A record of user IDs and their connection status.
+     */
     isUserConnected: {
         [userId: string]: boolean;
     };
+    /**
+     * The current user's permissions.
+     */
     permissions: UserPermissions;
 }
 
+/**
+ * A collection of props that's shared by every themed component used in the Chatbox UI.
+ *
+ * @public
+ */
 declare interface CommonChatboxProps {
-    app: AppMetadata;
+    /**
+     * Holds information about your TalkJS app.
+     */
+    app: App;
+    /**
+     * The user that mounted this chatbox.
+     */
     currentUser: UserSnapshot;
+    /**
+     * A translation object which holds localized strings for internationalization
+     * purposes.
+     */
     t: Translation;
-    chatbox: ChatboxRef;
+    /**
+     * Public interface of the chatbox instance.
+     */
+    chatbox: ChatboxController;
+    /**
+     * Arbitrary custom data passed down to the theme.
+     *
+     * @remarks
+     * The data that you pass to {@link ChatboxProps.themeCustom} will show up
+     * here so that you can use it from within theme components.
+     */
     themeCustom?: any;
+    /**
+     * Describes the capabilities of the current device.
+     */
     device: DeviceFeatures;
+    /**
+     * The theme object that the chatbox's is currently using.
+     */
     theme: Theme;
+    /**
+     * The conversation displayed in the chatbox.
+     */
     conversation: ConversationSnapshot;
+    /**
+     * A list of participants that are part of the conversation that's currently
+     * being shown.
+     */
     participants: ParticipantSnapshot[];
+    /**
+     * Tells you which participants are currently typing
+     */
     typing: TypingSnapshot;
+    /**
+     * The underlying TalkJS session object that handles sending and receiving chat data.
+     */
     session: TalkSession;
 }
 
+/**
+ * A collection of props that's shared by every themed component used in the ConversationList UI.
+ *
+ * @public
+ */
 declare interface CommonConversationListProps {
-    app: AppMetadata;
+    /**
+     * Holds information about your TalkJS app.
+     */
+    app: App;
+    /**
+     * The user that mounted this chatbox.
+     */
     currentUser: UserSnapshot;
+    /**
+     * A translation object which holds localized strings for internationalization
+     * purposes.
+     */
     t: Translation;
+    /**
+     * Arbitrary custom data passed down to the theme.
+     *
+     * @remarks
+     * The data that you pass to {@link ConversationListProps.themeCustom} will show up
+     * here so that you can use it from within theme components.
+     */
     themeCustom?: any;
+    /**
+     * Describes the capabilities of the current device.
+     */
     device: DeviceFeatures;
+    /**
+     * The theme object that the chatbox's is currently using.
+     */
     theme: Theme;
-    conversationList: ConversationListRef;
+    /**
+     * Public interface of the conversation list instance.
+     */
+    conversationList: ConversationListController;
+    /**
+     * The underlying TalkJS session object that handles sending and receiving chat data.
+     */
     session: TalkSession;
 }
 
+/**
+ * @public
+ */
 declare interface CompactMessageContentProps {
+    /**
+     * A collection of objects which are passed to all Chatbox/ConversationList
+     * theme components.
+     *
+     * @remarks
+     * Because this particular theme component can show up in both a `<Chatbox>`
+     * and a `<ConversationList>`, this prop has a union type.
+     */
     common: CommonChatboxProps | CommonConversationListProps;
+    /**
+     * The message that's being displayed.
+     */
     message: MessageSnapshot | ReferencedMessageSnapshot;
 }
 
-declare interface ContentBlockProps {
-    common: CommonChatboxProps;
-    message: MessageSnapshot;
-}
-
+/**
+ * @public
+ */
 declare interface ConversationImageProps {
+    /**
+     * A collection of objects which are passed to all Chatbox/ConversationList
+     * theme components.
+     *
+     * @remarks
+     * Because this particular theme component can show up in both a `<Chatbox>`
+     * and a `<ConversationList>`, this prop has a union type.
+     */
     common: CommonChatboxProps | CommonConversationListProps;
+    /**
+     * The conversation that's being displayed.
+     */
     conversation: ConversationSnapshot;
+    /**
+     * A list of participants that are a part of the conversation.
+     */
     participants: ParticipantSnapshot[];
 }
 
-export declare const ConversationList: ForwardRefExoticComponent<ConversationListProps & RefAttributes<ConversationListRef>>;
+export declare const ConversationList: React.ForwardRefExoticComponent<ConversationListProps & React.RefAttributes<ConversationListController>>;
+
+/**
+ * A collection of actions available on the ConversationList UI.
+ *
+ * @public
+ */
+export declare class ConversationListController {
+    #private;
+    /**
+     * 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
+     * {@linkcode ConversationListProps.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 {@linkcode ConversationListProps.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;
+}
 
 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;
+    /**
+     * The list of participants that are part of the given conversation.
+     */
     participants: ParticipantSnapshot[];
+    /**
+     * If `true`, this conversation is the currently selected one in the
+     * conversation list.
+     */
     isSelected: boolean;
 }
 
+/**
+ * @public
+ */
 export declare interface ConversationListProps {
+    /**
+     * @hidden
+     */
     className?: string;
-    style?: CSSProperties;
+    /**
+     * @hidden
+     */
+    style?: React.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;
-    token?: 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.
+     *
+     * Note that updating the selected conversation through this prop **will not**
+     * trigger the {@linkcode onSelectConversation} callback.
+     */
     selectedConversationId?: string;
+    /**
+     * A token to authenticate the session with.
+     *
+     * @remarks
+     * See the
+     * {@link https://talkjs.com/docs/Features/Security/Authentication/ | Authentication guide}
+     * and
+     * {@link https://talkjs.com/docs/Features/Security/Advanced_Authentication/#token-reference | Token reference}
+     *  for details and examples.
+     *
+     * Required when authentication is enabled, otherwise optional.
+     */
+    token?: string;
+    /**
+     * A function that fetches and returns a new authentication token from your
+     * server.
+     *
+     * @remarks
+     * TalkJS calls this function whenever the current token is about to expire.
+     * This callback is designed to work with any backend setup. See
+     * {@link https://talkjs.com/docs/Features/Security/Advanced_Authentication/#refreshable-tokens | Refreshable tokens}
+     *  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
+     * {@linkcode 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 {@linkcode CommonChatboxProps.themeCustom} for Chatbox
+     * theme components and through
+     * {@linkcode CommonConversationListProps.themeCustom} for ConversationList
+     * theme components.
+     */
     themeCustom?: any;
-    onSelectConversation?: (e: SelectConversationEvent) => void;
-}
-
-export declare interface ConversationListRef {
-    selectConversation(conversationId: string): void;
-}
-
-declare interface Coordinates {
-    latitude: number;
-    longitude: number;
 }
 
+/**
+ * @public
+ */
 declare interface Coordinates {
     latitude: number;
     longitude: number;
 }
 
+/**
+ * The entire TalkJS default theme.
+ *
+ * @remarks
+ * The entire source code of the theme is available in the {@link https://www.github.com/talkjs/theme-default | TalkJS `theme-default` Github repository.}
+ *
+ * @public
+ */
 export declare const defaultTheme: Theme;
 
+/**
+ * An event object dispatched by the {@link ChatboxProps.onDeleteMessage} event.
+ *
+ * @public
+ */
 export declare interface DeleteMessageEvent {
     currentUser: UserSnapshot;
+    /**
+     * The message that was just deleted.
+     */
     message: MessageSnapshot;
+    /**
+     * The conversation that the message used to be in.
+     */
     conversation: ConversationSnapshot;
 }
 
+/**
+ * Describes the capabilities of the current device.
+ *
+ * @public
+ */
 declare interface DeviceFeatures {
     /**
      * True if the browser supports IndexedDB, which the emoji picker depends on.
      */
     supportsEmojiPicker: boolean;
     /**
-     * True if the user agents reports this device as mobile (incl tablets).
+     * True if the user agents reports the current device as a mobile/tablet.
      */
     isMobile: boolean;
 }
 
-declare interface DeviceFeatures {
+/**
+ * @public
+ */
+declare interface FileBlockProps {
     /**
-     * True if the browser supports IndexedDB, which the emoji picker depends on.
+     * A collection of objects which are passed to all Chatbox theme components.
      */
-    supportsEmojiPicker: boolean;
+    common: CommonChatboxProps;
     /**
-     * True if the user agents reports this device as mobile (incl tablets).
+     * The message that this content block belongs to.
+     */
+    message: MessageSnapshot;
+    /**
+     * The generic file block to display.
+     */
+    block: GenericFileBlock;
+    /**
+     * The URL used to download the file.
+     *
+     * @remarks
+     * This URL is not the same as `block.url`. When the current user sends a file
+     * message, the `block.url` will hold a temporary `blob:` URL until that file
+     * is uploaded to TalkJS. The user can immediately see their file present in
+     * the chat, which makes for a smoother user experience.
+     *
+     * The `downloadUrl` is the URL of the file once it is uploaded to TalkJS. As
+     * such, this property will be `undefined` until the upload is completed,
+     * while `block.url` will always be defined and should be used for preview
+     * purposes.
      */
-    isMobile: boolean;
-}
-
-declare interface FileBlockProps extends ContentBlockProps {
-    block: FileBlock;
     downloadUrl?: string;
 }
 
+/**
+ * @public
+ */
 declare interface GroupChatImageProps {
+    /**
+     * A collection of objects which are passed to all Chatbox/ConversationList
+     * theme components.
+     *
+     * @remarks
+     * Because this particular theme component can show up in both a `<Chatbox>`
+     * and a `<ConversationList>`, this prop has a union type.
+     */
     common: CommonChatboxProps | CommonConversationListProps;
+    /**
+     * A list of participants that are a part of the conversation.
+     */
     participants: ParticipantSnapshot[];
 }
 
+/**
+ * @public
+ */
 declare interface IconProps {
+    /**
+     * A collection of objects which are passed to all Chatbox/ConversationList
+     * theme components.
+     *
+     * @remarks
+     * Because this particular theme component can show up in both a `<Chatbox>`
+     * and a `<ConversationList>`, this prop has a union type.
+     */
     common: CommonChatboxProps | CommonConversationListProps;
+    /**
+     * The name of the icon to display.
+     */
     type: "attach" | "chevronLeft" | "left" | "chevronRight" | "right" | "chevronUp" | "up" | "chevronDown" | "down" | "close" | "emoji" | "locationPin" | "more" | "plus" | "search" | "send" | "spinner" | "play" | "pause" | "updown" | "addEmoji" | "microphone" | "mic" | "stop" | "download" | "location" | "email" | "movie" | "image" | "attachment" | "horizontalDots" | "verticalDots" | "reply" | "back";
+    /**
+     * @hidden
+     */
     className?: string;
 }
 
@@ -301,65 +859,227 @@ declare interface IEditorController {
     toggleEmojiPicker(): void;
 }
 
-declare interface ImageBlockProps extends ContentBlockProps {
+/**
+ * @public
+ */
+declare interface ImageBlockProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
+    common: CommonChatboxProps;
+    /**
+     * The message that this content block belongs to.
+     */
+    message: MessageSnapshot;
+    /**
+     * The image block to display.
+     */
     block: ImageBlock;
+    /**
+     * The URL used to download the file.
+     *
+     * @remarks
+     * This URL is not the same as `block.url`. When the current user sends a file
+     * message, the `block.url` will hold a temporary `blob:` URL until that file
+     * is uploaded to TalkJS. The user can immediately see their file present in
+     * the chat, which makes for a smoother user experience.
+     *
+     * The `downloadUrl` is the URL of the file once it is uploaded to TalkJS. As
+     * such, this property will be `undefined` until the upload is completed,
+     * while `block.url` will always be defined and should be used for preview
+     * purposes.
+     */
     downloadUrl?: string;
 }
 
-declare interface LocationBlockProps extends ContentBlockProps {
+/**
+ * @public
+ */
+declare interface LocationBlockProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
+    common: CommonChatboxProps;
+    /**
+     * The message that this content block belongs to.
+     */
+    message: MessageSnapshot;
+    /**
+     * The location block to display.
+     */
     block: LocationBlock;
 }
 
+/**
+ * An event object dispatched by the {@link ChatboxProps.onMessageAction} event.
+ *
+ * @public
+ */
+export declare interface MessageActionEvent {
+    /**
+     * The name of the action that was triggered.
+     */
+    action: string;
+    /**
+     * The parameters of the action that was triggered, if any.
+     */
+    params: Record<string, string>;
+    /**
+     * The message that contained the action link or action button.
+     */
+    message: MessageSnapshot;
+    /**
+     * The current conversation.
+     */
+    conversation: ConversationSnapshot;
+}
+
+/**
+ * @public
+ */
 declare interface MessageActionMenuProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
     common: CommonChatboxProps;
+    /**
+     * The message that's attached to the action menu.
+     */
     message: MessageSnapshot;
+    /**
+     * The current user's permissions relating to the given message.
+     */
     permissions: MessagePermissions;
 }
 
+/**
+ * @public
+ */
 declare interface MessageDividerProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
     common: CommonChatboxProps;
+    /**
+     * If true, this divider separates unread messages from read ones.
+     */
     isReadMarker: boolean;
+    /**
+     * If true, this divider separates messages sent on two different dates.
+     */
     isDayMarker: boolean;
+    /**
+     * The date timestamp when {@link MessageDividerProps.isDayMarker} is `true`. Holds the number of
+     * milliseconds passed since the Unix Epoch.
+     */
     timestamp?: number;
 }
 
+/**
+ * @public
+ */
 declare interface MessageFieldProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
     common: CommonChatboxProps;
+    /**
+     * The message that's currently being replied to, if any.
+     */
     referencedMessage: MessageSnapshot | undefined;
+    /**
+     * The current user's permissions.
+     */
     permissions: UserPermissions;
+    /**
+     * An object holding the state of the message field.
+     */
     editor: IEditorController;
+    /**
+     * When a message is being edited its ID will be stored here.
+     */
     editMessageId: string | undefined;
 }
 
+/**
+ * @public
+ */
 declare interface MessageListFooterProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
     common: CommonChatboxProps;
 }
 
+/**
+ * A set of permissions the current user has for a given message.
+ *
+ * @remarks
+ * The values of these permissions come from the user's {@link https://talkjs.com/docs/Concepts/Roles/ | role}.
+ *
+ * @public
+ */
 declare interface MessagePermissions extends UserPermissions {
+    /**
+     * True if the user has the ability to delete the given message.
+     */
     canDeleteMessage: boolean;
+    /**
+     * True if the user has the ability to reply to the given message.
+     */
     canReplyToMessage: boolean;
+    /**
+     * True if the user has the ability to edit the given message.
+     */
     canEditMessage: boolean;
+    /**
+     * True if the user has the ability to add an {@link https://talkjs.com/docs/Features/Messages/Emojis/#emoji-reactions | emoji reaction} to the given message.
+     */
     canAddReaction: boolean;
 }
 
-declare interface MessagePermissions extends UserPermissions {
-    canDeleteMessage: boolean;
-    canReplyToMessage: boolean;
-    canEditMessage: boolean;
-}
-
+/**
+ * @public
+ */
 declare interface MessageProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
     common: CommonChatboxProps;
+    /**
+     * The message that's being displayed.
+     */
     message: MessageSnapshot;
+    /**
+     * The current status of the message.
+     */
     messageStatus: MessageStatus;
+    /**
+     * The current user's permissions relating to the given message.
+     */
     permissions: MessagePermissions;
 }
 
+/**
+ * The current status of the message.
+ *
+ * @remarks
+ * This type can have one of these values:
+ *
+ * - `"sending"` - Message is still being sent to the server. a loading spinner is typically shown in chat UIs.
+ *
+ * - `"sent"` - Message has arrived on the server. Typically represented using a single checkmark in chat UIs.
+ *
+ * - `"everyoneRead"` - Everyone in the conversation has read this message. Typically represented using two checkmarks in chat UIs.
+ *
+ * @public
+ */
 declare type MessageStatus = "sending" | "sent" | "everyoneRead";
 
 /**
- * Sent by `onMissingBrowserPermission` when the user tried to do an action that
- * require explicit browser permission, but that permission has been denied.
+ * Sent by {@link ChatboxProps.onMissingBrowserPermission} when the user
+ * tried to do an action that require explicit browser permission, but that
+ * permission has been denied.
  *
  * @remarks
  * This event is meant to let you show a message to the user if an action (eg
@@ -367,7 +1087,7 @@ declare type MessageStatus = "sending" | "sent" | "everyoneRead";
  * browser permission for that has been denied.
  *
  * If you want to control when to show the browser permissions prompt, use
- * `beforeBrowserPermissionPrompt`.
+ * {@link ChatboxProps.beforeBrowserPermissionPrompt}.
  *
  * This event is emitted both when the user has denied this permission in the
  * past, and when a user action just triggered a browser permissions prompt
@@ -388,64 +1108,136 @@ export declare interface MissingBrowserPermissionEvent {
     type: BrowserPermission;
 }
 
+/**
+ * @public
+ */
 declare interface ReferencedMessageProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
     common: CommonChatboxProps;
+    /**
+     * The message that's being referenced.
+     */
     referencedMessage: ReferencedMessageSnapshot;
 }
 
+/**
+ * @public
+ */
 declare interface ReplyBarProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
     common: CommonChatboxProps;
+    /**
+     * The message that's being replied to.
+     */
     referencedMessage: MessageSnapshot;
 }
 
+/**
+ * An event object dispatched by the
+ * {@link ConversationListProps.onSelectConversation} event.
+ */
 export declare interface SelectConversationEvent {
     currentUser: UserSnapshot;
+    /**
+     * The newly-selected conversation.
+     */
     conversation: ConversationSnapshot;
 }
 
+/**
+ * An event object dispatched by the {@link ChatboxProps.onSendMessage} event.
+ *
+ * @public
+ */
 export declare interface SendMessageEvent {
     currentUser: UserSnapshot;
+    /**
+     * The message that was just sent.
+     */
     message: MessageSnapshot;
+    /**
+     * The conversation the message was sent in.
+     */
     conversation: ConversationSnapshot;
 }
 
-declare interface TextBlockProps extends ContentBlockProps {
+/**
+ * @public
+ */
+declare interface TextBlockProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
+    common: CommonChatboxProps;
+    /**
+     * The message that this content block belongs to.
+     */
+    message: MessageSnapshot;
+    /**
+     * The text block to display.
+     */
     block: TextBlock;
 }
 
+/**
+ * A theme can be used to customize the appearance & behavior of your TalkJS
+ * Chatbox and/or ConversationList.
+ *
+ * @remarks
+ * The implementation of TalkJS's default theme is open-source and
+ * {@link https://github.com/talkjs/theme-default | available on Github. }
+ *
+ * @public
+ */
 export declare interface Theme {
-    Avatar: React_2.ComponentType<AvatarProps>;
-    ConversationImage: React_2.ComponentType<ConversationImageProps>;
-    GroupChatImage: React_2.ComponentType<GroupChatImageProps>;
-    ReferencedMessage: React_2.ComponentType<ReferencedMessageProps>;
-    ReplyBar: React_2.ComponentType<ReplyBarProps>;
-    TimeAgo: React_2.ComponentType<TimeAgoProps>;
-    MessageActionMenu: React_2.ComponentType<MessageActionMenuProps>;
-    CompactMessageContent: React_2.ComponentType<CompactMessageContentProps>;
-    ChatHeader: React_2.ComponentType<ChatHeaderProps>;
-    Message: React_2.ComponentType<MessageProps>;
-    MessageField: React_2.ComponentType<MessageFieldProps>;
-    Icon: React_2.ComponentType<IconProps>;
-    MessageDivider: React_2.ComponentType<MessageDividerProps>;
-    MessageListFooter: React_2.ComponentType<MessageListFooterProps>;
-    TextBlock: React_2.ComponentType<TextBlockProps>;
-    FileBlock: React_2.ComponentType<FileBlockProps>;
-    LocationBlock: React_2.ComponentType<LocationBlockProps>;
-    ImageBlock: React_2.ComponentType<ImageBlockProps>;
-    AudioBlock: React_2.ComponentType<AudioBlockProps>;
-    VoiceBlock: React_2.ComponentType<VoiceBlockProps>;
-    VideoBlock: React_2.ComponentType<VideoBlockProps>;
-    ConversationListItem: React_2.ComponentType<ConversationListItemProps>;
+    Avatar: React.ComponentType<AvatarProps>;
+    ConversationImage: React.ComponentType<ConversationImageProps>;
+    GroupChatImage: React.ComponentType<GroupChatImageProps>;
+    ReferencedMessage: React.ComponentType<ReferencedMessageProps>;
+    ReplyBar: React.ComponentType<ReplyBarProps>;
+    TimeAgo: React.ComponentType<TimeAgoProps>;
+    MessageActionMenu: React.ComponentType<MessageActionMenuProps>;
+    CompactMessageContent: React.ComponentType<CompactMessageContentProps>;
+    ChatHeader: React.ComponentType<ChatHeaderProps>;
+    Message: React.ComponentType<MessageProps>;
+    MessageField: React.ComponentType<MessageFieldProps>;
+    Icon: React.ComponentType<IconProps>;
+    MessageDivider: React.ComponentType<MessageDividerProps>;
+    MessageListFooter: React.ComponentType<MessageListFooterProps>;
+    TextBlock: React.ComponentType<TextBlockProps>;
+    FileBlock: React.ComponentType<FileBlockProps>;
+    LocationBlock: React.ComponentType<LocationBlockProps>;
+    ImageBlock: React.ComponentType<ImageBlockProps>;
+    AudioBlock: React.ComponentType<AudioBlockProps>;
+    VoiceBlock: React.ComponentType<VoiceBlockProps>;
+    VideoBlock: React.ComponentType<VideoBlockProps>;
+    ConversationListItem: React.ComponentType<ConversationListItemProps>;
 }
 
+/**
+ * @public
+ */
 declare interface TimeAgoProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
     common: CommonChatboxProps;
+    /**
+     * The timestamp of when the message was sent. Holds the number of milliseconds passed since the Unix Epoch.
+     */
     timestamp: number;
 }
 
-declare type Translation = TranslationData & TranslationStrings;
-
-declare interface TranslationData {
+/**
+ * Translation object
+ *
+ * @public
+ */
+declare interface Translation extends TranslationStrings {
     locale: string;
 }
 
@@ -509,35 +1301,114 @@ declare interface TranslationStrings {
     CONTACT_INFORMATION_HIDDEN: string;
 }
 
+/**
+ * A set of permissions for the current user.
+ *
+ * @remarks
+ * The values of these permissions come from the user's {@link https://talkjs.com/docs/Concepts/Roles/ | role}.
+ *
+ * @public
+ */
 declare interface UserPermissions {
+    /**
+     * True if typing indicators are enabled.
+     */
     showTypingIndicator: boolean;
+    /**
+     * True if {@link https://talkjs.com/docs/Features/Messages/File_Sharing/ | file sharing} is enabled.
+     */
     canShareFile: boolean;
+    /**
+     * True if location sharing is enabled.
+     */
     canShareLocation: boolean;
+    /**
+     * True if {@link https://talkjs.com/docs/Features/Messages/Mentions/ | mentions} are enabled.
+     */
     canMention: boolean;
+    /**
+     * True if
+     * {@link https://talkjs.com/docs/Features/Conversations/Status_Indicator/ | online status indicators }
+     * are enabled.
+     */
     showOnlineStatus: boolean;
+    /**
+     * True if {@link https://talkjs.com/docs/Features/Messages/Voice_Messages/ | voice messages} are enabled.
+     */
     canSendVoiceMessage: boolean;
+    /**
+     * True if the user has the permission to leave a given conversation.
+     */
     canLeaveConversation: boolean;
+    /**
+     * True if the user has the permission to mark the given conversation as unread.
+     */
     canMarkConversationAsUnread: boolean;
 }
 
-declare interface UserPermissions {
-    showTypingIndicator: boolean;
-    canShareFile: boolean;
-    canShareLocation: boolean;
-    canMention: boolean;
-    showOnlineStatus: boolean;
-    canSendVoiceMessage: boolean;
-    canLeaveConversation: boolean;
-    canMarkConversationAsUnread: boolean;
-}
-
-declare interface VideoBlockProps extends ContentBlockProps {
+/**
+ * @public
+ */
+declare interface VideoBlockProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
+    common: CommonChatboxProps;
+    /**
+     * The message that this content block belongs to.
+     */
+    message: MessageSnapshot;
+    /**
+     * The video block to display.
+     */
     block: VideoBlock;
+    /**
+     * The URL used to download the file.
+     *
+     * @remarks
+     * This URL is not the same as `block.url`. When the current user sends a file
+     * message, the `block.url` will hold a temporary `blob:` URL until that file
+     * is uploaded to TalkJS. The user can immediately see their file present in
+     * the chat, which makes for a smoother user experience.
+     *
+     * The `downloadUrl` is the URL of the file once it is uploaded to TalkJS. As
+     * such, this property will be `undefined` until the upload is completed,
+     * while `block.url` will always be defined and should be used for preview
+     * purposes.
+     */
     downloadUrl?: string;
 }
 
-declare interface VoiceBlockProps extends ContentBlockProps {
+/**
+ * @public
+ */
+declare interface VoiceBlockProps {
+    /**
+     * A collection of objects which are passed to all Chatbox theme components.
+     */
+    common: CommonChatboxProps;
+    /**
+     * The message that this content block belongs to.
+     */
+    message: MessageSnapshot;
+    /**
+     * The voice block to display.
+     */
     block: VoiceBlock;
+    /**
+     * The URL used to download the file.
+     *
+     * @remarks
+     * This URL is not the same as `block.url`. When the current user sends a file
+     * message, the `block.url` will hold a temporary `blob:` URL until that file
+     * is uploaded to TalkJS. The user can immediately see their file present in
+     * the chat, which makes for a smoother user experience.
+     *
+     * The `downloadUrl` is the URL of the file once it is uploaded to TalkJS. As
+     * such, this property will be `undefined` until the upload is completed,
+     * while `block.url` will always be defined and should be used for preview
+     * purposes.
+     */
     downloadUrl?: string;
 }
 
@@ -546,34 +1417,8 @@ export { }
 
 declare global {
     interface HTMLElementTagNameMap {
-        "t-chatbox": ChatboxHTMLElement;
-        "t-conversation-list": ConversationListHTMLElement;
-    }
-}
-
-
-declare global {
-    namespace JSX {
-        interface IntrinsicElements {
-            "t-chatbox": typeof UnthemedChatbox;
-            "t-conversation-list": typeof UnthemedConversationList;
-        }
-    }
-}
-
-
-declare global {
-    namespace JSX {
-        interface IntrinsicElements {
-            "emoji-picker": {
-                class?: string;
-                ref: React.Ref<HTMLElement>;
-            };
-        }
-    }
-    interface HTMLElementEventMap {
-        "emoji-click": EmojiClickEvent;
-        "skin-tone-change": SkinToneChangeEvent;
+        "t-chatbox": ChatboxElement;
+        "t-conversation-list": ConversationListElement;
     }
 }