@promptbook/components 0.101.0-16 → 0.101.0-18

package/esm/index.es.js

@@ -21,7 +21,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.101.0-16';
+const PROMPTBOOK_ENGINE_VERSION = '0.101.0-18';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -4130,6 +4130,147 @@ const SendIcon = ({ size }) => (jsx("svg", { width: size, height: size, viewBox:
  */
 const TemplateIcon = ({ size }) => (jsx("svg", { width: size, height: size, viewBox: "0 0 24 24", fill: "currentColor", children: jsx("path", { d: "M14,2H6A2,2 0 0,0 4,4V20A2,2 0 0,0 6,22H18A2,2 0 0,0 20,20V8L14,2M18,20H6V4H13V9H18V20Z" }) }));
 
+/**
+ * Hook for managing auto-scroll behavior in chat components
+ *
+ * This hook provides:
+ * - Automatic scrolling to bottom when new messages arrive (if user is already at bottom)
+ * - Detection of when user scrolls away from bottom
+ * - Scroll-to-bottom functionality with smooth animation
+ * - Mobile-optimized scrolling behavior
+ *
+ * @public exported from `@promptbook/components`
+ */
+function useChatAutoScroll(config = {}) {
+    const { bottomThreshold = 100, smoothScroll = true, scrollCheckDelay = 100, } = config;
+    const [isAutoScrolling, setIsAutoScrolling] = useState(true);
+    const [isMobile, setIsMobile] = useState(false);
+    const chatMessagesRef = useRef(null);
+    const scrollTimeoutRef = useRef(null);
+    const lastScrollHeightRef = useRef(0);
+    // Detect mobile device
+    useEffect(() => {
+        const checkMobile = () => {
+            const isMobileDevice = window.innerWidth <= 768 ||
+                /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
+            setIsMobile(isMobileDevice);
+        };
+        checkMobile();
+        window.addEventListener('resize', checkMobile);
+        return () => window.removeEventListener('resize', checkMobile);
+    }, []);
+    // Check if user is at the bottom of the chat
+    const checkIfAtBottom = useCallback((element) => {
+        const { scrollTop, scrollHeight, clientHeight } = element;
+        return scrollTop + clientHeight >= scrollHeight - bottomThreshold;
+    }, [bottomThreshold]);
+    // Scroll to bottom function
+    const scrollToBottom = useCallback((behavior = 'smooth') => {
+        const chatMessagesElement = chatMessagesRef.current;
+        if (!chatMessagesElement)
+            return;
+        if (isMobile) {
+            // Mobile-optimized scrolling
+            chatMessagesElement.scrollTo({
+                top: chatMessagesElement.scrollHeight,
+                behavior: smoothScroll ? behavior : 'auto',
+            });
+        }
+        else {
+            // Desktop scrolling
+            if (smoothScroll && behavior === 'smooth') {
+                chatMessagesElement.style.scrollBehavior = 'smooth';
+                chatMessagesElement.scrollTop = chatMessagesElement.scrollHeight;
+                chatMessagesElement.style.scrollBehavior = 'auto';
+            }
+            else {
+                chatMessagesElement.scrollTop = chatMessagesElement.scrollHeight;
+            }
+        }
+    }, [isMobile, smoothScroll]);
+    // Handle scroll events
+    const handleScroll = useCallback((event) => {
+        const element = event.target;
+        if (!element)
+            return;
+        // Clear any pending scroll timeout
+        if (scrollTimeoutRef.current) {
+            clearTimeout(scrollTimeoutRef.current);
+        }
+        // Debounce scroll position check to avoid too frequent updates
+        scrollTimeoutRef.current = setTimeout(() => {
+            const isAtBottom = checkIfAtBottom(element);
+            setIsAutoScrolling(isAtBottom);
+        }, 50);
+    }, [checkIfAtBottom]);
+    // Auto-scroll when messages change (if user is at bottom)
+    const handleMessagesChange = useCallback(() => {
+        const chatMessagesElement = chatMessagesRef.current;
+        if (!chatMessagesElement)
+            return;
+        // Check if this is a new message (scroll height increased)
+        const currentScrollHeight = chatMessagesElement.scrollHeight;
+        const hasNewContent = currentScrollHeight > lastScrollHeightRef.current;
+        lastScrollHeightRef.current = currentScrollHeight;
+        if (!hasNewContent)
+            return;
+        // If user is set to auto-scroll, scroll to bottom
+        if (isAutoScrolling) {
+            // Delay scroll slightly to ensure DOM has updated
+            setTimeout(() => {
+                scrollToBottom('smooth');
+            }, scrollCheckDelay);
+        }
+    }, [isAutoScrolling, scrollToBottom, scrollCheckDelay]);
+    // Ref callback for chat messages container
+    const chatMessagesRefCallback = useCallback((element) => {
+        chatMessagesRef.current = element;
+        if (element) {
+            // Update last scroll height
+            lastScrollHeightRef.current = element.scrollHeight;
+            // If auto-scrolling is enabled, scroll to bottom
+            if (isAutoScrolling) {
+                // Use requestAnimationFrame for smoother initial scroll
+                requestAnimationFrame(() => {
+                    scrollToBottom('auto');
+                });
+            }
+        }
+    }, [isAutoScrolling, scrollToBottom]);
+    // Manual scroll to bottom (for button click)
+    const handleScrollToBottomClick = useCallback(() => {
+        setIsAutoScrolling(true);
+        scrollToBottom('smooth');
+    }, [scrollToBottom]);
+    // Force auto-scroll back on (useful for programmatic control)
+    const enableAutoScroll = useCallback(() => {
+        setIsAutoScrolling(true);
+        scrollToBottom('smooth');
+    }, [scrollToBottom]);
+    // Disable auto-scroll (useful for programmatic control)
+    const disableAutoScroll = useCallback(() => {
+        setIsAutoScrolling(false);
+    }, []);
+    // Cleanup timeout on unmount
+    useEffect(() => {
+        return () => {
+            if (scrollTimeoutRef.current) {
+                clearTimeout(scrollTimeoutRef.current);
+            }
+        };
+    }, []);
+    return {
+        isAutoScrolling,
+        chatMessagesRef: chatMessagesRefCallback,
+        handleScroll,
+        handleMessagesChange,
+        scrollToBottom: handleScrollToBottomClick,
+        enableAutoScroll,
+        disableAutoScroll,
+        isMobile,
+    };
+}
+
 /**
  * Parses markdown buttons in the format [Button Text](?message=Message%20to%20send)
  * Returns both the content without buttons and the extracted buttons
@@ -4318,9 +4459,9 @@ function Chat(props) {
     // exportHeaderMarkdown,
     participants = [], } = props;
     const { onUseTemplate } = props;
-    const [isAutoScrolling, setAutoScrolling] = useState(true);
+    // Use the auto-scroll hook
+    const { isAutoScrolling, chatMessagesRef, handleScroll, handleMessagesChange, scrollToBottom, isMobile: isMobileFromHook, } = useChatAutoScroll();
     const textareaRef = useRef(null);
-    const chatMessagesRef = useRef(null);
     const buttonSendRef = useRef(null);
     const [ratingModalOpen, setRatingModalOpen] = useState(false);
     const [selectedMessage, setSelectedMessage] = useState(null);
@@ -4333,18 +4474,8 @@ function Chat(props) {
     // const [inputValue, setInputValue] = useState('');
     const [mode] = useState('LIGHT'); // Simplified light/dark mode
     const [ratingConfirmation, setRatingConfirmation] = useState(null);
-    const [isMobile, setIsMobile] = useState(false);
-    // Detect mobile device
-    useEffect(() => {
-        const checkMobile = () => {
-            const isMobileDevice = window.innerWidth <= 768 ||
-                /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
-            setIsMobile(isMobileDevice);
-        };
-        checkMobile();
-        window.addEventListener('resize', checkMobile);
-        return () => window.removeEventListener('resize', checkMobile);
-    }, []);
+    // Use mobile detection from the hook
+    const isMobile = isMobileFromHook;
     useEffect(( /* Focus textarea on page load */) => {
         if (!textareaRef.current) {
             return;
@@ -4470,59 +4601,16 @@ function Chat(props) {
             return { ...message, content: humanizeAiText(message.content) };
         });
     }, [messages, isAiTextHumanized]);
-    return (jsxs(Fragment, { children: [ratingConfirmation && jsx("div", { className: styles$1.ratingConfirmation, children: ratingConfirmation }), jsx("div", { className: classNames(className, styles$1.Chat, useChatCssClassName('Chat')), style, children: jsxs("div", { className: classNames(className, styles$1.chatMainFlow, useChatCssClassName('chatMainFlow')), children: [children && jsx("div", { className: classNames(styles$1.chatBar, chatBarCssClassName), children: children }), !isAutoScrolling && (jsx("div", { className: styles$1.scrollToBottomContainer, children: jsx("button", { "data-button-type": "custom", className: classNames(styles$1.scrollToBottom, scrollToBottomCssClassName), onClick: () => {
-                                    const chatMessagesElement = chatMessagesRef.current;
-                                    if (chatMessagesElement === null) {
-                                        return;
-                                    }
-                                    // Mobile-optimized scroll to bottom
-                                    if (isMobile) {
-                                        chatMessagesElement.scrollTo({
-                                            top: chatMessagesElement.scrollHeight,
-                                            behavior: 'smooth',
-                                        });
-                                    }
-                                    else {
-                                        chatMessagesElement.style.scrollBehavior = 'smooth';
-                                        chatMessagesElement.scrollBy(0, 10000);
-                                        chatMessagesElement.style.scrollBehavior = 'auto';
-                                    }
-                                }, children: jsx(ArrowIcon, { direction: "DOWN", size: 33 }) }) })), isVoiceCalling && (jsx("div", { className: styles$1.voiceCallIndicatorBar, children: jsxs("div", { className: styles$1.voiceCallIndicator, children: [jsx("svg", { width: "16", height: "16", viewBox: "0 0 24 24", fill: "currentColor", children: jsx("path", { d: "M6.62 10.79c1.44 2.83 3.76 5.14 6.59 6.59l2.2-2.2c.27-.27.67-.36 1.02-.24 1.12.37 2.33.57 3.57.57.55 0 1 .45 1 1V20c0 .55-.45 1-1 1-9.39 0-17-7.61-17-17 0-.55.45-1 1-1h3.5c.55 0 1 .45 1 1 0 1.25.2 2.45.57 3.57.11.35.03.74-.25 1.02l-2.2 2.2z" }) }), jsx("span", { children: "Voice call active" }), jsx("div", { className: styles$1.voiceCallPulse })] }) })), jsxs("div", { className: classNames(actionsAlignmentClass), children: [onReset && postprocessedMessages.length !== 0 && (jsxs("button", { className: classNames(styles$1.resetButton), onClick: () => {
+    // Trigger auto-scroll when messages change
+    useEffect(() => {
+        handleMessagesChange();
+    }, [postprocessedMessages, handleMessagesChange]);
+    return (jsxs(Fragment, { children: [ratingConfirmation && jsx("div", { className: styles$1.ratingConfirmation, children: ratingConfirmation }), jsx("div", { className: classNames(className, styles$1.Chat, useChatCssClassName('Chat')), style, children: jsxs("div", { className: classNames(className, styles$1.chatMainFlow, useChatCssClassName('chatMainFlow')), children: [children && jsx("div", { className: classNames(styles$1.chatBar, chatBarCssClassName), children: children }), !isAutoScrolling && (jsx("div", { className: styles$1.scrollToBottomContainer, children: jsx("button", { "data-button-type": "custom", className: classNames(styles$1.scrollToBottom, scrollToBottomCssClassName), onClick: scrollToBottom, children: jsx(ArrowIcon, { direction: "DOWN", size: 33 }) }) })), isVoiceCalling && (jsx("div", { className: styles$1.voiceCallIndicatorBar, children: jsxs("div", { className: styles$1.voiceCallIndicator, children: [jsx("svg", { width: "16", height: "16", viewBox: "0 0 24 24", fill: "currentColor", children: jsx("path", { d: "M6.62 10.79c1.44 2.83 3.76 5.14 6.59 6.59l2.2-2.2c.27-.27.67-.36 1.02-.24 1.12.37 2.33.57 3.57.57.55 0 1 .45 1 1V20c0 .55-.45 1-1 1-9.39 0-17-7.61-17-17 0-.55.45-1 1-1h3.5c.55 0 1 .45 1 1 0 1.25.2 2.45.57 3.57.11.35.03.74-.25 1.02l-2.2 2.2z" }) }), jsx("span", { children: "Voice call active" }), jsx("div", { className: styles$1.voiceCallPulse })] }) })), jsxs("div", { className: classNames(actionsAlignmentClass), children: [onReset && postprocessedMessages.length !== 0 && (jsxs("button", { className: classNames(styles$1.resetButton), onClick: () => {
                                         if (!confirm(`Do you really want to reset the chat?`)) {
                                             return;
                                         }
                                         onReset();
-                                    }, children: [jsx(ResetIcon, {}), jsx("span", { className: styles$1.resetButtonText, children: "New chat" })] })), onUseTemplate && (jsxs("button", { className: classNames(styles$1.useTemplateButton), onClick: onUseTemplate, children: [jsx("span", { className: styles$1.resetButtonText, children: "Use this template" }), jsx(TemplateIcon, { size: 16 })] }))] }), jsx("div", { className: classNames(styles$1.chatMessages, useChatCssClassName('chatMessages')), ref: (chatMessagesElement) => {
-                                chatMessagesRef.current = chatMessagesElement;
-                                if (chatMessagesElement === null) {
-                                    return;
-                                }
-                                if (!isAutoScrolling) {
-                                    return;
-                                }
-                                // Mobile-optimized scrolling
-                                if (isMobile) {
-                                    // Delay scroll slightly on mobile for better performance
-                                    requestAnimationFrame(() => {
-                                        chatMessagesElement.scrollTo({
-                                            top: chatMessagesElement.scrollHeight,
-                                            behavior: 'smooth',
-                                        });
-                                    });
-                                }
-                                else {
-                                    // Desktop smooth scrolling
-                                    chatMessagesElement.style.scrollBehavior = 'smooth';
-                                    chatMessagesElement.scrollBy(0, 1000);
-                                    chatMessagesElement.style.scrollBehavior = 'auto';
-                                }
-                            }, onScroll: (event) => {
-                                const element = event.target;
-                                if (!(element instanceof HTMLDivElement)) {
-                                    return;
-                                }
-                                setAutoScrolling(element.scrollTop + element.clientHeight > element.scrollHeight - 100);
-                            }, children: postprocessedMessages.map((message, i) => {
+                                    }, children: [jsx(ResetIcon, {}), jsx("span", { className: styles$1.resetButtonText, children: "New chat" })] })), onUseTemplate && (jsxs("button", { className: classNames(styles$1.useTemplateButton), onClick: onUseTemplate, children: [jsx("span", { className: styles$1.resetButtonText, children: "Use this template" }), jsx(TemplateIcon, { size: 16 })] }))] }), jsx("div", { className: classNames(styles$1.chatMessages, useChatCssClassName('chatMessages')), ref: chatMessagesRef, onScroll: handleScroll, children: postprocessedMessages.map((message, i) => {
                                 const participant = participants.find((participant) => participant.name === message.from);
                                 const avatarSrc = (participant && participant.avatarSrc) || '';
                                 const color = Color.from((participant && participant.color) || '#ccc');
@@ -5396,6 +5484,53 @@ function BookEditor(props) {
     return (jsx("div", { "data-book-component": "BookEditor", ref: hostRef, className: classNames(styles.BookEditor, isVerbose && styles.isVerbose, className), style: style, children: shadowReady && shadowRootRef.current ? createPortal(editorInner, shadowRootRef.current) : jsx(Fragment, { children: "Loading..." }) }));
 }
 
+/**
+ * Hook to create a sendMessage function for an <LlmChat/> component WITHOUT needing any React Context.
+ *
+ * Usage pattern:
+ * ```tsx
+ * const sendMessage = useSendMessageToLlmChat();
+ * return (
+ *   <>
+ *     <button onClick={() => sendMessage('Hello!')}>Hello</button>
+ *     <LlmChat llmTools={llmTools} sendMessage={sendMessage} />
+ *   </>
+ * );
+ * ```
+ *
+ * - No provider wrapping needed.
+ * - Safe to call before the <LlmChat/> mounts (messages will be queued).
+ * - Keeps DRY by letting <LlmChat/> reuse its internal `handleMessage` logic.
+ *
+ * @public exported from `@promptbook/components`
+ */
+function useSendMessageToLlmChat() {
+    const ref = useRef(null);
+    if (!ref.current) {
+        let handler = null;
+        const queue = [];
+        const sendMessage = (message) => {
+            if (handler) {
+                // Fire and forget
+                void handler(message);
+            }
+            else {
+                queue.push(message);
+            }
+        };
+        sendMessage._attach = (attachedHandler) => {
+            handler = attachedHandler;
+            // Flush queued messages
+            while (queue.length > 0) {
+                const next = queue.shift();
+                void handler(next);
+            }
+        };
+        ref.current = sendMessage;
+    }
+    return ref.current;
+}
+
 /**
  * Utility functions for persisting chat conversations in localStorage
  *
@@ -5482,16 +5617,22 @@ ChatPersistence.STORAGE_PREFIX = 'promptbook_chat_';
  * @public exported from `@promptbook/components`
  */
 function LlmChat(props) {
-    const { llmTools, persistenceKey, onChange, onReset, ...restProps } = props;
+    const { llmTools, persistenceKey, onChange, onReset, initialMessages, sendMessage, ...restProps } = props;
     // Internal state management
-    const [messages, setMessages] = useState([]);
+    const [messages, setMessages] = useState(() => (initialMessages ? [...initialMessages] : []));
     const [tasksProgress, setTasksProgress] = useState([]);
+    /**
+     * Tracks whether the user (or system via persistence restoration) has interacted.
+     * We do NOT persist purely initialMessages until the user sends something.
+     */
+    const hasUserInteractedRef = useRef(false);
     // Load persisted messages on component mount
     useEffect(() => {
         if (persistenceKey && ChatPersistence.isAvailable()) {
             const persistedMessages = ChatPersistence.loadMessages(persistenceKey);
             if (persistedMessages.length > 0) {
                 setMessages(persistedMessages);
+                hasUserInteractedRef.current = true; // Persisted conversation exists; allow saving next changes
                 // Notify about loaded messages
                 if (onChange) {
                     onChange(persistedMessages, participants);
@@ -5501,7 +5642,10 @@ function LlmChat(props) {
     }, [persistenceKey]); // Only depend on persistenceKey, not participants or onChange to avoid infinite loops
     // Save messages to localStorage whenever messages change (and persistence is enabled)
     useEffect(() => {
-        if (persistenceKey && ChatPersistence.isAvailable() && messages.length > 0) {
+        if (persistenceKey &&
+            ChatPersistence.isAvailable() &&
+            messages.length > 0 &&
+            hasUserInteractedRef.current) {
             ChatPersistence.saveMessages(persistenceKey, messages);
         }
     }, [messages, persistenceKey]);
@@ -5522,6 +5666,7 @@ function LlmChat(props) {
     ], [llmTools.profile, llmTools.title]);
     // Handle user messages and LLM responses
     const handleMessage = useCallback(async (messageContent) => {
+        hasUserInteractedRef.current = true;
         // Add user message
         const userMessage = {
             id: `user_${Date.now()}`,
@@ -5609,6 +5754,7 @@ function LlmChat(props) {
     const handleReset = useCallback(async () => {
         setMessages([]);
         setTasksProgress([]);
+        hasUserInteractedRef.current = false;
         // Clear persisted messages if persistence is enabled
         if (persistenceKey && ChatPersistence.isAvailable()) {
             ChatPersistence.clearMessages(persistenceKey);
@@ -5621,8 +5767,14 @@ function LlmChat(props) {
             onChange([], participants);
         }
     }, [persistenceKey, onReset, onChange, participants]);
+    // Attach internal handler to external sendMessage (from useSendMessageToLlmChat) if provided
+    useEffect(() => {
+        if (sendMessage && sendMessage._attach) {
+            sendMessage._attach(handleMessage);
+        }
+    }, [sendMessage, handleMessage]);
     return (jsx(Chat, { ...restProps, messages, onReset, tasksProgress, participants, onMessage: handleMessage, onReset: handleReset }));
 }
 
-export { ArrowIcon, AvatarChip, AvatarChipFromSource, AvatarProfile, AvatarProfileFromSource, BOOK_LANGUAGE_VERSION, BookEditor, Chat, DEFAULT_BOOK_FONT_CLASS, LlmChat, MockedChat, PROMPTBOOK_ENGINE_VERSION, ResetIcon, SendIcon, TemplateIcon, isMarkdownContent, parseMessageButtons, renderMarkdown };
+export { ArrowIcon, AvatarChip, AvatarChipFromSource, AvatarProfile, AvatarProfileFromSource, BOOK_LANGUAGE_VERSION, BookEditor, Chat, DEFAULT_BOOK_FONT_CLASS, LlmChat, MockedChat, PROMPTBOOK_ENGINE_VERSION, ResetIcon, SendIcon, TemplateIcon, isMarkdownContent, parseMessageButtons, renderMarkdown, useChatAutoScroll, useSendMessageToLlmChat };
 //# sourceMappingURL=index.es.js.map