feat(ask-baml): some final cleanups (#2270)

- clean up unused code / sloppy vibe code, or try to
- make state communication between search bar and chatbot less bug-prone
(go through jotai for it all)
- make state management for opening/closing the chatbot less bug-prome
(again, go through jotai and rip out a bunch of intermediate state
bridging/juggling)
- add CLAUDE.md for ask-baml-client, to provide instructions about
- scroll all the way down when opening the chatbot, instead of most of
the way down (this was probably the "scrollIntoView" logic)
- vertically align the chatbot message input and send button (customer
called out the misalignment) - there were extra divs and sloppy flexbox
management
- feedback API calls are not triggering notion/slack calls - add an
`after()` call which Vercel functions should understand
<!-- ELLIPSIS_HIDDEN -->


----

> [!IMPORTANT]
> Refactor state management and UI for chatbot and search bar, add
architecture documentation, and improve feedback logging in
`ask-baml-client`.
> 
>   - **State Management**:
> - Refactor state communication between search bar and chatbot using
`jotai` in `AlgoliaSearch.tsx` and `ChatBot.tsx`.
> - Simplify chatbot open/close state management with
`isChatbotOpenAtom` in `store.ts`.
>   - **UI Enhancements**:
> - Align chatbot message input and send button vertically in
`ChatBot.tsx`.
>     - Ensure chatbot scrolls to the bottom on open in `ChatBot.tsx`.
> - Add `CLAUDE.md` for architecture instructions in `ask-baml-client`.
>   - **Backend**:
>     - Use `after()` for asynchronous feedback logging in `route.ts`.
>   - **Miscellaneous**:
> - Remove unused code and improve code quality across multiple files.
>     - Fix minor UI issues and improve logging.
> 
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=BoundaryML%2Fbaml&utm_source=github&utm_medium=referral)<sup>
for ba82b12. You can
[customize](https://app.ellipsis.dev/BoundaryML/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>


<!-- ELLIPSIS_HIDDEN -->

Author: sxlijin

pnpm-lock.yaml

@@ -0,0 +1,8 @@
+This is a browser chat app written in TS, compiled into a JS snippet and injected on page load into docs.boundaryml.com.
+
+- ChatBot is the chat interface
+- AssistantResponseFeedback manages feedback buttons and sends feedback to the backend
+
+The backend code is in ../sage-backend, in the /api/ask-baml/ routes.
+
+The RPC interface with the backend is defined in ../../packages/sage-interface.

typescript/apps/ask-baml-client/CLAUDE.md

@@ -0,0 +1,19 @@
+See CLAUDE.md for architecture description.
+
+Remaining work items, in priority answer:
+
+[ ] stream chatbot responses to the user
+[ ] search bar css is missing dark mode support (maybe integrate tailwind styles?)
+[ ] copy chat-sdk.dev’s UI https://chat-sdk.dev/
+    [ ] want to allow edit-and-retry, for example
+        (this is partially done, see packages/ui/chatbot)
+[ ] index headings of each document, to be able to suggest links to
+    individual headings when suggesting destinations
+[ ] improve the underlying prompt
+    [ ] standalone queries like "alias" or "type builder" sometimes result in
+        "please provide a complete query" from the chatbot
+    [ ] alias → how do i use alias with dynamic types (currently returns the
+        wrong answer)
+    [ ] what do if user is asking for code debugging help?
+[ ] instant search dropdown icons are wrong (needs to get
+    propagated through sitemap/pinecone)

typescript/apps/ask-baml-client/README.md

@@ -1,13 +1,28 @@
 'use client';
 
 import { liteClient as algoliasearch } from 'algoliasearch/lite';
+import { useAtom, useAtomValue, useSetAtom } from 'jotai';
 import type React from 'react';
 import { useEffect, useRef, useState } from 'react';
 import { Configure, InstantSearch, useHits, useSearchBox } from 'react-instantsearch';
 import { z } from 'zod';
 import BamlLambWhite from './baml-lamb-white.svg';
 import { ALGOLIA_SEARCH_CREDENTIALS_ENDPOINT, ALGOLIA_SEARCH_INDEX_NAME } from './constants';
-
+import { isChatbotOpenAtom, pendingQueryAtom } from './store';
+
+const useChatbot = () => {
+  const [pendingQuery, setPendingQuery] = useAtom(pendingQueryAtom);
+  const [isChatbotOpen, setIsChatbotOpen] = useAtom(isChatbotOpenAtom);
+
+  return {
+    pendingQuery,
+    isChatbotOpen,
+    openChatbotWithQuery: (query: string) => {
+      setPendingQuery(query);
+      setIsChatbotOpen(true);
+    },
+  };
+};
 
 // Zod schema for API response validation
 const SearchCredentialsSchema = z.object({
@@ -459,28 +474,25 @@ function AskWithAIOption({
         }}
       >
         <AIIcon />
-        Ask Baaaaml about "{query}"
+        Ask Baaaml about "{query}"
       </div>
     </button>
   );
 }
 
 // Custom SearchBox with integrated controls
 function CustomSearchBox({
-  onAskAI,
-  onToggleAI,
-  isAIOpen,
+  onToggleChatbot,
 }: {
-  onAskAI: (query: string) => void;
-  onToggleAI?: () => void;
-  isAIOpen?: boolean;
+  onToggleChatbot: () => void;
 }) {
   const { query, refine } = useSearchBox();
   const { hits } = useHits();
   const [inputValue, setInputValue] = useState(query);
   const [isFocused, setIsFocused] = useState(false);
   const [selectedIndex, setSelectedIndex] = useState(-1);
   const inputRef = useRef<HTMLInputElement>(null);
+  const { isChatbotOpen, openChatbotWithQuery } = useChatbot();
 
   useEffect(() => {
     setInputValue(query);
@@ -516,17 +528,11 @@ function CustomSearchBox({
   };
 
   const handleAskAI = () => {
-    onAskAI(inputValue);
+    openChatbotWithQuery(inputValue);
     setIsFocused(false);
   };
 
-  const handleToggleAI = () => {
-    if (onToggleAI) {
-      onToggleAI();
-    }
-  };
-
-  // Calculate total selectable items: Ask Baaaaml option (when query exists) + search results
+  // Calculate total selectable items: Ask Baaaml option (when query exists) + search results
   const totalSelectableItems = (inputValue.trim() ? 1 : 0) + hits.length;
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
@@ -541,7 +547,7 @@ function CustomSearchBox({
     } else if (e.key === 'Enter') {
       e.preventDefault();
       if (selectedIndex === 0 && inputValue.trim()) {
-        // Ask Baaaaml option is selected
+        // Ask Baaaml option is selected
         handleAskAI();
       } else if (selectedIndex > 0) {
         // A search result is selected
@@ -551,7 +557,7 @@ function CustomSearchBox({
           window.location.href = hit.pathname || hit.canonicalPathname || '#';
         }
       } else if (selectedIndex === -1 && inputValue.trim()) {
-        // No selection, trigger Ask Baaaaml by default
+        // No selection, trigger Ask Baaaml by default
         handleAskAI();
       }
     } else if (e.key === 'Escape') {
@@ -704,13 +710,13 @@ function CustomSearchBox({
             </div>
           )}
 
-          {/* Ask Baaaaml / Close button */}
+          {/* Ask Baaaml / Close button */}
           <button
             type="button"
-            onClick={handleToggleAI}
+            onClick={onToggleChatbot}
             style={{
               padding: '6px 10px',
-              background: isAIOpen ? '#6b7280' : '#7c3aed',
+              background: isChatbotOpen ? '#6b7280' : '#7c3aed',
               border: 'none',
               borderRadius: '6px',
               color: 'white',
@@ -727,25 +733,25 @@ function CustomSearchBox({
               boxShadow: '0 1px 2px rgba(0, 0, 0, 0.1)',
             }}
             onMouseEnter={(e) => {
-              e.currentTarget.style.background = isAIOpen ? '#4b5563' : '#6d28d9';
+              e.currentTarget.style.background = isChatbotOpen ? '#4b5563' : '#6d28d9';
               e.currentTarget.style.transform = 'translateY(-0.5px)';
               e.currentTarget.style.boxShadow = '0 2px 4px rgba(0, 0, 0, 0.15)';
             }}
             onMouseLeave={(e) => {
-              e.currentTarget.style.background = isAIOpen ? '#6b7280' : '#7c3aed';
+              e.currentTarget.style.background = isChatbotOpen ? '#6b7280' : '#7c3aed';
               e.currentTarget.style.transform = 'translateY(0)';
               e.currentTarget.style.boxShadow = '0 1px 2px rgba(0, 0, 0, 0.1)';
             }}
           >
-            {isAIOpen ? (
+            {isChatbotOpen ? (
               <>
                 <CloseIcon />
                 Close
               </>
             ) : (
               <>
                 <AIIcon />
-                Ask Baaaaml
+                Ask Baaaml
               </>
             )}
           </button>
@@ -755,23 +761,23 @@ function CustomSearchBox({
       {/* Pass selectedIndex and handlers to hits */}
       <CustomHits
         selectedIndex={selectedIndex}
-        onAskAI={() => handleAskAI()}
+        onAskBaml={() => handleAskAI()}
         query={inputValue}
         isFocused={isFocused}
       />
     </form>
   );
 }
 
-// Custom Hits component with conditional visibility and Ask Baaaaml option
+// Custom Hits component with conditional visibility and Ask Baaaml option
 function CustomHits({
   selectedIndex,
-  onAskAI,
+  onAskBaml,
   query,
   isFocused,
 }: {
   selectedIndex?: number;
-  onAskAI?: () => void;
+  onAskBaml?: () => void;
   query?: string;
   isFocused?: boolean;
 }) {
@@ -804,8 +810,8 @@ function CustomHits({
       }}
     >
       {/* Ask with AI option */}
-      {onAskAI && actualQuery.trim() && (
-        <AskWithAIOption isSelected={selectedIndex === 0} onClick={onAskAI} query={actualQuery} />
+      {onAskBaml && actualQuery.trim() && (
+        <AskWithAIOption isSelected={selectedIndex === 0} onClick={onAskBaml} query={actualQuery} />
       )}
 
       {/* Search results */}
@@ -827,10 +833,10 @@ function CustomHits({
           }}
         >
           <div style={{ marginBottom: '6px' }}>No results found for "{actualQuery}"</div>
-          {onAskAI && (
+          {onAskBaml && (
             <button
               type="button"
-              onClick={onAskAI}
+              onClick={onAskBaml}
               style={{
                 color: '#6366f1',
                 background: 'none',
@@ -841,7 +847,7 @@ function CustomHits({
                 fontWeight: '500',
               }}
             >
-              Ask Baaaaml about this instead
+              Ask Baaaml about this instead
             </button>
           )}
         </div>
@@ -851,13 +857,9 @@ function CustomHits({
 }
 
 export default function AlgoliaSearch({
-  onAskAI,
-  onToggleAI,
-  isAIOpen,
+  onToggleChatbot,
 }: {
-  onAskAI?: (query: string) => void;
-  onToggleAI?: () => void;
-  isAIOpen?: boolean;
+  onToggleChatbot: () => void;
 }) {
   const containerRef = useRef<HTMLDivElement>(null);
   const [searchClient, setSearchClient] = useState<any>(null);
@@ -894,18 +896,6 @@ export default function AlgoliaSearch({
     };
   }, []);
 
-  const handleAskAI = (query: string) => {
-    if (onAskAI) {
-      onAskAI(query);
-    }
-  };
-
-  const handleToggleAI = () => {
-    if (onToggleAI) {
-      onToggleAI();
-    }
-  };
-
   if (isLoading) {
     return (
       <div style={{ position: 'relative', width: '100%' }}>
@@ -971,7 +961,7 @@ export default function AlgoliaSearch({
           analyticsTags={['desktop', 'docs.boundaryml.com', 'search-v3-enhanced']}
         />
 
-        <CustomSearchBox onAskAI={handleAskAI} onToggleAI={handleToggleAI} isAIOpen={isAIOpen} />
+        <CustomSearchBox onToggleChatbot={onToggleChatbot} />
       </InstantSearch>
     </div>
   );