Review

Author: zenoachtig

packages/embed/README.md

@@ -38,7 +38,7 @@ The standalone script provides a global `GitBook` function. See the [API Referen
 GitBook('configure', {
     button: {
         label: 'Ask',
-        icon: 'assistant' // 'assistant' | 'sparkle' | 'circle-question' | 'book'
+        icon: 'assistant' // 'assistant' | 'sparkle' | 'help' | 'book'
     },
     tabs: ['assistant', 'docs'],
     actions: [
@@ -238,16 +238,18 @@ Available in: Standalone script, NPM package, React components
 
 Custom action buttons rendered in the sidebar alongside tabs. Each action button triggers a callback when clicked.
 
+**Note**: This prop was previously named `buttons`. Use `actions` instead, it has the same functionality.
+
 - **Type**: `GitBookEmbeddableActionDefinition[]`
 - **Properties**:
-  - `icon`: `string` - Icon name (e.g., `'circle-question'`, `'book'`, `'sparkle'`, `'rocket'`, `'assistant'`)
+  - `icon`: `string` - Icon name. Any [FontAwesome icon](https://fontawesome.com/search) is supported. (e.g., `'rocket'`, `'comments'`, `'user-circle'`, ...)
   - `label`: `string` - Button label text
   - `onClick`: `() => void | Promise<void>` - Callback function when clicked
 
 ```javascript
 actions: [
     {
-        icon: 'circle-question',
+        icon: 'comments',
         label: 'Contact Support',
         onClick: () => window.open('https://support.example.com', '_blank')
     },
@@ -261,8 +263,6 @@ actions: [
 ]
 ```
 
-**Note**: This prop was previously named `buttons`. Use `actions` instead, it has the same functionality.
-
 ### `greeting`
 
 Available in: Standalone script, NPM package, React components
@@ -398,10 +398,10 @@ Available in: Standalone script only
 
 Configure the widget button for the standalone script. This option is not available when using the NPM package or React components, since they can be customized completely.
 
-- **Type**: `{ label: string, icon: 'assistant' | 'sparkle' | 'circle-question' | 'book' }`
+- **Type**: `{ label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }`
 - **Properties**:
   - `label`: `string` - Button label text
-  - `icon`: `'assistant' | 'sparkle' | 'circle-question' | 'book'` - Icon displayed on the button
+  - `icon`: `'assistant' | 'sparkle' | 'help' | 'book'` - Icon displayed on the button. Choose from one of 4 presets.
 
 ```javascript
 button: {

packages/gitbook/src/components/AI/useAIChat.tsx

@@ -87,6 +87,19 @@ export type AIChatState = {
     error: boolean;
 };
 
+export type AIChatEvent =
+    | { type: 'open' }
+    | { type: 'postMessage'; message: string }
+    | { type: 'clear' }
+    | { type: 'close' };
+
+type AIChatEventData<T extends AIChatEvent['type']> = Omit<
+    Extract<AIChatEvent, { type: T }>,
+    'type'
+>;
+
+type AIChatEventListener = (input?: Omit<AIChatEvent, 'type'>) => void;
+
 export type AIChatController = {
     /** Open the dialog */
     open: () => void;
@@ -97,7 +110,10 @@ export type AIChatController = {
     /** Clear the conversation */
     clear: () => void;
     /** Register an event listener */
-    on: (event: 'postMessage', listener: (input: { message: string }) => void) => () => void;
+    on: <T extends AIChatEvent['type']>(
+        event: T,
+        listener: (input?: AIChatEventData<T>) => void
+    ) => () => void;
 };
 
 const AIChatControllerContext = React.createContext<AIChatController | null>(null);
@@ -125,6 +141,17 @@ export function useAIChatState(): AIChatState {
     return state;
 }
 
+function notify(
+    listeners: AIChatEventListener[] | undefined,
+    input: Omit<AIChatEvent, 'type'>
+): void {
+    if (!listeners) return;
+    // Defer event listeners to next tick so React can process state updates first
+    setTimeout(() => {
+        listeners.forEach((listener) => listener(input));
+    }, 0);
+}
+
 /**
  * Provide the controller to interact with the AI chat.
  */
@@ -140,9 +167,7 @@ export function AIChatProvider(props: {
     const language = useLanguage();
 
     // Event listeners storage
-    const eventsRef = React.useRef<Map<'postMessage', Array<(input: { message: string }) => void>>>(
-        new Map()
-    );
+    const eventsRef = React.useRef<Map<AIChatEvent['type'], AIChatEventListener[]>>(new Map());
 
     // Open AI chat and sync with search state
     const onOpen = React.useCallback(() => {
@@ -156,6 +181,8 @@ export function AIChatProvider(props: {
             scope: prev?.scope ?? 'default',
             open: false, // Close search popover when opening chat
         }));
+
+        notify(eventsRef.current.get('open'), {});
     }, [setSearchState]);
 
     // Close AI chat and clear ask parameter
@@ -169,6 +196,8 @@ export function AIChatProvider(props: {
             scope: prev?.scope ?? 'default',
             open: false,
         }));
+
+        notify(eventsRef.current.get('close'), {});
     }, [setSearchState]);
 
     // Stream a message with the AI backend
@@ -386,11 +415,7 @@ export function AIChatProvider(props: {
                 }));
             }
 
-            // Defer event listeners to next tick so React can process state updates first
-            setTimeout(() => {
-                const listeners = eventsRef.current.get('postMessage') || [];
-                listeners.forEach((listener) => listener(input));
-            }, 0);
+            notify(eventsRef.current.get('postMessage'), { message: input.message });
 
             if (query === input.message) {
                 // Return early if the message is the same as the previous message
@@ -458,9 +483,12 @@ export function AIChatProvider(props: {
     }, [setSearchState]);
 
     const onEvent = React.useCallback(
-        (event: 'postMessage', listener: (input: { message: string }) => void) => {
+        <T extends AIChatEvent['type']>(
+            event: T,
+            listener: (input?: AIChatEventData<T>) => void
+        ) => {
             const listeners = eventsRef.current.get(event) || [];
-            listeners.push(listener);
+            listeners.push(listener as AIChatEventListener);
             eventsRef.current.set(event, listeners);
             return () => {
                 const currentListeners = eventsRef.current.get(event) || [];

packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx

@@ -40,7 +40,7 @@ export function EmbeddableIframeAPI(props: {
     }, [baseURL, siteTitle]);
 
     React.useEffect(() => {
-        return chatController.on('postMessage', () => {
+        return chatController.on('open', () => {
             router.push(`${baseURL}/assistant`);
         });
     }, [router, baseURL, chatController]);
@@ -154,15 +154,6 @@ export function EmbeddableIframeTabs(props: { active?: string }) {
 
     const router = useRouter();
 
-    // Override the active tab if it doesn't match the configured tabs
-    React.useEffect(() => {
-        if (active === 'assistant' && !configuredTabs.includes('assistant')) {
-            router.replace(`${baseURL}/page`);
-        } else if (active === 'docs' && !configuredTabs.includes('docs')) {
-            router.replace(`${baseURL}/assistant`);
-        }
-    }, [configuredTabs, baseURL, router, active]);
-
     const tabs = [
         config.aiMode === CustomizationAIMode.Assistant &&
         assistants[0] &&
@@ -188,6 +179,21 @@ export function EmbeddableIframeTabs(props: { active?: string }) {
             : null,
     ].filter((tab) => tab !== null);
 
+    // Override the active tab if it doesn't match the configured tabs
+    React.useEffect(() => {
+        const hasAssistant = tabs.find((tab) => tab.key === 'assistant');
+        const hasDocs = tabs.find((tab) => tab.key === 'docs');
+        if (!hasAssistant && !hasDocs) {
+            // No valid tabs, do not redirect
+            return;
+        }
+        if (active === 'assistant' && !hasAssistant) {
+            router.replace(`${baseURL}/page`);
+        } else if (active === 'docs' && !hasDocs) {
+            router.replace(`${baseURL}/assistant`);
+        }
+    }, [tabs, baseURL, router, active]);
+
     return (
         <>
             {tabs.length > 1 || actions.length > 0

packages/gitbook/src/lib/embeddable.ts

@@ -59,7 +59,7 @@ export function getEmbeddableLinker(linker: GitBookLinker): GitBookLinker {
         toLinkForContent(rawURL: string): string {
             const result = linker.toLinkForContent(rawURL);
             // If the link is not relative or already an embed, return it as is
-            if (result.includes('~gitbook') || !result.startsWith('/')) {
+            if (result.includes('~gitbook/embed') || !result.startsWith('/')) {
                 return result;
             }