@talkjs/web-components 0.0.27 → 0.0.29

package/default.d.ts

@@ -1,15 +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 { 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 type * as React from 'react';
 import { ReferencedMessageSnapshot } from '@talkjs/core';
 import { SendMessageParams } from '@talkjs/core';
 import { SendTextMessageParams } from '@talkjs/core';
@@ -20,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
  */
@@ -115,181 +159,661 @@ export declare interface BrowserPermissionRequest {
     showPrompt(): Promise<"granted" | "denied">;
 }
 
+/**
+ * The
+ * {@link https://talkjs.com/docs/Features/Chat_UIs/#chatbox | TalkJS Chatbox UI. }
+ * Displays a single conversation.
+ *
+ * @public
+ */
 export declare const ChatboxHTMLElement: new () => ChatboxHTMLElement_2;
 
 declare interface ChatboxHTMLElement_2 extends HTMLElement, NullishChatboxProps, ChatboxRef {
 }
 
+/**
+ * @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/SDKs/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;
+    /**
+     * 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;
 }
 
+/**
+ * A collection of actions available on the Chatbox UI.
+ *
+ * @public
+ */
 export declare interface ChatboxRef {
+    /**
+     * 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>;
-    sendFileMessage(message: {
+    /**
+     * 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;
-    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;
+    /**
+     * The chatbox instance itself.
+     */
     chatbox: ChatboxRef;
+    /**
+     * 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;
+    /**
+     * The conversation list instance itself.
+     */
     conversationList: ConversationListRef;
+    /**
+     * 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[];
 }
 
+/**
+ * The
+ * {@link https://talkjs.com/docs/Features/Chat_UIs/#conversation-list | Conversation List UI. }
+ * Displays a list of a user's conversations. You can use a conversation list on
+ * its own on a page, or combine it with a {@link Chatbox} to build a complete message
+ * center.
+ *
+ * @public
+ */
 export declare const ConversationListHTMLElement: new () => ConversationListHTMLElement_2;
 
 declare interface ConversationListHTMLElement_2 extends HTMLElement, NullishConversationListProps, ConversationListRef {
 }
 
 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/SDKs/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/SDKs/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;
 }
 
+/**
+ * A collection of actions available on the ConversationList UI.
+ *
+ * @public
+ */
 export declare interface ConversationListRef {
+    /**
+     * Programatically select a conversation.
+     *
+     * @param conversationId
+     *
+     * @remarks
+     * Note that this **will not** trigger the
+     * {@linkcode ConversationListProps.onSelectConversation} callback.
+     */
     selectConversation(conversationId: string): void;
 }
 
+/**
+ * @public
+ */
 declare interface Coordinates {
     latitude: number;
     longitude: number;
 }
 
-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;
 }
 
@@ -305,65 +829,203 @@ 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;
 }
 
+/**
+ * @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
@@ -371,7 +1033,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
@@ -400,64 +1062,136 @@ declare type NullishConversationListProps = {
     [K in keyof Omit<ConversationListProps, "className" | "style">]: ConversationListProps[K] | null | undefined;
 };
 
+/**
+ * @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;
 }
 
@@ -521,35 +1255,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;
 }
 
@@ -563,29 +1376,3 @@ declare global {
     }
 }
 
-
-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;
-    }
-}
-