@assistant-ui/react 0.12.0 → 0.12.3

package/src/primitives/assistantModal/AssistantModalRoot.tsx

@@ -28,7 +28,7 @@ const useAssistantModalOpenState = ({
     return aui.on("thread.runStart", () => {
       setOpen(true);
     });
-  }, [unstable_openOnRunStart, setOpen, aui]);
+  }, [unstable_openOnRunStart, aui]);
 
   return state;
 };

package/src/primitives/index.ts

@@ -8,6 +8,7 @@ export * as MessagePartPrimitive from "./messagePart";
 export * as ErrorPrimitive from "./error";
 export * as MessagePrimitive from "./message";
 export * as ThreadPrimitive from "./thread";
+export * as SuggestionPrimitive from "./suggestion";
 export * as ThreadListPrimitive from "./threadList";
 export * as ThreadListItemPrimitive from "./threadListItem";
 export * as ThreadListItemMorePrimitive from "./threadListItemMore";

package/src/primitives/message/MessageParts.tsx

@@ -242,6 +242,17 @@ export namespace MessagePrimitiveParts {
           ReasoningGroup?: ReasoningGroupComponent;
         }
       | undefined;
+    /**
+     * When enabled, shows the Empty component if the last part in the message
+     * is anything other than Text or Reasoning.
+     *
+     * This can be useful to ensure there's always a visible element at the end
+     * of messages that end with non-text content like tool calls or images.
+     *
+     * @experimental This API is experimental and may change in future versions.
+     * @default true
+     */
+    unstable_showEmptyOnNonTextEnd?: boolean | undefined;
   };
 }
 
@@ -429,6 +440,30 @@ const EmptyParts = memo(
     prev.components?.Text === next.components?.Text,
 );
 
+const ConditionalEmptyImpl: FC<{
+  components: MessagePrimitiveParts.Props["components"];
+  enabled: boolean;
+}> = ({ components, enabled }) => {
+  const shouldShowEmpty = useAuiState(({ message }) => {
+    if (!enabled) return false;
+    if (message.parts.length === 0) return false;
+
+    const lastPart = message.parts[message.parts.length - 1];
+    return lastPart?.type !== "text" && lastPart?.type !== "reasoning";
+  });
+
+  if (!shouldShowEmpty) return null;
+  return <EmptyParts components={components} />;
+};
+
+const ConditionalEmpty = memo(
+  ConditionalEmptyImpl,
+  (prev, next) =>
+    prev.enabled === next.enabled &&
+    prev.components?.Empty === next.components?.Empty &&
+    prev.components?.Text === next.components?.Text,
+);
+
 /**
  * Renders the parts of a message with support for multiple content types.
  *
@@ -455,6 +490,7 @@ const EmptyParts = memo(
  */
 export const MessagePrimitiveParts: FC<MessagePrimitiveParts.Props> = ({
   components,
+  unstable_showEmptyOnNonTextEnd = true,
 }) => {
   const contentLength = useAuiState(({ message }) => message.parts.length);
   const messageRanges = useMessagePartsGroups();
@@ -520,7 +556,15 @@ export const MessagePrimitiveParts: FC<MessagePrimitiveParts.Props> = ({
     });
   }, [messageRanges, components, contentLength]);
 
-  return <>{partsElements}</>;
+  return (
+    <>
+      {partsElements}
+      <ConditionalEmpty
+        components={components}
+        enabled={unstable_showEmptyOnNonTextEnd}
+      />
+    </>
+  );
 };
 
 MessagePrimitiveParts.displayName = "MessagePrimitive.Parts";

package/src/primitives/suggestion/SuggestionDescription.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+import { Primitive } from "@radix-ui/react-primitive";
+import { type ElementRef, forwardRef, ComponentPropsWithoutRef } from "react";
+import { useAuiState } from "@assistant-ui/store";
+
+export namespace SuggestionPrimitiveDescription {
+  export type Element = ElementRef<typeof Primitive.span>;
+  export type Props = ComponentPropsWithoutRef<typeof Primitive.span>;
+}
+
+/**
+ * Renders the description/label of the suggestion.
+ *
+ * @example
+ * ```tsx
+ * <SuggestionPrimitive.Description />
+ * ```
+ */
+export const SuggestionPrimitiveDescription = forwardRef<
+  SuggestionPrimitiveDescription.Element,
+  SuggestionPrimitiveDescription.Props
+>((props, ref) => {
+  const label = useAuiState(({ suggestion }) => suggestion.label);
+
+  return (
+    <Primitive.span {...props} ref={ref}>
+      {props.children ?? label}
+    </Primitive.span>
+  );
+});
+
+SuggestionPrimitiveDescription.displayName = "SuggestionPrimitive.Description";

package/src/primitives/suggestion/SuggestionTitle.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+import { Primitive } from "@radix-ui/react-primitive";
+import { type ElementRef, forwardRef, ComponentPropsWithoutRef } from "react";
+import { useAuiState } from "@assistant-ui/store";
+
+export namespace SuggestionPrimitiveTitle {
+  export type Element = ElementRef<typeof Primitive.span>;
+  export type Props = ComponentPropsWithoutRef<typeof Primitive.span>;
+}
+
+/**
+ * Renders the title of the suggestion.
+ *
+ * @example
+ * ```tsx
+ * <SuggestionPrimitive.Title />
+ * ```
+ */
+export const SuggestionPrimitiveTitle = forwardRef<
+  SuggestionPrimitiveTitle.Element,
+  SuggestionPrimitiveTitle.Props
+>((props, ref) => {
+  const title = useAuiState(({ suggestion }) => suggestion.title);
+
+  return (
+    <Primitive.span {...props} ref={ref}>
+      {props.children ?? title}
+    </Primitive.span>
+  );
+});
+
+SuggestionPrimitiveTitle.displayName = "SuggestionPrimitive.Title";

package/src/primitives/suggestion/SuggestionTrigger.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+import {
+  ActionButtonElement,
+  ActionButtonProps,
+  createActionButton,
+} from "../../utils/createActionButton";
+import { useCallback } from "react";
+import { useAuiState, useAui } from "@assistant-ui/store";
+
+const useSuggestionTrigger = ({
+  send,
+  clearComposer = true,
+}: {
+  /**
+   * When true, automatically sends the message.
+   * When false, replaces or appends the composer text with the suggestion - depending on the value of `clearComposer`.
+   */
+  send?: boolean | undefined;
+
+  /**
+   * Whether to clear the composer after sending.
+   * When send is set to false, determines if composer text is replaced with suggestion (true, default),
+   * or if it's appended to the composer text (false).
+   *
+   * @default true
+   */
+  clearComposer?: boolean | undefined;
+}) => {
+  const aui = useAui();
+  const disabled = useAuiState(({ thread }) => thread.isDisabled);
+  const prompt = useAuiState(({ suggestion }) => suggestion.prompt);
+
+  const resolvedSend = send ?? false;
+
+  const callback = useCallback(() => {
+    const isRunning = aui.thread().getState().isRunning;
+
+    if (resolvedSend && !isRunning) {
+      aui.thread().append(prompt);
+      if (clearComposer) {
+        aui.composer().setText("");
+      }
+    } else {
+      if (clearComposer) {
+        aui.composer().setText(prompt);
+      } else {
+        const currentText = aui.composer().getState().text;
+        aui
+          .composer()
+          .setText(currentText.trim() ? `${currentText} ${prompt}` : prompt);
+      }
+    }
+  }, [aui, resolvedSend, clearComposer, prompt]);
+
+  if (disabled) return null;
+  return callback;
+};
+
+export namespace SuggestionPrimitiveTrigger {
+  export type Element = ActionButtonElement;
+  export type Props = ActionButtonProps<typeof useSuggestionTrigger>;
+}
+
+/**
+ * A button that triggers the suggestion action (send or insert into composer).
+ *
+ * @example
+ * ```tsx
+ * <SuggestionPrimitive.Trigger send>
+ *   Click me
+ * </SuggestionPrimitive.Trigger>
+ * ```
+ */
+export const SuggestionPrimitiveTrigger = createActionButton(
+  "SuggestionPrimitive.Trigger",
+  useSuggestionTrigger,
+  ["send", "clearComposer"],
+);

package/src/primitives/suggestion/index.ts

@@ -0,0 +1,3 @@
+export { SuggestionPrimitiveTitle as Title } from "./SuggestionTitle";
+export { SuggestionPrimitiveDescription as Description } from "./SuggestionDescription";
+export { SuggestionPrimitiveTrigger as Trigger } from "./SuggestionTrigger";

package/src/primitives/thread/ThreadSuggestions.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import { type ComponentType, type FC, memo, useMemo } from "react";
+import { useAuiState } from "@assistant-ui/store";
+import { SuggestionByIndexProvider } from "../../context/providers";
+
+export namespace ThreadPrimitiveSuggestions {
+  export type Props = {
+    /**
+     * Component to render for each suggestion.
+     */
+    components: {
+      /** Component used to render each suggestion */
+      Suggestion: ComponentType;
+    };
+  };
+}
+
+type SuggestionComponentProps = {
+  components: ThreadPrimitiveSuggestions.Props["components"];
+};
+
+const SuggestionComponent: FC<SuggestionComponentProps> = ({ components }) => {
+  const Component = components.Suggestion;
+  return <Component />;
+};
+
+export namespace ThreadPrimitiveSuggestionByIndex {
+  export type Props = {
+    index: number;
+    components: ThreadPrimitiveSuggestions.Props["components"];
+  };
+}
+
+/**
+ * Renders a single suggestion at the specified index.
+ *
+ * This component provides suggestion context for a specific suggestion
+ * and renders it using the provided component configuration.
+ *
+ * @example
+ * ```tsx
+ * <ThreadPrimitive.SuggestionByIndex
+ *   index={0}
+ *   components={{
+ *     Suggestion: MySuggestion
+ *   }}
+ * />
+ * ```
+ */
+export const ThreadPrimitiveSuggestionByIndex: FC<ThreadPrimitiveSuggestionByIndex.Props> =
+  memo(
+    ({ index, components }) => {
+      return (
+        <SuggestionByIndexProvider index={index}>
+          <SuggestionComponent components={components} />
+        </SuggestionByIndexProvider>
+      );
+    },
+    (prev, next) =>
+      prev.index === next.index &&
+      prev.components.Suggestion === next.components.Suggestion,
+  );
+
+ThreadPrimitiveSuggestionByIndex.displayName =
+  "ThreadPrimitive.SuggestionByIndex";
+
+/**
+ * Renders all suggestions using the provided component configuration.
+ *
+ * This component automatically renders all suggestions from the suggestions scope,
+ * providing the appropriate suggestion context for each one.
+ *
+ * @example
+ * ```tsx
+ * <ThreadPrimitive.Suggestions
+ *   components={{
+ *     Suggestion: MySuggestion
+ *   }}
+ * />
+ * ```
+ */
+export const ThreadPrimitiveSuggestionsImpl: FC<
+  ThreadPrimitiveSuggestions.Props
+> = ({ components }) => {
+  const suggestionsLength = useAuiState(
+    ({ suggestions }) => suggestions.suggestions.length,
+  );
+
+  const suggestionElements = useMemo(() => {
+    if (suggestionsLength === 0) return null;
+    return Array.from({ length: suggestionsLength }, (_, index) => (
+      <ThreadPrimitiveSuggestionByIndex
+        key={index}
+        index={index}
+        components={components}
+      />
+    ));
+  }, [suggestionsLength, components]);
+
+  return suggestionElements;
+};
+
+ThreadPrimitiveSuggestionsImpl.displayName = "ThreadPrimitive.Suggestions";
+
+export const ThreadPrimitiveSuggestions = memo(
+  ThreadPrimitiveSuggestionsImpl,
+  (prev, next) => prev.components.Suggestion === next.components.Suggestion,
+);

package/src/primitives/thread/index.ts

@@ -9,3 +9,7 @@ export { ThreadPrimitiveMessages as Messages } from "./ThreadMessages";
 export { ThreadPrimitiveMessageByIndex as MessageByIndex } from "./ThreadMessages";
 export { ThreadPrimitiveScrollToBottom as ScrollToBottom } from "./ThreadScrollToBottom";
 export { ThreadPrimitiveSuggestion as Suggestion } from "./ThreadSuggestion";
+export {
+  ThreadPrimitiveSuggestions as Suggestions,
+  ThreadPrimitiveSuggestionByIndex as SuggestionByIndex,
+} from "./ThreadSuggestions";

package/src/tests/external-message-converter.test.ts

@@ -1,16 +1,10 @@
 import { describe, it, expect } from "vitest";
 import { convertExternalMessages } from "../legacy-runtime/runtime-cores/external-store/external-message-converter";
 import type { useExternalMessageConverter } from "../legacy-runtime/runtime-cores/external-store/external-message-converter";
+import { isErrorMessageId } from "../utils/idUtils";
 
-/**
- * Tests for the external message converter, specifically the joinExternalMessages logic.
- */
 describe("convertExternalMessages", () => {
   describe("reasoning part merging", () => {
-    /**
-     * Tests that reasoning parts with the same parentId are merged together.
-     * The text should be concatenated with a double newline separator.
-     */
     it("should merge reasoning parts with the same parentId", () => {
       const messages = [
         {
@@ -56,9 +50,6 @@ describe("convertExternalMessages", () => {
       expect((reasoningParts[0] as any).parentId).toBe("parent1");
     });
 
-    /**
-     * Tests that reasoning parts without parentId remain separate.
-     */
     it("should keep reasoning parts without parentId separate", () => {
       const messages = [
         {
@@ -89,9 +80,6 @@ describe("convertExternalMessages", () => {
       expect((reasoningParts[1] as any).text).toBe("Second reasoning");
     });
 
-    /**
-     * Tests that reasoning parts with different parentIds remain separate.
-     */
     it("should keep reasoning parts with different parentIds separate", () => {
       const messages = [
         {
@@ -134,9 +122,6 @@ describe("convertExternalMessages", () => {
       expect((reasoningParts[1] as any).parentId).toBe("parent2");
     });
 
-    /**
-     * Tests that tool result merging still works correctly alongside reasoning merging.
-     */
     it("should still merge tool results with matching tool calls", () => {
       const messages = [
         {
@@ -174,4 +159,108 @@ describe("convertExternalMessages", () => {
       expect((toolCallParts[0] as any).result).toEqual({ data: "result" });
     });
   });
+
+  describe("synthetic error message", () => {
+    it("should create synthetic error message when error exists and no messages", () => {
+      const messages: never[] = [];
+      const callback: useExternalMessageConverter.Callback<never> = (msg) =>
+        msg;
+
+      const result = convertExternalMessages(messages, callback, false, {
+        error: "API key is missing",
+      });
+
+      expect(result).toHaveLength(1);
+      expect(result[0]!.role).toBe("assistant");
+      expect(result[0]!.content).toHaveLength(0);
+      expect(result[0]!.status).toEqual({
+        type: "incomplete",
+        reason: "error",
+        error: "API key is missing",
+      });
+      expect(isErrorMessageId(result[0]!.id)).toBe(true);
+    });
+
+    it("should create synthetic error message when error exists and last message is user", () => {
+      const messages = [
+        {
+          id: "user1",
+          role: "user" as const,
+          content: "Hello",
+        },
+      ];
+
+      const callback: useExternalMessageConverter.Callback<
+        (typeof messages)[number]
+      > = (msg) => msg;
+
+      const result = convertExternalMessages(messages, callback, false, {
+        error: { message: "Invalid API key" },
+      });
+
+      expect(result).toHaveLength(2);
+      expect(result[0]!.role).toBe("user");
+      expect(result[1]!.role).toBe("assistant");
+      expect(result[1]!.content).toHaveLength(0);
+      expect(result[1]!.status).toEqual({
+        type: "incomplete",
+        reason: "error",
+        error: { message: "Invalid API key" },
+      });
+      expect(isErrorMessageId(result[1]!.id)).toBe(true);
+    });
+
+    it("should not create synthetic error message when last message is assistant", () => {
+      const messages = [
+        {
+          id: "user1",
+          role: "user" as const,
+          content: "Hello",
+        },
+        {
+          id: "assistant1",
+          role: "assistant" as const,
+          content: "Hi there",
+        },
+      ];
+
+      const callback: useExternalMessageConverter.Callback<
+        (typeof messages)[number]
+      > = (msg) => msg;
+
+      const result = convertExternalMessages(messages, callback, false, {
+        error: "Connection error",
+      });
+
+      expect(result).toHaveLength(2);
+      expect(result[0]!.role).toBe("user");
+      expect(result[1]!.role).toBe("assistant");
+      expect(result[1]!.id).toBe("assistant1");
+      expect(result[1]!.status).toMatchObject({
+        type: "incomplete",
+        reason: "error",
+        error: "Connection error",
+      });
+      expect(isErrorMessageId(result[1]!.id)).toBe(false);
+    });
+
+    it("should not create synthetic message when no error", () => {
+      const messages = [
+        {
+          id: "user1",
+          role: "user" as const,
+          content: "Hello",
+        },
+      ];
+
+      const callback: useExternalMessageConverter.Callback<
+        (typeof messages)[number]
+      > = (msg) => msg;
+
+      const result = convertExternalMessages(messages, callback, false, {});
+
+      expect(result).toHaveLength(1);
+      expect(result[0]!.role).toBe("user");
+    });
+  });
 });

package/src/types/scopes/index.ts

@@ -43,6 +43,18 @@ export type {
   AttachmentClientSchema,
 } from "./attachment";
 export type { ToolsState, ToolsMethods, ToolsClientSchema } from "./tools";
+export type {
+  SuggestionsState,
+  SuggestionsMethods,
+  SuggestionsClientSchema,
+  Suggestion,
+} from "./suggestions";
+export type {
+  SuggestionState,
+  SuggestionMethods,
+  SuggestionMeta,
+  SuggestionClientSchema,
+} from "./suggestion";
 export type {
   ModelContextState,
   ModelContextMethods,

package/src/types/scopes/suggestion.ts

@@ -0,0 +1,20 @@
+export type SuggestionState = {
+  title: string;
+  label: string;
+  prompt: string;
+};
+
+export type SuggestionMethods = {
+  getState(): SuggestionState;
+};
+
+export type SuggestionMeta = {
+  source: "suggestions";
+  query: { index: number };
+};
+
+export type SuggestionClientSchema = {
+  state: SuggestionState;
+  methods: SuggestionMethods;
+  meta: SuggestionMeta;
+};

package/src/types/scopes/suggestions.ts

@@ -0,0 +1,21 @@
+import type { SuggestionMethods } from "./suggestion";
+
+export type Suggestion = {
+  title: string;
+  label: string;
+  prompt: string;
+};
+
+export type SuggestionsState = {
+  suggestions: Suggestion[];
+};
+
+export type SuggestionsMethods = {
+  getState(): SuggestionsState;
+  suggestion(query: { index: number }): SuggestionMethods;
+};
+
+export type SuggestionsClientSchema = {
+  state: SuggestionsState;
+  methods: SuggestionsMethods;
+};

package/src/types/store-augmentation.ts

@@ -9,6 +9,8 @@ import type { ComposerClientSchema } from "./scopes/composer";
 import type { AttachmentClientSchema } from "./scopes/attachment";
 import type { ToolsClientSchema } from "./scopes/tools";
 import type { ModelContextClientSchema } from "./scopes/modelContext";
+import type { SuggestionsClientSchema } from "./scopes/suggestions";
+import type { SuggestionClientSchema } from "./scopes/suggestion";
 
 declare module "@assistant-ui/store" {
   interface ClientRegistry {
@@ -21,5 +23,7 @@ declare module "@assistant-ui/store" {
     attachment: AttachmentClientSchema;
     tools: ToolsClientSchema;
     modelContext: ModelContextClientSchema;
+    suggestions: SuggestionsClientSchema;
+    suggestion: SuggestionClientSchema;
   }
 }

package/src/utils/idUtils.tsx

@@ -8,3 +8,7 @@ export const generateId = customAlphabet(
 const optimisticPrefix = "__optimistic__";
 export const generateOptimisticId = () => `${optimisticPrefix}${generateId()}`;
 export const isOptimisticId = (id: string) => id.startsWith(optimisticPrefix);
+
+const errorPrefix = "__error__";
+export const generateErrorMessageId = () => `${errorPrefix}${generateId()}`;
+export const isErrorMessageId = (id: string) => id.startsWith(errorPrefix);