@liveblocks/react-ui 2.25.0-aiprivatebeta9 → 3.0.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ComponentType, ComponentPropsWithoutRef, ElementType, ReactNode, ComponentProps, FormEvent, RefAttributes, MouseEvent, PropsWithChildren } from 'react';
-import { CommentAttachment, AiKnowledgeSource, AiOpaqueToolDefinition, AiToolTypePack, JsonObject, ToolResultData, AiToolExecuteCallback, CommentBody, BaseMetadata, DM, CommentData, HistoryVersion, InboxNotificationData, InboxNotificationThreadData, InboxNotificationTextMentionData, InboxNotificationCustomData, KDAD, ThreadData } from '@liveblocks/core';
+import { CommentAttachment, AiKnowledgeSource, AiOpaqueToolDefinition, AiToolTypePack, JsonObject, AiToolExecuteCallback, NoInfr, CommentBody, MentionData, BaseMetadata, DM, CommentData, HistoryVersion, InboxNotificationData, InboxNotificationThreadData, InboxNotificationTextMentionData, InboxNotificationCustomData, KDAD, ThreadData } from '@liveblocks/core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface GlobalComponents {
@@ -54,6 +54,7 @@ interface GlobalOverrides {
     EMOJI_PICKER_CHANGE_SKIN_TONE: string;
     ATTACHMENT_TOO_LARGE: (maxSize?: string) => string;
     ATTACHMENT_ERROR: (error: Error) => string;
+    COPY_TO_CLIPBOARD: string;
 }
 interface CommentOverrides {
     COMMENT_EDITED: ReactNode;
@@ -78,6 +79,10 @@ interface ComposerOverrides {
     COMPOSER_SEND: string;
     COMPOSER_TOGGLE_MARK: (mark: ComposerBodyMark) => string;
 }
+interface AiToolConfirmationOverrides {
+    AI_TOOL_CONFIRMATION_CONFIRM: string;
+    AI_TOOL_CONFIRMATION_CANCEL: string;
+}
 interface AiChatComposerOverrides {
     AI_CHAT_COMPOSER_PLACEHOLDER: string;
     AI_CHAT_COMPOSER_SEND: string;
@@ -86,6 +91,7 @@ interface AiChatComposerOverrides {
 interface AiChatMessageOverrides {
     AI_CHAT_MESSAGE_DELETED: string;
     AI_CHAT_MESSAGE_THINKING: string;
+    AI_CHAT_MESSAGE_REASONING: (isStreaming: boolean) => string;
 }
 interface AiChatOverrides {
     AI_CHAT_MESSAGES_ERROR: (error: Error) => ReactNode;
@@ -114,13 +120,28 @@ interface HistoryVersionPreviewOverrides {
     HISTORY_VERSION_PREVIEW_EMPTY: ReactNode;
     HISTORY_VERSION_PREVIEW_ERROR: (error: Error) => ReactNode;
 }
-type Overrides = LocalizationOverrides & GlobalOverrides & ComposerOverrides & CommentOverrides & ThreadOverrides & InboxNotificationOverrides & HistoryVersionPreviewOverrides & AiChatComposerOverrides & AiChatMessageOverrides & AiChatOverrides;
+type Overrides = LocalizationOverrides & GlobalOverrides & ComposerOverrides & CommentOverrides & ThreadOverrides & InboxNotificationOverrides & HistoryVersionPreviewOverrides & AiChatComposerOverrides & AiChatMessageOverrides & AiChatOverrides & AiToolConfirmationOverrides;
 declare function useOverrides(overrides?: Partial<Overrides>): Overrides;
 
-type AiChatComponentsEmptyProps = Record<string, never>;
+type AiChatComponentsEmptyProps = {
+    /**
+     * The chat id provided to the `AiChat` component.
+     */
+    chatId: string;
+    /**
+     * The copilot id provided to the `AiChat` component.
+     */
+    copilotId?: string;
+};
 type AiChatComponentsLoadingProps = Record<string, never>;
 type AiChatComponents = {
+    /**
+     * The component used to render the empty state of the chat.
+     */
     Empty: ComponentType<AiChatComponentsEmptyProps>;
+    /**
+     * The component used to render the loading state of the chat.
+     */
     Loading: ComponentType<AiChatComponentsLoadingProps>;
 };
 interface AiChatProps extends ComponentProps<"div"> {
@@ -177,26 +198,204 @@ interface AiToolProps extends Omit<ComponentProps<"div">, "title" | "children">
      * The content shown in the tool.
      */
     children?: ReactNode;
+    /**
+     * Whether the content is currently collapsed.
+     * It is not a traditional controlled value, as in if you set it to `true` it would only stay expanded.
+     * Instead, it is "semi-controlled", meaning that setting it to `true` will expand it, but it
+     * can still be collapsed/expanded by clicking on it.
+     */
+    collapsed?: boolean;
+    /**
+     * The event handler called when the content is collapsed or expanded by clicking on it.
+     */
+    onCollapsedChange?: (collapsed: boolean) => void;
 }
 type AiToolIconProps = ComponentProps<"div">;
 type AiToolInspectorProps = ComponentProps<"div">;
-/**
- * @private This API will change, and is not considered stable. DO NOT RELY on it.
- *
- * This component can be used to build human-in-the-loop interfaces.
- */
-interface AiToolConfirmationProps<A extends JsonObject, R extends ToolResultData> extends ComponentProps<"div"> {
-    args?: A;
+interface AiToolConfirmationProps<A extends JsonObject, R extends JsonObject> extends ComponentProps<"div"> {
+    /**
+     * The callback invoked when the user clicks the confirm button.
+     */
     confirm: AiToolExecuteCallback<A, R>;
-    cancel: AiToolExecuteCallback<A, R>;
+    /**
+     * The callback invoked when the user clicks the cancel button.
+     */
+    cancel?: AiToolExecuteCallback<A, R>;
+    /**
+     * The visual appearance.
+     */
     variant?: "default" | "destructive";
+    /**
+     * Override the component's strings.
+     */
+    overrides?: Partial<GlobalOverrides & AiToolConfirmationOverrides>;
+    /**
+     * The tool's result type, to be used with the `types` prop in the `render` method.
+     *
+     * @example
+     * defineAiTool<{ value: number }>()({
+     *   // ...
+     *   render: ({ types }) => (
+     *     <AiTool.Confirmation
+     *       types={types}
+     *       confirm={() => {
+     *         return {
+     *           // Using `types` makes the result type-safe
+     *           // based on the tool's definition
+     *           data: { value: 123 },
+     *         };
+     *       }}
+     *     />
+     *   ),
+     * })
+     */
+    types?: NoInfr<AiToolTypePack<A, R>>;
 }
 declare function AiToolIcon({ className, ...props }: AiToolIconProps): react_jsx_runtime.JSX.Element;
 declare function AiToolInspector({ className, ...props }: AiToolInspectorProps): react_jsx_runtime.JSX.Element;
-declare function AiToolConfirmation<TPack extends AiToolTypePack, A extends JsonObject = TPack["A"], R extends ToolResultData = TPack["R"]>({ children, variant, confirm, cancel, className, ...props }: AiToolConfirmationProps<A, R>): react_jsx_runtime.JSX.Element | null;
+declare function AiToolConfirmation<TPack extends AiToolTypePack, A extends JsonObject = TPack["A"], R extends JsonObject = TPack["R"]>({ children, variant, confirm, cancel, overrides, className, ...props }: AiToolConfirmationProps<A, R>): react_jsx_runtime.JSX.Element | null;
+/**
+ * A pre-built component which displays a tool call.
+ *
+ * By default, a human-readable version of the tool's name is used as a title:
+ * - `"showTodo"` → "Show todo"
+ * - `"get_weather"` → "Get weather"
+ *
+ * @example
+ * defineAiTool()({
+ *   // ...
+ *   render: () => (
+ *     <AiTool />
+ *   ),
+ * })
+ *
+ * It can be customized in various ways:
+ * - adding an icon
+ * - customizing the title (even dynamically)
+ * - adding custom content inside it
+ * - collapsing it conditionally
+ * - etc.
+ *
+ * @example
+ * defineAiTool()({
+ *   // ...
+ *   render: ({ stage, result }) => (
+ *     <AiTool
+ *       icon="🔍"
+ *
+ *       // Override the default title based on the tool's stage
+ *       title={stage === "executing" ? "Searching…" : "Search results"}
+ *
+ *       // Start open and automatically collapse after it is executed
+ *       // The user can still expand/collapse it manually at any time
+ *       collapsed={stage === "executed"}
+ *     >
+ *       <SearchResults data={result.data} />
+ *     </AiTool>
+ *   ),
+ * })
+ *
+ * It also comes with a few built-in sub-components:
+ * - `AiTool.Confirmation` to display a human-in-the-loop confirmation step
+ *   which can be accepted or cancelled by the user.
+ * - `AiTool.Inspector` to display the tool's arguments and result which can
+ *   be useful during development.
+ *
+ * @example
+ * defineAiTool()({
+ *   // ...
+ *   render: () => (
+ *     <AiTool>
+ *       <AiTool.Confirmation
+ *         // Use a destructive visual appearance
+ *         variant="destructive"
+ *
+ *         // The tool's arguments can be directly accessed like in `execute`
+ *         confirm={({ pageIds }) => {
+ *           const deletedPageTitles = pages
+ *             .filter((p) => pageIds.includes(p.id))
+ *             .map((page) => page.title);
+ *
+ *           deletePages(pageIds);
+ *
+ *           // This result will be available as `result` in the tool's `render` props
+ *           return { data: { deletedPageTitles } };
+ *         }}
+ *
+ *         // If needed, `cancel={() => ...}` would work similarly
+ *       >
+ *         Do you want to delete these pages?
+ *         <PagesPreviews />
+ *       </AiTool.Confirmation>
+ *     </AiTool>
+ *   ),
+ * })
+ *
+ * @example
+ * defineAiTool()({
+ *   // ...
+ *   render: () => (
+ *     <AiTool>
+ *       <AiTool.Inspector />
+ *     </AiTool>
+ *   ),
+ * })
+ */
 declare const AiTool: react.ForwardRefExoticComponent<Omit<AiToolProps, "ref"> & react.RefAttributes<HTMLDivElement>> & {
+    /**
+     * Display an icon in a container.
+     *
+     * @example
+     * <AiTool
+     *   icon={
+     *     <AiTool.Icon>🔍</AiTool.Icon>
+     *   }
+     * />
+     */
     Icon: typeof AiToolIcon;
+    /**
+     * Display the tool's arguments and result, which can be useful during
+     * development.
+     *
+     * @example
+     * <AiTool>
+     *   <AiTool.Inspector />
+     * </AiTool>
+     */
     Inspector: typeof AiToolInspector;
+    /**
+     * Display a human-in-the-loop confirmation step which can be accepted
+     * or cancelled by the user.
+     *
+     * The `confirm` and `cancel` callbacks work like `execute` in tool definitions: they can
+     * perform side-effects, be async if needed, and return a result. The tool call will stay
+     * pending until either `confirm` or `cancel` is called.
+     *
+     * @example
+     * <AiTool>
+     *   <AiTool.Confirmation
+     *     // Use a destructive visual appearance
+     *     variant="destructive"
+     *
+     *     // The tool's arguments can be directly accessed like in `execute`
+     *     confirm={({ pageIds }) => {
+     *       const deletedPageTitles = pages
+     *         .filter((p) => pageIds.includes(p.id))
+     *         .map((page) => page.title);
+     *
+     *       deletePages(pageIds);
+     *
+     *       // This result will be available as `result` in the tool's `render` props
+     *       return { data: { deletedPageTitles } };
+     *     }}
+     *
+     *     // If needed, `cancel={() => ...}` would work similarly
+     *   >
+     *     Do you want to delete these pages?
+     *     <PagesPreviews />
+     *   </AiTool.Confirmation>
+     * </AiTool>
+     */
     Confirmation: typeof AiToolConfirmation;
 };
 
@@ -206,9 +405,9 @@ interface ComposerEditorMentionProps {
      */
     isSelected: boolean;
     /**
-     * The mention's user ID.
+     * The mention to display.
      */
-    userId: string;
+    mention: MentionData;
 }
 interface ComposerEditorLinkProps {
     /**
@@ -226,13 +425,13 @@ interface ComposerEditorLinkProps {
 }
 type ComposerEditorMentionSuggestionsProps = {
     /**
-     * The list of suggested user IDs.
+     * The list of mention suggestions.
      */
-    userIds: string[];
+    mentions: MentionData[];
     /**
-     * The currently selected user ID.
+     * The currently selected mention's ID.
      */
-    selectedUserId?: string;
+    selectedMentionId?: string;
 };
 type ComposerEditorFloatingToolbarProps = Record<string, never>;
 interface ComposerEditorComponents {
@@ -253,7 +452,7 @@ interface ComposerEditorComponents {
      */
     FloatingToolbar?: ComponentType<ComposerEditorFloatingToolbarProps>;
 }
-interface ComposerEditorProps extends Omit<ComponentPropsWithoutRef<"div">, "defaultValue"> {
+interface ComposerEditorProps extends Omit<ComponentPropsWithoutRef<"div">, "defaultValue" | "children"> {
     /**
      * The reading direction of the editor and related elements.
      */
@@ -446,7 +645,7 @@ interface CommentProps extends ComponentPropsWithoutRef<"div"> {
     /**
      * The event handler called when clicking on a mention.
      */
-    onMentionClick?: (userId: string, event: MouseEvent<HTMLElement>) => void;
+    onMentionClick?: (mention: MentionData, event: MouseEvent<HTMLElement>) => void;
     /**
      * The event handler called when clicking on a comment's attachment.
      */
@@ -455,6 +654,10 @@ interface CommentProps extends ComponentPropsWithoutRef<"div"> {
      * Override the component's strings.
      */
     overrides?: Partial<GlobalOverrides & CommentOverrides & ComposerOverrides>;
+    /**
+     * Override the component's components.
+     */
+    components?: Partial<GlobalComponents>;
 }
 /**
  * Displays a single comment.
@@ -712,6 +915,10 @@ interface ThreadProps<M extends BaseMetadata = DM> extends ComponentPropsWithout
      * Override the component's strings.
      */
     overrides?: Partial<GlobalOverrides & ThreadOverrides & CommentOverrides & ComposerOverrides>;
+    /**
+     * Override the component's components.
+     */
+    components?: Partial<GlobalComponents>;
 }
 /**
  * Displays a thread of comments, with a composer to reply
@@ -726,7 +933,7 @@ interface ThreadProps<M extends BaseMetadata = DM> extends ComponentPropsWithout
  */
 declare const Thread: <M extends BaseMetadata = DM>(props: ThreadProps<M> & RefAttributes<HTMLDivElement>) => JSX.Element;
 
-type LiveblocksUIConfigProps = PropsWithChildren<{
+type LiveblocksUiConfigProps = PropsWithChildren<{
     /**
      * Override the components' strings.
      */
@@ -770,11 +977,11 @@ type LiveblocksUIConfigProps = PropsWithChildren<{
  * Set configuration options for all components.
  *
  * @example
- * <LiveblocksUIConfig overrides={{ locale: "fr", USER_UNKNOWN: "Anonyme", ... }}>
+ * <LiveblocksUiConfig overrides={{ locale: "fr", USER_UNKNOWN: "Anonyme", ... }}>
  *   <App />
- * </LiveblocksUIConfig>
+ * </LiveblocksUiConfig>
  */
-declare function LiveblocksUIConfig({ overrides, components, portalContainer, preventUnsavedComposerChanges, emojibaseUrl, children, }: LiveblocksUIConfigProps): react_jsx_runtime.JSX.Element;
+declare function LiveblocksUiConfig({ overrides, components, portalContainer, preventUnsavedComposerChanges, emojibaseUrl, children, }: LiveblocksUiConfigProps): react_jsx_runtime.JSX.Element;
 
 declare function ArrowCornerDownRightIcon(props: ComponentProps<"svg">): react_jsx_runtime.JSX.Element;
 
@@ -916,4 +1123,4 @@ declare namespace icon {
   };
 }
 
-export { AiChat, AiChatProps, AiTool, AiToolIconProps, AiToolProps, Comment, CommentAttachmentArgs, CommentOverrides, CommentProps, Composer, ComposerBodyMark, ComposerBodyMarks, ComposerOverrides, ComposerProps, ComposerSubmitComment, GlobalOverrides, HistoryVersionSummary, HistoryVersionSummaryList, HistoryVersionSummaryListProps, HistoryVersionSummaryProps, icon as Icon, InboxNotification, InboxNotificationAvatarProps, InboxNotificationCustomKindProps, InboxNotificationCustomProps, InboxNotificationIconProps, InboxNotificationList, InboxNotificationListProps, InboxNotificationOverrides, InboxNotificationProps, InboxNotificationTextMentionKindProps, InboxNotificationTextMentionProps, InboxNotificationThreadKindProps, InboxNotificationThreadProps, LiveblocksUIConfig, LocalizationOverrides, Overrides, Thread, ThreadOverrides, ThreadProps, useOverrides };
+export { AiChat, AiChatComponents, AiChatComponentsEmptyProps, AiChatComponentsLoadingProps, AiChatProps, AiTool, AiToolIconProps, AiToolProps, Comment, CommentAttachmentArgs, CommentOverrides, CommentProps, Composer, ComposerBodyMark, ComposerBodyMarks, ComposerOverrides, ComposerProps, ComposerSubmitComment, GlobalOverrides, HistoryVersionSummary, HistoryVersionSummaryList, HistoryVersionSummaryListProps, HistoryVersionSummaryProps, icon as Icon, InboxNotification, InboxNotificationAvatarProps, InboxNotificationCustomKindProps, InboxNotificationCustomProps, InboxNotificationIconProps, InboxNotificationList, InboxNotificationListProps, InboxNotificationOverrides, InboxNotificationProps, InboxNotificationTextMentionKindProps, InboxNotificationTextMentionProps, InboxNotificationThreadKindProps, InboxNotificationThreadProps, LiveblocksUiConfig, LocalizationOverrides, Overrides, Thread, ThreadOverrides, ThreadProps, useOverrides };