@djangocfg/layouts 2.0.6 → 2.0.8

package/src/snippets/McpChat/context/AIChatContext.tsx

@@ -0,0 +1,245 @@
+'use client';
+
+import React, { createContext, useContext, useState, useCallback, useMemo, useEffect, type ReactNode } from 'react';
+import { useLocalStorage, useIsMobile } from '@djangocfg/ui/hooks';
+import { useAIChat } from '../hooks/useAIChat';
+import { mcpEndpoints, type AIChatMessage, type ChatWidgetConfig, type ChatDisplayMode } from '../types';
+
+const STORAGE_KEY_MODE = 'djangocfg-ai-chat-mode';
+
+/**
+ * AI Chat context state
+ */
+export interface AIChatContextState {
+  /** All chat messages */
+  messages: AIChatMessage[];
+  /** Whether a request is in progress */
+  isLoading: boolean;
+  /** Last error if any */
+  error: Error | null;
+  /** Whether chat panel is open */
+  isOpen: boolean;
+  /** Whether chat is minimized */
+  isMinimized: boolean;
+  /** Configuration */
+  config: ChatWidgetConfig;
+  /** Current display mode */
+  displayMode: ChatDisplayMode;
+  /** Is on mobile device */
+  isMobile: boolean;
+  /** Thread ID for conversation */
+  threadId: string;
+  /** User ID for conversation */
+  userId: string;
+}
+
+/**
+ * AI Chat context actions
+ */
+export interface AIChatContextActions {
+  /** Send a message */
+  sendMessage: (content: string) => Promise<void>;
+  /** Clear all messages */
+  clearMessages: () => void;
+  /** Open chat panel */
+  openChat: () => void;
+  /** Close chat panel */
+  closeChat: () => void;
+  /** Toggle chat panel */
+  toggleChat: () => void;
+  /** Minimize/restore chat */
+  toggleMinimize: () => void;
+  /** Set display mode */
+  setDisplayMode: (mode: ChatDisplayMode) => void;
+  /** Stop streaming response */
+  stopStreaming: () => void;
+}
+
+export type AIChatContextValue = AIChatContextState & AIChatContextActions;
+
+const AIChatContext = createContext<AIChatContextValue | null>(null);
+
+/**
+ * AI Chat provider props
+ */
+export interface AIChatProviderProps {
+  children: ReactNode;
+  /** API endpoint for AI chat (default: /api/ai/chat) */
+  apiEndpoint?: string;
+  /** Widget configuration */
+  config?: Partial<ChatWidgetConfig>;
+  /** Callback on error */
+  onError?: (error: Error) => void;
+  /** Enable streaming (default: true) */
+  enableStreaming?: boolean;
+}
+
+/**
+ * AI Chat provider component
+ * Uses useAIChat hook with server-side persistence
+ */
+export function AIChatProvider({
+  children,
+  apiEndpoint = mcpEndpoints.chat,
+  config: userConfig = {},
+  onError,
+  enableStreaming = true,
+}: AIChatProviderProps) {
+  // Use AI chat hook
+  const {
+    messages,
+    isLoading,
+    error,
+    threadId,
+    userId,
+    sendMessage: sendAIMessage,
+    clearMessages: clearAIMessages,
+    stopStreaming,
+  } = useAIChat({
+    apiEndpoint,
+    onError,
+    enableStreaming,
+  });
+
+  const [isMinimized, setIsMinimized] = useState(false);
+
+  // Display mode with localStorage persistence
+  const [storedMode, setStoredMode] = useLocalStorage<ChatDisplayMode>(STORAGE_KEY_MODE, 'closed');
+
+  const isMobile = useIsMobile();
+
+  // On mobile, sidebar mode is not available - fallback to floating
+  const displayMode: ChatDisplayMode = useMemo(() => {
+    if (isMobile && storedMode === 'sidebar') {
+      return 'floating';
+    }
+    return storedMode;
+  }, [isMobile, storedMode]);
+
+  // Derived state: isOpen is true when not in 'closed' mode
+  const isOpen = displayMode !== 'closed';
+
+  const config: ChatWidgetConfig = useMemo(
+    () => ({
+      apiEndpoint,
+      title: 'DjangoCFG AI Assistant',
+      placeholder: 'Ask about DjangoCFG...',
+      greeting:
+        "Hi! I'm your DjangoCFG AI assistant powered by GPT. Ask me anything about configuration, features, or how to use the library.",
+      position: 'bottom-right',
+      variant: 'default',
+      ...userConfig,
+    }),
+    [apiEndpoint, userConfig]
+  );
+
+  const sendMessage = useCallback(
+    async (content: string) => {
+      await sendAIMessage(content);
+    },
+    [sendAIMessage]
+  );
+
+  const clearMessages = useCallback(() => {
+    clearAIMessages();
+  }, [clearAIMessages]);
+
+  const openChat = useCallback(() => {
+    setStoredMode('floating');
+    setIsMinimized(false);
+  }, [setStoredMode]);
+
+  const closeChat = useCallback(() => {
+    setStoredMode('closed');
+    setIsMinimized(false);
+  }, [setStoredMode]);
+
+  const toggleChat = useCallback(() => {
+    if (displayMode === 'closed') {
+      setStoredMode('floating');
+      setIsMinimized(false);
+    } else {
+      setStoredMode('closed');
+    }
+  }, [displayMode, setStoredMode]);
+
+  const toggleMinimize = useCallback(() => {
+    setIsMinimized((prev) => !prev);
+  }, []);
+
+  const setDisplayMode = useCallback(
+    (mode: ChatDisplayMode) => {
+      // On mobile, sidebar is not available
+      if (isMobile && mode === 'sidebar') {
+        setStoredMode('floating');
+      } else {
+        setStoredMode(mode);
+      }
+      setIsMinimized(false);
+    },
+    [isMobile, setStoredMode]
+  );
+
+  const value = useMemo<AIChatContextValue>(
+    () => ({
+      messages,
+      isLoading,
+      error,
+      isOpen,
+      isMinimized,
+      config,
+      displayMode,
+      isMobile,
+      threadId,
+      userId,
+      sendMessage,
+      clearMessages,
+      openChat,
+      closeChat,
+      toggleChat,
+      toggleMinimize,
+      setDisplayMode,
+      stopStreaming,
+    }),
+    [
+      messages,
+      isLoading,
+      error,
+      isOpen,
+      isMinimized,
+      config,
+      displayMode,
+      isMobile,
+      threadId,
+      userId,
+      sendMessage,
+      clearMessages,
+      openChat,
+      closeChat,
+      toggleChat,
+      toggleMinimize,
+      setDisplayMode,
+      stopStreaming,
+    ]
+  );
+
+  return <AIChatContext.Provider value={value}>{children}</AIChatContext.Provider>;
+}
+
+/**
+ * Hook to access AI chat context
+ */
+export function useAIChatContext(): AIChatContextValue {
+  const context = useContext(AIChatContext);
+  if (!context) {
+    throw new Error('useAIChatContext must be used within an AIChatProvider');
+  }
+  return context;
+}
+
+/**
+ * Hook to check if AI chat context is available
+ */
+export function useAIChatContextOptional(): AIChatContextValue | null {
+  return useContext(AIChatContext);
+}

package/src/snippets/McpChat/context/ChatContext.tsx

@@ -0,0 +1,350 @@
+'use client';
+
+import React, { createContext, useContext, useState, useCallback, useMemo, useEffect, useRef, type ReactNode } from 'react';
+import { useLocalStorage, useIsMobile } from '@djangocfg/ui/hooks';
+import { v4 as uuidv4 } from 'uuid';
+import type { AIChatMessage, ChatApiResponse, AIChatSource, ChatWidgetConfig, ChatDisplayMode } from '../types';
+
+const STORAGE_KEY_MODE = 'djangocfg-chat-mode';
+const STORAGE_KEY_USER_ID = 'djangocfg-chat-user-id';
+const STORAGE_KEY_MESSAGES = 'djangocfg-chat-messages';
+const MAX_STORED_MESSAGES = 50;
+
+function generateMessageId(): string {
+  return `msg_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+
+/**
+ * Serialized message format for localStorage
+ */
+interface SerializedMessage {
+  id: string;
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  timestamp: string; // ISO string
+  sources?: AIChatSource[];
+}
+
+/**
+ * Chat context state
+ */
+export interface ChatContextState {
+  /** All chat messages */
+  messages: AIChatMessage[];
+  /** Whether a request is in progress */
+  isLoading: boolean;
+  /** Last error if any */
+  error: Error | null;
+  /** Whether chat panel is open */
+  isOpen: boolean;
+  /** Whether chat is minimized */
+  isMinimized: boolean;
+  /** Configuration */
+  config: ChatWidgetConfig;
+  /** Current display mode */
+  displayMode: ChatDisplayMode;
+  /** Is on mobile device */
+  isMobile: boolean;
+  /** User ID for this session */
+  userId: string;
+}
+
+/**
+ * Chat context actions
+ */
+export interface ChatContextActions {
+  /** Send a message */
+  sendMessage: (content: string) => Promise<void>;
+  /** Clear all messages */
+  clearMessages: () => void;
+  /** Open chat panel */
+  openChat: () => void;
+  /** Close chat panel */
+  closeChat: () => void;
+  /** Toggle chat panel */
+  toggleChat: () => void;
+  /** Minimize/restore chat */
+  toggleMinimize: () => void;
+  /** Set display mode */
+  setDisplayMode: (mode: ChatDisplayMode) => void;
+}
+
+export type ChatContextValue = ChatContextState & ChatContextActions;
+
+const ChatContext = createContext<ChatContextValue | null>(null);
+
+/**
+ * Chat provider props
+ */
+export interface ChatProviderProps {
+  children: ReactNode;
+  /** API endpoint for chat */
+  apiEndpoint?: string;
+  /** Widget configuration */
+  config?: Partial<ChatWidgetConfig>;
+  /** Callback on error */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Chat provider component
+ */
+export function ChatProvider({
+  children,
+  apiEndpoint = '/api/chat',
+  config: userConfig = {},
+  onError,
+}: ChatProviderProps) {
+  const [messages, setMessages] = useState<AIChatMessage[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [isMinimized, setIsMinimized] = useState(false);
+  const isHydratedRef = useRef(false);
+
+  // Display mode with localStorage persistence
+  const [storedMode, setStoredMode] = useLocalStorage<ChatDisplayMode>(STORAGE_KEY_MODE, 'closed');
+
+  // User ID with localStorage persistence
+  const [userId, setUserId] = useLocalStorage<string>(STORAGE_KEY_USER_ID, '');
+
+  // Messages storage (serialized)
+  const [storedMessages, setStoredMessages] = useLocalStorage<SerializedMessage[]>(STORAGE_KEY_MESSAGES, []);
+
+  const isMobile = useIsMobile();
+
+  // Generate user ID if not exists
+  useEffect(() => {
+    if (!userId) {
+      setUserId(uuidv4());
+    }
+  }, [userId, setUserId]);
+
+  // Load messages from localStorage on mount (once)
+  useEffect(() => {
+    if (isHydratedRef.current) return;
+    isHydratedRef.current = true;
+
+    if (storedMessages.length > 0) {
+      const hydratedMessages: AIChatMessage[] = storedMessages.map((msg) => ({
+        ...msg,
+        timestamp: new Date(msg.timestamp),
+      }));
+      setMessages(hydratedMessages);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [storedMessages]); // Depend on storedMessages to wait for localStorage
+
+  // Save messages to localStorage when they change
+  useEffect(() => {
+    if (!isHydratedRef.current) return;
+
+    const toStore: SerializedMessage[] = messages.slice(-MAX_STORED_MESSAGES).map((msg) => ({
+      id: msg.id,
+      role: msg.role,
+      content: msg.content,
+      timestamp: msg.timestamp.toISOString(),
+      sources: msg.sources,
+    }));
+    setStoredMessages(toStore);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [messages]);
+
+  // On mobile, sidebar mode is not available - fallback to floating
+  const displayMode: ChatDisplayMode = useMemo(() => {
+    if (isMobile && storedMode === 'sidebar') {
+      return 'floating';
+    }
+    return storedMode;
+  }, [isMobile, storedMode]);
+
+  // Derived state: isOpen is true when not in 'closed' mode
+  const isOpen = displayMode !== 'closed';
+
+  const config: ChatWidgetConfig = useMemo(
+    () => ({
+      apiEndpoint,
+      title: 'DjangoCFG Assistant',
+      placeholder: 'Ask about DjangoCFG...',
+      greeting:
+        "Hi! I'm your DjangoCFG documentation assistant. Ask me anything about configuration, features, or how to use the library.",
+      position: 'bottom-right',
+      variant: 'default',
+      ...userConfig,
+    }),
+    [apiEndpoint, userConfig]
+  );
+
+  const sendMessage = useCallback(
+    async (content: string) => {
+      if (!content.trim() || isLoading) return;
+
+      const userMessage: AIChatMessage = {
+        id: generateMessageId(),
+        role: 'user',
+        content: content.trim(),
+        timestamp: new Date(),
+      };
+
+      setMessages((prev) => [...prev, userMessage]);
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const response = await fetch(config.apiEndpoint || apiEndpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            query: content,
+            userId: userId || undefined,
+          }),
+        });
+
+        if (!response.ok) {
+          throw new Error(`HTTP error: ${response.status}`);
+        }
+
+        const data: ChatApiResponse = await response.json();
+
+        if (!data.success) {
+          throw new Error(data.error || 'Failed to get response');
+        }
+
+        const sources: AIChatSource[] =
+          data.results?.map((r) => ({
+            title: r.chunk.title,
+            path: r.chunk.path,
+            url: r.chunk.url,
+            section: r.chunk.section,
+            score: r.score,
+          })) || [];
+
+        const assistantMessage: AIChatMessage = {
+          id: generateMessageId(),
+          role: 'assistant',
+          content: data.answer || 'I found some relevant documentation.',
+          timestamp: new Date(),
+          sources,
+        };
+
+        setMessages((prev) => [...prev, assistantMessage]);
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error('Unknown error');
+        setError(error);
+        onError?.(error);
+
+        const errorMessage: AIChatMessage = {
+          id: generateMessageId(),
+          role: 'assistant',
+          content: `Sorry, I encountered an error: ${error.message}. Please try again.`,
+          timestamp: new Date(),
+        };
+
+        setMessages((prev) => [...prev, errorMessage]);
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [apiEndpoint, config.apiEndpoint, isLoading, onError, userId]
+  );
+
+  const clearMessages = useCallback(() => {
+    setMessages([]);
+    setStoredMessages([]);
+    setError(null);
+  }, [setStoredMessages]);
+
+  const openChat = useCallback(() => {
+    setStoredMode('floating');
+    setIsMinimized(false);
+  }, [setStoredMode]);
+
+  const closeChat = useCallback(() => {
+    setStoredMode('closed');
+    setIsMinimized(false);
+  }, [setStoredMode]);
+
+  const toggleChat = useCallback(() => {
+    if (displayMode === 'closed') {
+      setStoredMode('floating');
+      setIsMinimized(false);
+    } else {
+      setStoredMode('closed');
+    }
+  }, [displayMode, setStoredMode]);
+
+  const toggleMinimize = useCallback(() => {
+    setIsMinimized((prev) => !prev);
+  }, []);
+
+  const setDisplayMode = useCallback(
+    (mode: ChatDisplayMode) => {
+      // On mobile, sidebar is not available
+      if (isMobile && mode === 'sidebar') {
+        setStoredMode('floating');
+      } else {
+        setStoredMode(mode);
+      }
+      setIsMinimized(false);
+    },
+    [isMobile, setStoredMode]
+  );
+
+  const value = useMemo<ChatContextValue>(
+    () => ({
+      messages,
+      isLoading,
+      error,
+      isOpen,
+      isMinimized,
+      config,
+      displayMode,
+      isMobile,
+      userId: userId || '',
+      sendMessage,
+      clearMessages,
+      openChat,
+      closeChat,
+      toggleChat,
+      toggleMinimize,
+      setDisplayMode,
+    }),
+    [
+      messages,
+      isLoading,
+      error,
+      isOpen,
+      isMinimized,
+      config,
+      displayMode,
+      isMobile,
+      userId,
+      sendMessage,
+      clearMessages,
+      openChat,
+      closeChat,
+      toggleChat,
+      toggleMinimize,
+      setDisplayMode,
+    ]
+  );
+
+  return <ChatContext.Provider value={value}>{children}</ChatContext.Provider>;
+}
+
+/**
+ * Hook to access chat context
+ */
+export function useChatContext(): ChatContextValue {
+  const context = useContext(ChatContext);
+  if (!context) {
+    throw new Error('useChatContext must be used within a ChatProvider');
+  }
+  return context;
+}
+
+/**
+ * Hook to check if chat context is available
+ */
+export function useChatContextOptional(): ChatContextValue | null {
+  return useContext(ChatContext);
+}

package/src/snippets/McpChat/context/index.ts

@@ -0,0 +1,7 @@
+'use client';
+
+export { ChatProvider, useChatContext, useChatContextOptional } from './ChatContext';
+export type { ChatContextState, ChatContextActions, ChatContextValue, ChatProviderProps } from './ChatContext';
+
+export { AIChatProvider, useAIChatContext, useAIChatContextOptional } from './AIChatContext';
+export type { AIChatContextState, AIChatContextActions, AIChatContextValue, AIChatProviderProps } from './AIChatContext';

package/src/snippets/McpChat/hooks/index.ts

@@ -0,0 +1,5 @@
+'use client';
+
+export { useAIChat } from './useAIChat';
+export { useChatLayout } from './useChatLayout';
+export type { ChatLayoutConfig, UseChatLayoutReturn } from './useChatLayout';