@djangocfg/layouts 2.0.6 → 2.0.8

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

@@ -0,0 +1,329 @@
+'use client';
+
+import { useEffect, useCallback, useRef } from 'react';
+import type { ChatDisplayMode } from '../types';
+
+/**
+ * Configuration for chat layout management
+ */
+export interface ChatLayoutConfig {
+  /** Width of sidebar in pixels */
+  sidebarWidth?: number;
+  /** Z-index for chat elements */
+  zIndex?: number;
+  /** Animation duration in ms */
+  animationDuration?: number;
+  /** Element to push (defaults to body) */
+  pushTarget?: 'body' | 'main' | string;
+}
+
+/**
+ * Return type for useChatLayout hook
+ */
+export interface UseChatLayoutReturn {
+  /** Apply layout changes for mode */
+  applyLayout: (mode: ChatDisplayMode) => void;
+  /** Reset layout to default */
+  resetLayout: () => void;
+  /** Get CSS for sidebar container */
+  getSidebarStyles: () => React.CSSProperties;
+  /** Get CSS for floating container */
+  getFloatingStyles: (position: 'bottom-right' | 'bottom-left') => React.CSSProperties;
+  /** Get CSS for FAB button */
+  getFabStyles: (position: 'bottom-right' | 'bottom-left') => React.CSSProperties;
+}
+
+const DEFAULT_CONFIG: Required<ChatLayoutConfig> = {
+  sidebarWidth: 400,
+  zIndex: 300,
+  animationDuration: 200,
+  pushTarget: 'body',
+};
+
+/** Stored original styles for fixed elements */
+interface FixedElementOriginalStyles {
+  element: HTMLElement;
+  right: string;
+  transition: string;
+}
+
+/**
+ * Hook for managing chat layout embedding modes
+ *
+ * Handles:
+ * - Sidebar mode: pushes content left by adding margin to target element
+ *   AND automatically adjusts all position:fixed elements with right:0
+ * - Floating mode: positions chat at bottom-right/left
+ * - Closed mode: just shows FAB button
+ *
+ * @example
+ * ```tsx
+ * const { applyLayout, getSidebarStyles, getFloatingStyles } = useChatLayout({
+ *   sidebarWidth: 400,
+ * });
+ *
+ * useEffect(() => {
+ *   applyLayout(displayMode);
+ * }, [displayMode]);
+ * ```
+ */
+export function useChatLayout(config?: ChatLayoutConfig): UseChatLayoutReturn {
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+  const { sidebarWidth, zIndex, animationDuration, pushTarget } = mergedConfig;
+
+  // Store original styles for cleanup
+  const originalStylesRef = useRef<{
+    marginRight?: string;
+    overflowX?: string;
+    transition?: string;
+  } | null>(null);
+
+  // Store original styles for fixed elements
+  const fixedElementsRef = useRef<FixedElementOriginalStyles[]>([]);
+
+  // Current mode for cleanup
+  const currentModeRef = useRef<ChatDisplayMode>('closed');
+
+  /**
+   * Get the target element to push
+   */
+  const getTargetElement = useCallback((): HTMLElement | null => {
+    if (typeof window === 'undefined') return null;
+
+    if (pushTarget === 'body') {
+      return document.body;
+    } else if (pushTarget === 'main') {
+      return document.querySelector('main');
+    } else {
+      return document.querySelector(pushTarget);
+    }
+  }, [pushTarget]);
+
+  /**
+   * Find all fixed/sticky elements that need right adjustment
+   */
+  const getFixedElements = useCallback((): HTMLElement[] => {
+    if (typeof window === 'undefined') return [];
+
+    const elements: HTMLElement[] = [];
+    const allElements = document.querySelectorAll('*');
+
+    allElements.forEach((el) => {
+      if (!(el instanceof HTMLElement)) return;
+      // Skip chat sidebar itself
+      if (el.closest('[data-chat-sidebar-panel]')) return;
+
+      const style = window.getComputedStyle(el);
+      const position = style.position;
+      const right = style.right;
+
+      // Check for fixed/sticky elements with right: 0
+      if ((position === 'fixed' || position === 'sticky') && right === '0px') {
+        elements.push(el);
+      }
+    });
+
+    return elements;
+  }, []);
+
+  /**
+   * Save original styles before modification
+   */
+  const saveOriginalStyles = useCallback((element: HTMLElement) => {
+    if (!originalStylesRef.current) {
+      originalStylesRef.current = {
+        marginRight: element.style.marginRight,
+        overflowX: element.style.overflowX,
+        transition: element.style.transition,
+      };
+    }
+  }, []);
+
+  /**
+   * Restore original styles
+   */
+  const restoreOriginalStyles = useCallback((element: HTMLElement) => {
+    if (originalStylesRef.current) {
+      element.style.marginRight = originalStylesRef.current.marginRight || '';
+      element.style.overflowX = originalStylesRef.current.overflowX || '';
+      element.style.transition = originalStylesRef.current.transition || '';
+      element.removeAttribute('data-chat-sidebar');
+      originalStylesRef.current = null;
+    }
+  }, []);
+
+  /**
+   * Adjust fixed elements for sidebar
+   */
+  const adjustFixedElements = useCallback(
+    (open: boolean) => {
+      if (open) {
+        // Save and adjust fixed elements
+        const fixedElements = getFixedElements();
+        fixedElementsRef.current = fixedElements.map((el) => ({
+          element: el,
+          right: el.style.right,
+          transition: el.style.transition,
+        }));
+
+        fixedElements.forEach((el) => {
+          el.style.transition = `right ${animationDuration}ms ease`;
+          el.style.right = `${sidebarWidth}px`;
+        });
+      } else {
+        // Restore fixed elements
+        fixedElementsRef.current.forEach(({ element, right, transition }) => {
+          element.style.transition = `right ${animationDuration}ms ease`;
+          element.style.right = '0px';
+
+          // Restore original after animation
+          setTimeout(() => {
+            element.style.right = right;
+            element.style.transition = transition;
+          }, animationDuration);
+        });
+        fixedElementsRef.current = [];
+      }
+    },
+    [getFixedElements, sidebarWidth, animationDuration]
+  );
+
+  /**
+   * Apply sidebar mode layout
+   */
+  const applySidebarLayout = useCallback(() => {
+    const target = getTargetElement();
+    if (!target) return;
+
+    saveOriginalStyles(target);
+
+    // Add smooth transition
+    target.style.transition = `margin-right ${animationDuration}ms ease`;
+    target.style.marginRight = `${sidebarWidth}px`;
+    target.style.overflowX = 'hidden';
+    target.setAttribute('data-chat-sidebar', 'open');
+
+    // Adjust fixed elements (header, etc.)
+    adjustFixedElements(true);
+
+    currentModeRef.current = 'sidebar';
+  }, [getTargetElement, saveOriginalStyles, sidebarWidth, animationDuration, adjustFixedElements]);
+
+  /**
+   * Apply floating/closed mode layout (reset sidebar push)
+   */
+  const applyDefaultLayout = useCallback(
+    (mode: ChatDisplayMode) => {
+      const target = getTargetElement();
+      if (!target) return;
+
+      // Only restore if we were in sidebar mode
+      if (currentModeRef.current === 'sidebar') {
+        // Add transition for smooth animation
+        target.style.transition = `margin-right ${animationDuration}ms ease`;
+        target.style.marginRight = '0px';
+
+        // Restore fixed elements
+        adjustFixedElements(false);
+
+        // Remove styles after animation completes
+        setTimeout(() => {
+          restoreOriginalStyles(target);
+        }, animationDuration);
+      }
+
+      currentModeRef.current = mode;
+    },
+    [getTargetElement, restoreOriginalStyles, animationDuration, adjustFixedElements]
+  );
+
+  /**
+   * Apply layout changes for given mode
+   */
+  const applyLayout = useCallback(
+    (mode: ChatDisplayMode) => {
+      if (mode === 'sidebar') {
+        applySidebarLayout();
+      } else {
+        applyDefaultLayout(mode);
+      }
+    },
+    [applySidebarLayout, applyDefaultLayout]
+  );
+
+  /**
+   * Reset layout to default (cleanup)
+   */
+  const resetLayout = useCallback(() => {
+    const target = getTargetElement();
+    if (target && originalStylesRef.current) {
+      restoreOriginalStyles(target);
+    }
+    // Restore fixed elements immediately on cleanup
+    fixedElementsRef.current.forEach(({ element, right, transition }) => {
+      element.style.right = right;
+      element.style.transition = transition;
+    });
+    fixedElementsRef.current = [];
+    currentModeRef.current = 'closed';
+  }, [getTargetElement, restoreOriginalStyles]);
+
+  /**
+   * Get CSS styles for sidebar container
+   */
+  const getSidebarStyles = useCallback((): React.CSSProperties => {
+    return {
+      position: 'fixed',
+      top: 0,
+      right: 0,
+      bottom: 0,
+      width: `${sidebarWidth}px`,
+      zIndex,
+    };
+  }, [sidebarWidth, zIndex]);
+
+  /**
+   * Get CSS styles for floating container
+   */
+  const getFloatingStyles = useCallback(
+    (position: 'bottom-right' | 'bottom-left'): React.CSSProperties => {
+      return {
+        position: 'fixed',
+        zIndex: zIndex - 50, // Slightly lower than sidebar
+        bottom: 56, // Above banner
+        ...(position === 'bottom-right' ? { right: 16 } : { left: 16 }),
+      };
+    },
+    [zIndex]
+  );
+
+  /**
+   * Get CSS styles for FAB button
+   */
+  const getFabStyles = useCallback(
+    (position: 'bottom-right' | 'bottom-left'): React.CSSProperties => {
+      return {
+        position: 'fixed',
+        zIndex: zIndex - 50,
+        bottom: 56,
+        ...(position === 'bottom-right' ? { right: 16 } : { left: 16 }),
+      };
+    },
+    [zIndex]
+  );
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      resetLayout();
+    };
+  }, [resetLayout]);
+
+  return {
+    applyLayout,
+    resetLayout,
+    getSidebarStyles,
+    getFloatingStyles,
+    getFabStyles,
+  };
+}

package/src/snippets/McpChat/index.ts

@@ -0,0 +1,76 @@
+'use client';
+
+/**
+ * @djangocfg/mcp-chat
+ *
+ * React chat components for DjangoCFG documentation assistant.
+ * Works with @djangocfg/mcp for semantic search.
+ *
+ * @example Basic usage (standalone widget)
+ * ```tsx
+ * import { ChatWidget } from '@djangocfg/mcp-chat';
+ *
+ * export default function Layout({ children }) {
+ *   return (
+ *     <>
+ *       {children}
+ *       <ChatWidget apiEndpoint="/api/chat" />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example With provider (for accessing chat from multiple components)
+ * ```tsx
+ * import { ChatProvider, ChatWidget, useChatContext } from '@djangocfg/mcp-chat';
+ *
+ * function OpenChatButton() {
+ *   const { openChat } = useChatContext();
+ *   return <button onClick={openChat}>Ask AI</button>;
+ * }
+ *
+ * export default function Layout({ children }) {
+ *   return (
+ *     <ChatProvider apiEndpoint="/api/chat">
+ *       {children}
+ *       <OpenChatButton />
+ *       <ChatWidget />
+ *     </ChatProvider>
+ *   );
+ * }
+ * ```
+ */
+
+// Components
+export { ChatWidget, AIChatWidget, ChatPanel, MessageBubble, AIMessageInput } from './components';
+export type {
+  ChatWidgetProps,
+  AIChatWidgetProps,
+  ChatPanelProps,
+  MessageBubbleProps,
+  AIMessageInputProps,
+} from './components';
+
+// Context
+export { AIChatProvider, useAIChatContext, useAIChatContextOptional } from './context';
+export type {
+  AIChatContextState,
+  AIChatContextActions,
+  AIChatContextValue,
+  AIChatProviderProps,
+} from './context';
+
+// Hooks
+export { useAIChat, useChatLayout } from './hooks';
+export type { ChatLayoutConfig, UseChatLayoutReturn } from './hooks';
+
+// Types
+export type {
+  AIChatMessage,
+  AIChatSource,
+  AIMessageRole,
+  AIChatApiResponse,
+  UseAIChatOptions,
+  UseAIChatReturn,
+  ChatWidgetConfig,
+} from './types';

package/src/snippets/McpChat/types.ts

@@ -0,0 +1,141 @@
+/**
+ * Types for @djangocfg/mcp-chat
+ */
+
+// Re-export config constants for backwards compatibility
+export { DEFAULT_CHAT_API_ENDPOINT, mcpEndpoints } from './config';
+
+/**
+ * AI Chat message role
+ */
+export type AIMessageRole = 'user' | 'assistant' | 'system';
+
+/**
+ * AI Chat message
+ */
+export interface AIChatMessage {
+  id: string;
+  role: AIMessageRole;
+  content: string;
+  timestamp: Date;
+  /** Related documentation links */
+  sources?: AIChatSource[];
+  /** Is message still being generated */
+  isStreaming?: boolean;
+}
+
+/**
+ * AI Documentation source reference
+ */
+export interface AIChatSource {
+  title: string;
+  path: string;
+  url?: string;
+  section?: string;
+  score?: number;
+}
+
+/**
+ * Chat API response
+ */
+export interface ChatApiResponse {
+  success: boolean;
+  results?: Array<{
+    chunk: {
+      id: string;
+      path: string;
+      title: string;
+      section?: string;
+      content: string;
+      url?: string;
+    };
+    score: number;
+  }>;
+  answer?: string;
+  error?: string;
+}
+
+/**
+ * Chat display mode
+ * - closed: Only FAB button visible
+ * - floating: Floating panel (default)
+ * - sidebar: Full-height sidebar on the right (desktop only)
+ */
+export type ChatDisplayMode = 'closed' | 'floating' | 'sidebar';
+
+/**
+ * Chat widget configuration
+ */
+export interface ChatWidgetConfig {
+  /** API endpoint for chat (default: /api/chat) */
+  apiEndpoint?: string;
+  /** Widget title */
+  title?: string;
+  /** Placeholder text for input */
+  placeholder?: string;
+  /** Initial greeting message */
+  greeting?: string;
+  /** Position on screen */
+  position?: 'bottom-right' | 'bottom-left';
+  /** Theme variant */
+  variant?: 'default' | 'minimal';
+}
+
+// =============================================================================
+// AI Chat Types
+// =============================================================================
+
+/**
+ * AI Chat API response
+ */
+export interface AIChatApiResponse {
+  success: boolean;
+  content?: string;
+  sources?: Array<{
+    id?: string;
+    title: string;
+    path: string;
+    url?: string;
+    section?: string;
+    score?: number;
+  }>;
+  threadId?: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  error?: string;
+}
+
+/**
+ * useAIChat hook options
+ */
+export interface UseAIChatOptions {
+  /** API endpoint (default: /api/ai/chat) */
+  apiEndpoint?: string;
+  /** Initial messages */
+  initialMessages?: AIChatMessage[];
+  /** Callback on error */
+  onError?: (error: Error) => void;
+  /** Enable streaming responses (default: true) */
+  enableStreaming?: boolean;
+  /** Thread ID for conversation (generated if not provided) */
+  threadId?: string;
+  /** User ID for conversation (generated if not provided) */
+  userId?: string;
+}
+
+/**
+ * useAIChat hook return type
+ */
+export interface UseAIChatReturn {
+  messages: AIChatMessage[];
+  isLoading: boolean;
+  error: Error | null;
+  threadId: string;
+  userId: string;
+  sendMessage: (content: string) => Promise<void>;
+  clearMessages: () => void;
+  stopStreaming: () => void;
+}

package/src/snippets/index.ts

@@ -9,3 +9,35 @@ export * from './Breadcrumbs';
 export * from './AuthDialog';
 export * from './ContactForm';
 export * from './Analytics';
+
+// MCP Chat (AI-powered documentation assistant)
+export {
+  AIChatWidget,
+  ChatPanel,
+  MessageBubble,
+  AIMessageInput,
+  AIChatProvider,
+  useAIChatContext,
+  useAIChatContextOptional,
+  useAIChat,
+  useChatLayout,
+} from './McpChat';
+export type {
+  AIChatWidgetProps,
+  ChatPanelProps,
+  MessageBubbleProps,
+  AIMessageInputProps,
+  AIChatContextState,
+  AIChatContextActions,
+  AIChatContextValue,
+  AIChatProviderProps,
+  ChatLayoutConfig,
+  UseChatLayoutReturn,
+  AIChatMessage,
+  AIChatSource,
+  AIMessageRole,
+  AIChatApiResponse,
+  UseAIChatOptions,
+  UseAIChatReturn,
+  ChatWidgetConfig,
+} from './McpChat';

package/src/utils/index.ts

@@ -3,5 +3,4 @@
  */
 
 export * from './logger';
-export * from './og-image';