@btst/stack 1.3.1 → 1.4.1

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

@@ -0,0 +1,156 @@
+/**
+ * AI Chat plugin localization strings
+ */
+export interface AiChatLocalization {
+	// Chat interface
+	CHAT_PLACEHOLDER: string;
+	CHAT_SEND_BUTTON: string;
+	CHAT_EMPTY_STATE: string;
+	CHAT_LOADING: string;
+	CHAT_ERROR: string;
+	CHAT_RETRY: string;
+
+	// Page errors
+	CHAT_GENERIC_ERROR_TITLE: string;
+	CHAT_GENERIC_ERROR_MESSAGE: string;
+	CHAT_PAGE_NOT_FOUND_TITLE: string;
+	CHAT_PAGE_NOT_FOUND_DESCRIPTION: string;
+
+	// Sidebar
+	SIDEBAR_TITLE: string;
+	SIDEBAR_NEW_CHAT: string;
+	SIDEBAR_NO_CONVERSATIONS: string;
+	SIDEBAR_SEARCH_PLACEHOLDER: string;
+
+	// Conversation actions
+	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 (legacy)
+	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
+	FILE_UPLOAD_BUTTON: string;
+	FILE_UPLOAD_ERROR_TOO_LARGE: string;
+	FILE_UPLOAD_SUCCESS: string;
+	FILE_UPLOAD_FAILURE: string;
+
+	// Timestamps
+	TIME_JUST_NOW: string;
+	TIME_MINUTES_AGO: string;
+	TIME_HOURS_AGO: string;
+	TIME_YESTERDAY: string;
+	TIME_DAYS_AGO: string;
+
+	// Message actions
+	MESSAGE_COPY: string;
+	MESSAGE_COPIED: string;
+	MESSAGE_RETRY: string;
+	MESSAGE_EDIT: string;
+	MESSAGE_SAVE: string;
+	MESSAGE_CANCEL: string;
+
+	// Accessibility
+	A11Y_USER_MESSAGE: string;
+	A11Y_ASSISTANT_MESSAGE: string;
+	A11Y_COPY_CODE: string;
+	A11Y_CODE_COPIED: string;
+}
+
+/**
+ * Default English localization strings
+ */
+export const AI_CHAT_LOCALIZATION: AiChatLocalization = {
+	// Chat interface
+	CHAT_PLACEHOLDER: "Type a message...",
+	CHAT_SEND_BUTTON: "Send",
+	CHAT_EMPTY_STATE: "Start a conversation...",
+	CHAT_LOADING: "Thinking...",
+	CHAT_ERROR: "Something went wrong. Please try again.",
+	CHAT_RETRY: "Retry",
+
+	// Page errors
+	CHAT_GENERIC_ERROR_TITLE: "Something went wrong",
+	CHAT_GENERIC_ERROR_MESSAGE:
+		"An error occurred while loading the chat. Please try again.",
+	CHAT_PAGE_NOT_FOUND_TITLE: "Chat not found",
+	CHAT_PAGE_NOT_FOUND_DESCRIPTION:
+		"The conversation you're looking for doesn't exist or has been deleted.",
+
+	// Sidebar
+	SIDEBAR_TITLE: "Conversations",
+	SIDEBAR_NEW_CHAT: "New chat",
+	SIDEBAR_NO_CONVERSATIONS: "No conversations yet",
+	SIDEBAR_SEARCH_PLACEHOLDER: "Search conversations...",
+
+	// Conversation actions
+	CONVERSATION_RENAME: "Rename",
+	CONVERSATION_RENAME_PLACEHOLDER: "Enter conversation name",
+	CONVERSATION_RENAME_SAVE: "Save",
+	CONVERSATION_RENAME_CANCEL: "Cancel",
+	CONVERSATION_DELETE: "Delete",
+	CONVERSATION_DELETE_CONFIRM_TITLE: "Delete conversation",
+	CONVERSATION_DELETE_CONFIRM_DESCRIPTION:
+		"Are you sure you want to delete this conversation? This action cannot be undone.",
+	CONVERSATION_DELETE_CONFIRM_BUTTON: "Delete",
+	CONVERSATION_DELETE_CANCEL: "Cancel",
+
+	// Image upload (legacy)
+	IMAGE_UPLOAD_BUTTON: "Attach image",
+	IMAGE_UPLOAD_UPLOADING: "Uploading...",
+	IMAGE_UPLOAD_ERROR_NOT_IMAGE: "Please select an image file",
+	IMAGE_UPLOAD_ERROR_TOO_LARGE: "Image must be less than 4MB",
+	IMAGE_UPLOAD_SUCCESS: "Image uploaded",
+	IMAGE_UPLOAD_FAILURE: "Failed to upload image",
+
+	// File upload
+	FILE_UPLOAD_BUTTON: "Attach file",
+	FILE_UPLOAD_ERROR_TOO_LARGE: "File must be less than 10MB",
+	FILE_UPLOAD_SUCCESS: "File attached",
+	FILE_UPLOAD_FAILURE: "Failed to attach file",
+
+	// Timestamps
+	TIME_JUST_NOW: "Just now",
+	TIME_MINUTES_AGO: "{count} minutes ago",
+	TIME_HOURS_AGO: "{count} hours ago",
+	TIME_YESTERDAY: "Yesterday",
+	TIME_DAYS_AGO: "{count} days ago",
+
+	// Message actions
+	MESSAGE_COPY: "Copy message",
+	MESSAGE_COPIED: "Copied!",
+	MESSAGE_RETRY: "Retry",
+	MESSAGE_EDIT: "Edit message",
+	MESSAGE_SAVE: "Save",
+	MESSAGE_CANCEL: "Cancel",
+
+	// Accessibility
+	A11Y_USER_MESSAGE: "Your message",
+	A11Y_ASSISTANT_MESSAGE: "AI response",
+	A11Y_COPY_CODE: "Copy code",
+	A11Y_CODE_COPIED: "Code copied",
+};
+
+/**
+ * Helper function to format localized strings with placeholders
+ */
+export function formatLocalized(
+	template: string,
+	values: Record<string, string | number>,
+): string {
+	return template.replace(/\{(\w+)\}/g, (match, key) => {
+		return values[key]?.toString() ?? match;
+	});
+}

package/src/plugins/ai-chat/client/overrides.ts

@@ -0,0 +1,241 @@
+import type { ComponentType } from "react";
+import type { AiChatLocalization } from "./localization";
+
+/**
+ * Plugin mode for AI Chat
+ * - 'authenticated': Conversations persisted with userId (default)
+ * - 'public': Stateless chat, no persistence (ideal for public chatbots)
+ */
+export type AiChatMode = "authenticated" | "public";
+
+/**
+ * State of a tool call execution
+ */
+export type ToolCallState =
+	| "input-streaming"
+	| "input-available"
+	| "output-available"
+	| "output-error";
+
+/**
+ * Props passed to custom tool call renderer components
+ */
+export 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.
+ */
+export type ToolCallRenderer<
+	TInput = unknown,
+	TOutput = unknown,
+> = ComponentType<ToolCallProps<TInput, TOutput>>;
+
+/**
+ * Allowed file type categories for uploads
+ */
+export 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
+ */
+export const DEFAULT_ALLOWED_FILE_TYPES: AllowedFileType[] = ["image"];
+
+/**
+ * MIME type mappings for each file type category
+ */
+export const FILE_TYPE_MIME_MAP: Record<AllowedFileType, string[]> = {
+	image: ["image/*"],
+	text: ["text/plain"],
+	markdown: ["text/markdown"],
+	csv: ["text/csv"],
+	pdf: ["application/pdf"],
+	json: ["application/json"],
+};
+
+/**
+ * Context passed to lifecycle hooks
+ */
+export 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.)
+ */
+export 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>;
+
+	// ============== Lifecycle Hooks (optional) ==============
+
+	/**
+	 * 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;
+}