@btst/stack 1.4.0 → 1.4.1

package/dist/shared/stack.DaOcgmrM.d.ts

@@ -0,0 +1,323 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { UIMessage } from 'ai';
+import { ComponentType, FormEvent } from 'react';
+
+/**
+ * AI Chat plugin localization strings
+ */
+interface AiChatLocalization {
+    CHAT_PLACEHOLDER: string;
+    CHAT_SEND_BUTTON: string;
+    CHAT_EMPTY_STATE: string;
+    CHAT_LOADING: string;
+    CHAT_ERROR: string;
+    CHAT_RETRY: string;
+    CHAT_GENERIC_ERROR_TITLE: string;
+    CHAT_GENERIC_ERROR_MESSAGE: string;
+    CHAT_PAGE_NOT_FOUND_TITLE: string;
+    CHAT_PAGE_NOT_FOUND_DESCRIPTION: string;
+    SIDEBAR_TITLE: string;
+    SIDEBAR_NEW_CHAT: string;
+    SIDEBAR_NO_CONVERSATIONS: string;
+    SIDEBAR_SEARCH_PLACEHOLDER: string;
+    CONVERSATION_RENAME: string;
+    CONVERSATION_RENAME_PLACEHOLDER: string;
+    CONVERSATION_RENAME_SAVE: string;
+    CONVERSATION_RENAME_CANCEL: string;
+    CONVERSATION_DELETE: string;
+    CONVERSATION_DELETE_CONFIRM_TITLE: string;
+    CONVERSATION_DELETE_CONFIRM_DESCRIPTION: string;
+    CONVERSATION_DELETE_CONFIRM_BUTTON: string;
+    CONVERSATION_DELETE_CANCEL: string;
+    IMAGE_UPLOAD_BUTTON: string;
+    IMAGE_UPLOAD_UPLOADING: string;
+    IMAGE_UPLOAD_ERROR_NOT_IMAGE: string;
+    IMAGE_UPLOAD_ERROR_TOO_LARGE: string;
+    IMAGE_UPLOAD_SUCCESS: string;
+    IMAGE_UPLOAD_FAILURE: string;
+    FILE_UPLOAD_BUTTON: string;
+    FILE_UPLOAD_ERROR_TOO_LARGE: string;
+    FILE_UPLOAD_SUCCESS: string;
+    FILE_UPLOAD_FAILURE: string;
+    TIME_JUST_NOW: string;
+    TIME_MINUTES_AGO: string;
+    TIME_HOURS_AGO: string;
+    TIME_YESTERDAY: string;
+    TIME_DAYS_AGO: string;
+    MESSAGE_COPY: string;
+    MESSAGE_COPIED: string;
+    MESSAGE_RETRY: string;
+    MESSAGE_EDIT: string;
+    MESSAGE_SAVE: string;
+    MESSAGE_CANCEL: string;
+    A11Y_USER_MESSAGE: string;
+    A11Y_ASSISTANT_MESSAGE: string;
+    A11Y_COPY_CODE: string;
+    A11Y_CODE_COPIED: string;
+}
+
+/**
+ * Plugin mode for AI Chat
+ * - 'authenticated': Conversations persisted with userId (default)
+ * - 'public': Stateless chat, no persistence (ideal for public chatbots)
+ */
+type AiChatMode = "authenticated" | "public";
+/**
+ * State of a tool call execution
+ */
+type ToolCallState = "input-streaming" | "input-available" | "output-available" | "output-error";
+/**
+ * Props passed to custom tool call renderer components
+ */
+interface ToolCallProps<TInput = unknown, TOutput = unknown> {
+    /** Unique identifier for this tool call */
+    toolCallId: string;
+    /** Name of the tool being called */
+    toolName: string;
+    /** Current state of the tool call execution */
+    state: ToolCallState;
+    /** Input arguments passed to the tool (may be partial during streaming) */
+    input: TInput | undefined;
+    /** Output from the tool (only available when state is 'output-available') */
+    output: TOutput | undefined;
+    /** Error message (only available when state is 'output-error') */
+    errorText?: string;
+    /** Whether the tool call is currently in progress */
+    isLoading: boolean;
+}
+/**
+ * A component that renders a custom UI for a specific tool call.
+ * Return `null` to fall back to the default tool call accordion.
+ */
+type ToolCallRenderer<TInput = unknown, TOutput = unknown> = ComponentType<ToolCallProps<TInput, TOutput>>;
+/**
+ * Allowed file type categories for uploads
+ */
+type AllowedFileType = "image" | "text" | "pdf" | "markdown" | "csv" | "json";
+/**
+ * Default allowed file types (images only for best AI model compatibility)
+ * Consumers can expand this by passing allowedFileTypes in overrides
+ */
+declare const DEFAULT_ALLOWED_FILE_TYPES: AllowedFileType[];
+/**
+ * Context passed to lifecycle hooks
+ */
+interface RouteContext {
+    /** Current route path */
+    path: string;
+    /** Route parameters (e.g., { id: "abc123" }) */
+    params?: Record<string, string>;
+    /** Whether rendering on server (true) or client (false) */
+    isSSR: boolean;
+    /** Additional context properties */
+    [key: string]: any;
+}
+/**
+ * Overridable components and functions for the AI Chat plugin
+ *
+ * External consumers can provide their own implementations of these
+ * to customize the behavior for their framework (Next.js, React Router, etc.)
+ */
+interface AiChatPluginOverrides {
+    /**
+     * Plugin mode - should match backend config
+     * @default 'authenticated'
+     */
+    mode?: AiChatMode;
+    /**
+     * API base URL
+     */
+    apiBaseURL: string;
+    /**
+     * API base path
+     */
+    apiBasePath: string;
+    /**
+     * Navigation function for programmatic navigation
+     */
+    navigate: (path: string) => void | Promise<void>;
+    /**
+     * Refresh function to invalidate server-side cache (e.g., Next.js router.refresh())
+     */
+    refresh?: () => void | Promise<void>;
+    /**
+     * Link component for navigation
+     */
+    Link?: ComponentType<React.ComponentProps<"a"> & Record<string, any>>;
+    /**
+     * Image component for displaying images
+     */
+    Image?: ComponentType<React.ImgHTMLAttributes<HTMLImageElement> & Record<string, any>>;
+    /**
+     * Function used to upload a file and return its URL.
+     * Called for images, PDFs, text files, and other supported file types.
+     */
+    uploadFile?: (file: File) => Promise<string>;
+    /**
+     * Allowed file types for upload.
+     * By default, all types are enabled: image, text, pdf, markdown, csv, json
+     * Set to empty array to disable file uploads entirely.
+     * @default ['image', 'text', 'pdf', 'markdown', 'csv', 'json']
+     */
+    allowedFileTypes?: AllowedFileType[];
+    /**
+     * Localization object for the AI Chat plugin
+     */
+    localization?: Partial<AiChatLocalization>;
+    /**
+     * Optional headers to pass with API requests (e.g., for SSR auth)
+     */
+    headers?: HeadersInit;
+    /**
+     * Whether to show the attribution
+     * @default true
+     */
+    showAttribution?: boolean;
+    /**
+     * Suggested prompts to display in the empty chat state.
+     * When provided, these appear as clickable buttons that populate the input field.
+     *
+     * @example
+     * ```tsx
+     * chatSuggestions: [
+     *   "What can you help me with?",
+     *   "Tell me about your features",
+     *   "How do I get started?",
+     * ]
+     * ```
+     */
+    chatSuggestions?: string[];
+    /**
+     * Custom renderers for tool calls. Keys should match tool names.
+     * Each renderer receives ToolCallProps and can return custom UI.
+     *
+     * @example
+     * ```tsx
+     * toolRenderers: {
+     *   getWeather: ({ toolName, input, output, state, isLoading }) => (
+     *     <WeatherCard location={input?.location} weather={output} loading={isLoading} />
+     *   ),
+     *   searchDocs: ({ input, output, isLoading }) => (
+     *     <SearchResults query={input?.query} results={output} loading={isLoading} />
+     *   ),
+     * }
+     * ```
+     */
+    toolRenderers?: Record<string, ToolCallRenderer>;
+    /**
+     * Called when a route is rendered
+     * @param routeName - Name of the route (e.g., 'chat', 'chatConversation')
+     * @param context - Route context with path, params, etc.
+     */
+    onRouteRender?: (routeName: string, context: RouteContext) => void | Promise<void>;
+    /**
+     * Called when a route encounters an error
+     * @param routeName - Name of the route
+     * @param error - The error that occurred
+     * @param context - Route context
+     */
+    onRouteError?: (routeName: string, error: Error, context: RouteContext) => void | Promise<void>;
+    /**
+     * Called before the chat page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param context - Route context
+     */
+    onBeforeChatPageRendered?: (context: RouteContext) => boolean;
+    /**
+     * Called before a conversation page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param id - The conversation ID
+     * @param context - Route context
+     */
+    onBeforeConversationPageRendered?: (id: string, context: RouteContext) => boolean;
+}
+
+interface ChatInterfaceProps {
+    apiPath?: string;
+    initialMessages?: UIMessage[];
+    id?: string;
+    /** Variant: 'full' for full-page layout, 'widget' for embedded widget */
+    variant?: "full" | "widget";
+    className?: string;
+    /** Called whenever messages change (for persistence). Only fires in public mode. */
+    onMessagesChange?: (messages: UIMessage[]) => void;
+}
+declare function ChatInterface({ apiPath, initialMessages, id, variant, className, onMessagesChange, }: ChatInterfaceProps): react_jsx_runtime.JSX.Element;
+
+interface ChatLayoutProps {
+    /** API base URL */
+    apiBaseURL: string;
+    /** API base path */
+    apiBasePath: string;
+    /** Current conversation ID (if viewing existing conversation) */
+    conversationId?: string;
+    /** Layout mode: 'full' for full page with sidebar, 'widget' for embeddable widget */
+    layout?: "full" | "widget";
+    /** Additional class name for the container */
+    className?: string;
+    /** Whether to show the sidebar (default: true for full layout) */
+    showSidebar?: boolean;
+    /** Height of the widget (only applies to widget layout) */
+    widgetHeight?: string | number;
+    /** Initial messages to populate the chat (useful for localStorage persistence in public mode) */
+    initialMessages?: UIMessage[];
+    /** Called whenever messages change (for persistence). Only fires in public mode. */
+    onMessagesChange?: (messages: UIMessage[]) => void;
+}
+/**
+ * ChatLayout component that provides a full-page chat experience with sidebar
+ * or a compact widget mode for embedding.
+ */
+declare function ChatLayout({ apiBaseURL, apiBasePath, conversationId, layout, className, showSidebar, widgetHeight, initialMessages, onMessagesChange, }: ChatLayoutProps): react_jsx_runtime.JSX.Element;
+
+interface ChatSidebarProps {
+    currentConversationId?: string;
+    onNewChat?: () => void;
+    className?: string;
+}
+declare function ChatSidebar({ currentConversationId, onNewChat, className, }: ChatSidebarProps): react_jsx_runtime.JSX.Element;
+
+interface ChatMessageProps {
+    message: UIMessage;
+    isStreaming?: boolean;
+    variant?: "default" | "compact";
+    /** Callback when user wants to retry/regenerate an AI response */
+    onRetry?: () => void;
+    /** Callback when user edits their message - receives the new text */
+    onEdit?: (newText: string) => void;
+    /** Whether retry is currently in progress */
+    isRetrying?: boolean;
+}
+declare function ChatMessage({ message, isStreaming, variant, onRetry, onEdit, isRetrying, }: ChatMessageProps): react_jsx_runtime.JSX.Element;
+
+/** Represents an attached file with metadata */
+interface AttachedFile {
+    /** Data URL or uploaded URL */
+    url: string;
+    /** MIME type of the file */
+    mediaType: string;
+    /** Original filename */
+    filename: string;
+}
+interface ChatInputProps {
+    input?: string;
+    handleInputChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
+    handleSubmit: (e: FormEvent<HTMLFormElement>, files?: AttachedFile[]) => void;
+    isLoading: boolean;
+    placeholder?: string;
+    variant?: "default" | "compact";
+    /** Callback when files are attached (for controlled mode) */
+    onFilesAttached?: (files: AttachedFile[]) => void;
+    /** Attached files (for controlled mode) */
+    attachedFiles?: AttachedFile[];
+}
+declare function ChatInput({ input, handleInputChange, handleSubmit, isLoading, placeholder, variant, onFilesAttached, attachedFiles: controlledFiles, }: ChatInputProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Default tool call display component.
+ * Shows an accordion with tool name, status, inputs, and outputs.
+ */
+declare function ToolCallDisplay({ toolCallId, toolName, state, input, output, errorText, isLoading, }: ToolCallProps): react_jsx_runtime.JSX.Element;
+
+export { ChatInterface as C, DEFAULT_ALLOWED_FILE_TYPES as D, ChatLayout as e, ChatSidebar as g, ChatMessage as h, ChatInput as i, ToolCallDisplay as j };
+export type { AiChatMode as A, ToolCallProps as T, AiChatPluginOverrides as a, AllowedFileType as b, ToolCallState as c, ToolCallRenderer as d, ChatLayoutProps as f };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",

package/src/plugins/ai-chat/client/components/chat-interface.tsx

@@ -28,6 +28,8 @@ interface ChatInterfaceProps {
 	/** Variant: 'full' for full-page layout, 'widget' for embedded widget */
 	variant?: "full" | "widget";
 	className?: string;
+	/** Called whenever messages change (for persistence). Only fires in public mode. */
+	onMessagesChange?: (messages: UIMessage[]) => void;
 }
 
 export function ChatInterface({
@@ -36,6 +38,7 @@ export function ChatInterface({
 	id,
 	variant = "full",
 	className,
+	onMessagesChange,
 }: ChatInterfaceProps) {
 	const {
 		navigate,
@@ -45,6 +48,7 @@ export function ChatInterface({
 		headers,
 		mode,
 		showAttribution,
+		chatSuggestions,
 	} = usePluginOverrides<AiChatPluginOverrides, Partial<AiChatPluginOverrides>>(
 		"ai-chat",
 		{ showAttribution: true },
@@ -108,6 +112,15 @@ export function ChatInterface({
 	// Ref to track edit operation with messages to use
 	const editMessagesRef = useRef<UIMessage[] | null>(null);
 
+	// Track if we've finished initializing messages
+	// This prevents onMessagesChange from firing with an empty array before initialMessages are loaded
+	// Without this guard, the effect would fire on mount with [], overwriting any saved messages
+	const [isMessagesInitialized, setIsMessagesInitialized] = useState(
+		() =>
+			// Start as initialized if there are no initialMessages to load
+			!initialMessages || initialMessages.length === 0,
+	);
+
 	// Memoize the transport to prevent recreation on every render
 	const transport = useMemo(
 		() =>
@@ -240,6 +253,8 @@ export function ChatInterface({
 			messages.length === 0
 		) {
 			setMessages(initialMessages);
+			// Mark as initialized - this is batched with setMessages so both take effect in the same render
+			setIsMessagesInitialized(true);
 		}
 	}, [initialMessages, setMessages, messages.length]);
 
@@ -259,6 +274,14 @@ export function ChatInterface({
 		}
 	}, [messages]);
 
+	// Notify parent when messages change (for persistence in public mode)
+	// Only fire after initialization to prevent overwriting saved messages with an empty array
+	useEffect(() => {
+		if (isPublicMode && onMessagesChange && isMessagesInitialized) {
+			onMessagesChange(messages);
+		}
+	}, [messages, isPublicMode, onMessagesChange, isMessagesInitialized]);
+
 	const handleInputChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
 		setInput(e.target.value);
 	};
@@ -382,8 +405,24 @@ export function ChatInterface({
 							)}
 						>
 							{messages.length === 0 ? (
-								<div className="flex flex-col items-center justify-center h-full min-h-[300px] text-muted-foreground">
-									<p>{localization.CHAT_EMPTY_STATE}</p>
+								<div className="flex flex-col h-full min-h-[300px]">
+									<div className="flex-1 flex items-center justify-center text-muted-foreground">
+										<p>{localization.CHAT_EMPTY_STATE}</p>
+									</div>
+									{chatSuggestions && chatSuggestions.length > 0 && (
+										<div className="flex flex-wrap justify-center gap-2 pb-4 max-w-md mx-auto">
+											{chatSuggestions.map((suggestion, index) => (
+												<button
+													key={index}
+													type="button"
+													onClick={() => setInput(suggestion)}
+													className="px-3 py-2 text-sm rounded-lg border border-border bg-background hover:bg-accent hover:text-accent-foreground transition-colors text-foreground"
+												>
+													{suggestion}
+												</button>
+											))}
+										</div>
+									)}
 								</div>
 							) : (
 								messages.map((m, index) => (

package/src/plugins/ai-chat/client/components/chat-layout.tsx

@@ -11,6 +11,7 @@ import { Menu, PanelLeftClose, PanelLeft } from "lucide-react";
 import { cn } from "@workspace/ui/lib/utils";
 import { ChatSidebar } from "./chat-sidebar";
 import { ChatInterface } from "./chat-interface";
+import type { UIMessage } from "ai";
 
 export interface ChatLayoutProps {
 	/** API base URL */
@@ -27,6 +28,10 @@ export interface ChatLayoutProps {
 	showSidebar?: boolean;
 	/** Height of the widget (only applies to widget layout) */
 	widgetHeight?: string | number;
+	/** Initial messages to populate the chat (useful for localStorage persistence in public mode) */
+	initialMessages?: UIMessage[];
+	/** Called whenever messages change (for persistence). Only fires in public mode. */
+	onMessagesChange?: (messages: UIMessage[]) => void;
 }
 
 /**
@@ -41,6 +46,8 @@ export function ChatLayout({
 	className,
 	showSidebar = true,
 	widgetHeight = "600px",
+	initialMessages,
+	onMessagesChange,
 }: ChatLayoutProps) {
 	const [sidebarOpen, setSidebarOpen] = useState(true);
 	const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
@@ -67,7 +74,13 @@ export function ChatLayout({
 				)}
 				style={{ height: widgetHeight }}
 			>
-				<ChatInterface apiPath={apiPath} id={conversationId} variant="widget" />
+				<ChatInterface
+					apiPath={apiPath}
+					id={conversationId}
+					variant="widget"
+					initialMessages={initialMessages}
+					onMessagesChange={onMessagesChange}
+				/>
 			</div>
 		);
 	}
@@ -153,6 +166,8 @@ export function ChatLayout({
 					apiPath={apiPath}
 					id={conversationId}
 					variant="full"
+					initialMessages={initialMessages}
+					onMessagesChange={onMessagesChange}
 				/>
 			</div>
 		</div>

package/src/plugins/ai-chat/client/components/chat-message.tsx

@@ -20,6 +20,7 @@ import {
 	X,
 } from "lucide-react";
 import type { UIMessage } from "ai";
+import { isToolUIPart, getToolName } from "ai";
 import {
 	useMemo,
 	useState,
@@ -28,8 +29,13 @@ import {
 	type ComponentType,
 } from "react";
 import { usePluginOverrides } from "@btst/stack/context";
-import type { AiChatPluginOverrides } from "../overrides";
+import type {
+	AiChatPluginOverrides,
+	ToolCallProps,
+	ToolCallState,
+} from "../overrides";
 import { AI_CHAT_LOCALIZATION } from "../localization";
+import { ToolCallDisplay } from "./tool-call-display";
 
 // Import shared markdown + syntax highlighting styles (same pattern as blog plugin)
 import "@workspace/ui/markdown-content.css";
@@ -131,6 +137,7 @@ export function ChatMessage({
 		Link,
 		Image,
 		localization: customLocalization,
+		toolRenderers,
 	} = usePluginOverrides<AiChatPluginOverrides, Partial<AiChatPluginOverrides>>(
 		"ai-chat",
 		{},
@@ -233,6 +240,14 @@ export function ChatMessage({
 		return [];
 	}, [message.parts]);
 
+	// Extract tool call parts from message (AI SDK v5 format: type is "tool-{toolName}")
+	const toolParts = useMemo(() => {
+		if (message.parts && Array.isArray(message.parts)) {
+			return message.parts.filter((part: any) => isToolUIPart(part));
+		}
+		return [];
+	}, [message.parts]);
+
 	// Use remend to complete partial markdown when streaming
 	const displayContent = useMemo(() => {
 		if (!textContent) return "";
@@ -370,7 +385,7 @@ export function ChatMessage({
 							)}
 						</div>
 					) : (
-						// Assistant messages: rendered markdown + files + images
+						// Assistant messages: rendered markdown + files + images + tool calls
 						<div className="wrap-break-word space-y-2">
 							{/* Any attached files (non-images) */}
 							{fileParts.length > 0 && (
@@ -407,6 +422,45 @@ export function ChatMessage({
 									))}
 								</div>
 							)}
+							{/* Tool calls */}
+							{toolParts.length > 0 && (
+								<div className="space-y-2">
+									{toolParts.map((part: any) => {
+										const toolName = getToolName(part);
+										const toolCallId = part.toolCallId;
+										const state = part.state as ToolCallState;
+										const input = part.input;
+										const output = part.output;
+										const errorText = part.errorText;
+										const isLoading =
+											state === "input-streaming" ||
+											state === "input-available";
+
+										const toolCallProps: ToolCallProps = {
+											toolCallId,
+											toolName,
+											state,
+											input,
+											output,
+											errorText,
+											isLoading,
+										};
+
+										// Check if there's a custom renderer for this tool
+										const CustomRenderer = toolRenderers?.[toolName];
+										if (CustomRenderer) {
+											return (
+												<CustomRenderer key={toolCallId} {...toolCallProps} />
+											);
+										}
+
+										// Use default tool call display
+										return (
+											<ToolCallDisplay key={toolCallId} {...toolCallProps} />
+										);
+									})}
+								</div>
+							)}
 							{/* Text content */}
 							{displayContent ? (
 								<MarkdownContent
@@ -415,7 +469,9 @@ export function ChatMessage({
 									LinkComponent={Link ?? DefaultLink}
 									ImageComponent={ImageComponent}
 								/>
-							) : imageParts.length === 0 && fileParts.length === 0 ? (
+							) : imageParts.length === 0 &&
+								fileParts.length === 0 &&
+								toolParts.length === 0 ? (
 								<span className="text-muted-foreground">...</span>
 							) : null}
 						</div>

package/src/plugins/ai-chat/client/components/index.ts

@@ -1,8 +1,10 @@
 export { ChatInterface } from "./chat-interface";
 export { ChatLayout } from "./chat-layout";
+export type { ChatLayoutProps } from "./chat-layout";
 export { ChatSidebar } from "./chat-sidebar";
 export { ChatMessage } from "./chat-message";
 export { ChatInput } from "./chat-input";
+export { ToolCallDisplay } from "./tool-call-display";
 
 // Page components
 export { ChatPageComponent } from "./pages/chat-page";