@djangocfg/layouts 2.1.18 → 2.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.18",
+  "version": "2.1.20",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -92,9 +92,9 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.18",
-    "@djangocfg/centrifugo": "^2.1.18",
-    "@djangocfg/ui-nextjs": "^2.1.18",
+    "@djangocfg/api": "^2.1.20",
+    "@djangocfg/centrifugo": "^2.1.20",
+    "@djangocfg/ui-nextjs": "^2.1.20",
     "@hookform/resolvers": "^5.2.0",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -114,7 +114,7 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.18",
+    "@djangocfg/typescript-config": "^2.1.20",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/components/errors/ErrorLayout.tsx

@@ -49,54 +49,48 @@ function getErrorIcon(code?: string | number): React.ReactNode {
     case '404':
       return (
         <svg
-          className="w-24 h-24 mx-auto text-muted-foreground/50"
-          fill="none"
-          stroke="currentColor"
-          viewBox="0 0 24 24"
+          className="w-32 h-32 mx-auto text-foreground/80"
+          viewBox="0 0 32 32"
+          fill="currentColor"
           aria-hidden="true"
         >
-          {/* Missing Page Icon */}
-          <path
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            strokeWidth={1.5}
-            d="M9.343 3.07a7.227 7.227 0 0111.558 0c.806.515 1.393 1.39 1.393 2.37v6.636c0 .98-.587 1.855-1.393 2.37a7.227 7.227 0 01-11.558 0c-.806-.515-1.393-1.39-1.393-2.37V5.44c0-.98.587-1.855 1.393-2.37zM12 13a1 1 0 100-2 1 1 0 000 2z"
-          />
+          {/* Cloud with 404 Icon */}
+          <g>
+            <path fillRule="evenodd" d="M19.889 21.734v-.947l-.631.947z" />
+            <path d="M15.484 19.636h1.032a.017.017 0 0 1 .017.017v3.1a.016.016 0 0 1-.016.016h-1.034a.016.016 0 0 1-.016-.016v-3.1a.017.017 0 0 1 .017-.017z" />
+            <g fillRule="evenodd">
+              <path d="M12.402 21.734v-.947l-.631.947z" />
+              <path d="M16 1.5A14.5 14.5 0 1 0 30.5 16 14.507 14.507 0 0 0 16 1.5zm-2.324 21.234H13.4v.532a.5.5 0 0 1-1 0v-.532h-1.563a.5.5 0 0 1-.416-.778l2.067-3.1a.5.5 0 0 1 .914.28v2.6h.274a.5.5 0 0 1 0 1zm-2.137-9.9A4.14 4.14 0 0 1 15.545 9.8a.5.5 0 0 1 0 1 3.138 3.138 0 0 0-3.04 2.3.5.5 0 0 1-.966-.259zm5.994 9.911a1.017 1.017 0 0 1-1.017 1.016h-1.032a1.017 1.017 0 0 1-1.017-1.016v-3.1a1.017 1.017 0 0 1 1.017-1.016h1.032a1.017 1.017 0 0 1 1.017 1.016zm3.63-.016h-.274v.532a.5.5 0 0 1-1 0v-.532h-1.565a.5.5 0 0 1-.416-.778l2.067-3.1a.5.5 0 0 1 .914.28v2.6h.274a.5.5 0 0 1 0 1zm1.036-1.52a.5.5 0 1 1-.4-.917 3.263 3.263 0 0 0-1.337-6.266.5.5 0 0 1-.5-.5 4.6 4.6 0 0 0-9.2 0 4.45 4.45 0 0 0 .153 1.161.5.5 0 0 1-.411.625 2.633 2.633 0 0 0-.364 5.148.5.5 0 0 1-.278.961 3.63 3.63 0 0 1-.024-6.984 5.467 5.467 0 0 1-.076-.911 5.6 5.6 0 0 1 11.182-.474 4.258 4.258 0 0 1 1.256 8.162z" />
+            </g>
+          </g>
         </svg>
       );
     case '500':
       return (
         <svg
-          className="w-24 h-24 mx-auto text-muted-foreground/50"
-          fill="none"
-          stroke="currentColor"
-          viewBox="0 0 24 24"
+          className="w-32 h-32 mx-auto text-foreground/80"
+          viewBox="0 0 512 512"
+          fill="currentColor"
           aria-hidden="true"
         >
-          {/* Server Error Icon - Server with X */}
-          <rect x="2" y="3" width="20" height="7" rx="1" strokeWidth={1.5} />
-          <rect x="2" y="14" width="20" height="7" rx="1" strokeWidth={1.5} />
-          <circle cx="6" cy="6.5" r="1" fill="currentColor" />
-          <circle cx="6" cy="17.5" r="1" fill="currentColor" />
-          <path strokeLinecap="round" strokeWidth={1.5} d="M22 2L2 22" />
+          {/* Server Error Icon - Circle with Exclamation */}
+          <g>
+            <path d="M256 118c-76.1 0-138 61.88-138 138s61.9 138.05 138 138.05 138-61.93 138-138S332.1 118 256 118zm0 237.93a30.12 30.12 0 1 1 30.11-30.12A30.15 30.15 0 0 1 256 355.88zm30.11-80.31a8.48 8.48 0 0 1-8.47 8.48h-43.28a8.48 8.48 0 0 1-8.47-8.48v-111a8.47 8.47 0 0 1 8.47-8.47h43.28a8.47 8.47 0 0 1 8.47 8.47z" />
+            <path d="M256 312.6a13.17 13.17 0 1 0 13.16 13.16A13.17 13.17 0 0 0 256 312.6zM242.84 173.07h26.32v94.02h-26.32z" />
+            <path d="M256 0C114.62 0 0 114.62 0 256s114.62 256 256 256 256-114.62 256-256S397.38 0 256 0zm109.57 365.6A155 155 0 1 1 411 256a153.91 153.91 0 0 1-45.43 109.6z" />
+          </g>
         </svg>
       );
     case '403':
       return (
         <svg
-          className="w-24 h-24 mx-auto text-muted-foreground/50"
-          fill="none"
-          stroke="currentColor"
+          className="w-32 h-32 mx-auto text-foreground/80"
           viewBox="0 0 24 24"
+          fill="currentColor"
           aria-hidden="true"
         >
-          {/* Forbidden Icon */}
-          <path
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            strokeWidth={1.5}
-            d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"
-          />
+          {/* Forbidden Icon - Circle with X */}
+          <path d="M12 1a11 11 0 1 0 11 11A11.013 11.013 0 0 0 12 1zm4.242 13.829a1 1 0 1 1-1.414 1.414L12 13.414l-2.828 2.829a1 1 0 0 1-1.414-1.414L10.586 12 7.758 9.171a1 1 0 1 1 1.414-1.414L12 10.586l2.828-2.829a1 1 0 1 1 1.414 1.414L13.414 12z" />
         </svg>
       );
     default:
@@ -148,18 +142,6 @@ export function ErrorLayout({
   return (
     <div className="min-h-screen flex items-center justify-center px-4 bg-background">
       <div className="max-w-2xl w-full text-center space-y-8">
-        {/* Error Code */}
-        {code && (
-          <div className="relative">
-            <h1
-              className="text-[12rem] font-bold leading-none text-muted/20 select-none"
-              aria-hidden="true"
-            >
-              {code}
-            </h1>
-          </div>
-        )}
-
         {/* Illustration */}
         {finalIllustration && (
           <div className="flex justify-center py-8">

package/src/layouts/AdminLayout/AdminLayout.tsx

@@ -17,7 +17,7 @@
  *   }}
  *   header={{
  *     title: 'Admin Dashboard',
- *     profilePath: '/profile' // Optional
+ *     profilePath: '/private/profile' // Optional
  *   }}
  * >
  *   {children}

package/src/layouts/AppLayout/AppLayout.tsx

@@ -39,7 +39,6 @@
 import React, { ReactNode, useMemo } from 'react';
 import { usePathname } from 'next/navigation';
 import { CentrifugoProvider } from '@djangocfg/centrifugo';
-import { ErrorBoundary } from '../../components/errors/ErrorBoundary';
 import { type AuthConfig } from '@djangocfg/api/auth';
 import { type ValidationErrorConfig, type CORSErrorConfig, type NetworkErrorConfig } from '../../components/errors/ErrorsTracker';
 import { AnalyticsProvider } from '../../snippets/Analytics';
@@ -151,7 +150,6 @@ function AppLayoutContent({
   adminLayout,
   analytics,
   centrifugo,
-  errorBoundary,
 }: AppLayoutProps) {
   const pathname = usePathname();
 
@@ -165,8 +163,6 @@ function AppLayoutContent({
     [pathname, adminLayout, privateLayout, publicLayout]
   );
 
-  const enableErrorBoundary = errorBoundary?.enabled !== false;
-
   // Render appropriate layout based on mode
   const renderLayout = () => {
     switch (layoutMode) {
@@ -240,20 +236,7 @@ function AppLayoutContent({
       {content}
     </CentrifugoProvider>
   );
-  
-  
-  // Wrap with ErrorBoundary if enabled
-  if (enableErrorBoundary) {
-    return (
-      <ErrorBoundary
-        supportEmail={errorBoundary?.supportEmail}
-        onError={errorBoundary?.onError}
-      >
-        {content}
-      </ErrorBoundary>
-    );
-  }
-  
+
   return content;
 }
 
@@ -261,13 +244,14 @@ function AppLayoutContent({
  * AppLayout - Main Component with All Providers
  */
 export function AppLayout(props: AppLayoutProps) {
-  const { theme, auth, errorTracking } = props;
+  const { theme, auth, errorTracking, errorBoundary } = props;
 
   return (
     <BaseApp
       theme={theme}
       auth={auth}
       errorTracking={errorTracking}
+      errorBoundary={errorBoundary}
     >
       <AppLayoutContent {...props} />
     </BaseApp>

package/src/layouts/AppLayout/BaseApp.tsx

@@ -7,17 +7,25 @@
  * - SWRConfig (data fetching)
  * - AuthProvider (authentication context)
  * - ErrorTrackingProvider (error handling)
+ * - ErrorBoundary (React error boundary, enabled by default)
  *
  * @example
  * ```tsx
  * import { BaseApp } from '@djangocfg/layouts';
  *
+ * // ErrorBoundary enabled by default
  * <BaseApp
  *   theme={{ defaultTheme: 'system' }}
  *   auth={{ loginPath: '/auth/login' }}
+ *   errorBoundary={{ supportEmail: 'support@example.com' }}
  * >
  *   {children}
  * </BaseApp>
+ *
+ * // To disable ErrorBoundary:
+ * <BaseApp errorBoundary={{ enabled: false }}>
+ *   {children}
+ * </BaseApp>
  * ```
  */
 
@@ -28,6 +36,7 @@ import { SWRConfig } from 'swr';
 import { ThemeProvider, Toaster, TooltipProvider } from '@djangocfg/ui-nextjs';
 import { AuthProvider, type AuthConfig } from '@djangocfg/api/auth';
 import { ErrorTrackingProvider, type ValidationErrorConfig, type CORSErrorConfig, type NetworkErrorConfig } from '../../components/errors/ErrorsTracker';
+import { ErrorBoundary } from '../../components/errors/ErrorBoundary';
 import { PageProgress } from '../../components/core/PageProgress';
 
 export interface BaseAppProps {
@@ -56,12 +65,19 @@ export interface BaseAppProps {
     revalidateOnReconnect?: boolean;
     dedupingInterval?: number;
   };
+
+  /** Error boundary configuration (enabled by default) */
+  errorBoundary?: {
+    enabled?: boolean;
+    supportEmail?: string;
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+  };
 }
 
 /**
  * BaseApp - Core providers wrapper for any React/Next.js app
  *
- * Includes: ThemeProvider, TooltipProvider, SWRConfig, AuthProvider, ErrorTrackingProvider
+ * Includes: ThemeProvider, TooltipProvider, SWRConfig, AuthProvider, ErrorTrackingProvider, ErrorBoundary (optional)
  * Also renders global Toaster and PageProgress components
  */
 export function BaseApp({
@@ -69,9 +85,13 @@ export function BaseApp({
   theme,
   auth,
   errorTracking,
+  errorBoundary,
   swr,
 }: BaseAppProps) {
-  return (
+  // ErrorBoundary is enabled by default
+  const enableErrorBoundary = errorBoundary?.enabled !== false;
+
+  const content = (
     <ThemeProvider
       defaultTheme={theme?.defaultTheme || 'system'}
       storageKey={theme?.storageKey}
@@ -100,4 +120,18 @@ export function BaseApp({
       </TooltipProvider>
     </ThemeProvider>
   );
+
+  // Wrap with ErrorBoundary only if explicitly enabled
+  if (enableErrorBoundary) {
+    return (
+      <ErrorBoundary
+        supportEmail={errorBoundary?.supportEmail}
+        onError={errorBoundary?.onError}
+      >
+        {content}
+      </ErrorBoundary>
+    );
+  }
+
+  return content;
 }

package/src/layouts/PrivateLayout/PrivateLayout.tsx

@@ -24,7 +24,7 @@
  *   }}
  *   header={{
  *     title: 'Dashboard',
- *     profilePath: '/profile' // Optional, defaults to '/profile'
+ *     profilePath: '/private/profile' // Optional, defaults to '/private/profile'
  *   }}
  * >
  *   {children}

package/src/layouts/PrivateLayout/components/PrivateHeader.tsx

@@ -24,7 +24,7 @@ interface PrivateHeaderProps {
 
 export function PrivateHeader({ header }: PrivateHeaderProps) {
   const { user, logout } = useAuth();
-  const profilePath = header?.profilePath || '/profile';
+  const profilePath = header?.profilePath || '/private/profile';
 
   return (
     <header

package/src/layouts/_components/UserMenu.tsx

@@ -34,8 +34,8 @@ export interface UserMenuProps {
 
 export function UserMenu({
   variant = 'desktop',
-  profilePath = '/profile',
-  dashboardPath = '/dashboard',
+  profilePath = '/private/profile',
+  dashboardPath = '/private',
   authPath = '/auth',
 }: UserMenuProps) {
   const { user, isAuthenticated, logout } = useAuth();

package/src/snippets/McpChat/README.md

@@ -0,0 +1,441 @@
+# MCP Chat - AI Assistant Integration
+
+AI-powered chat widget with global trigger system for seamless integration throughout your application.
+
+## Features
+
+- 🎯 **Global Trigger System** - Call chat from anywhere using `useMcpChat()` hook
+- 🤖 **Simple AI Button** - Universal `AskAIButton` component with AI assistant icon
+- 💬 **Multiple Display Modes** - Floating panel, sidebar, or closed
+- 🔄 **Streaming Responses** - Real-time AI responses
+- 📱 **Mobile Responsive** - Optimized for all devices
+- 🎭 **Context-Aware** - Send structured context with messages
+- 🔌 **Easy Integration** - Drop-in component with minimal setup
+
+## Quick Start
+
+### 1. Setup Provider (once in your app)
+
+```tsx
+// app/layout.tsx
+import { AIChatProvider, AIChatWidget } from '@djangocfg/layouts/snippets/McpChat';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <AIChatProvider>
+          {children}
+          <AIChatWidget />
+        </AIChatProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### 2. Use Anywhere
+
+#### Option A: Ready-to-use Button (Recommended)
+
+```tsx
+import { AskAIButton } from '@djangocfg/layouts/snippets/McpChat';
+
+// Simple usage
+<AskAIButton message="Explain this feature">
+  Ask AI
+</AskAIButton>
+
+// With context data
+<AskAIButton
+  message="Why is this failing?"
+  contextData={{ error: error.stack, component: 'UserForm' }}
+  source="ErrorBoundary"
+>
+  Explain error
+</AskAIButton>
+
+// Custom styling
+<AskAIButton
+  message="Help me optimize this"
+  contextData={{ topic: "database-performance" }}
+  variant="default"
+  size="lg"
+>
+  Get advice
+</AskAIButton>
+```
+
+#### Option B: Custom Hook
+
+```tsx
+import { useMcpChat } from '@djangocfg/layouts/snippets/McpChat';
+
+function MyComponent() {
+  const { sendToChat } = useMcpChat();
+
+  const handleClick = () => {
+    sendToChat({
+      message: 'Explain this error',
+      context: {
+        data: { error: errorDetails },
+        source: 'MyComponent'
+      }
+    });
+  };
+
+  return <button onClick={handleClick}>Ask AI</button>;
+}
+```
+
+## Components
+
+### AskAIButton
+
+Universal AI chat trigger button with Bot icon:
+
+```tsx
+<AskAIButton
+  message="Your question or prompt"
+  contextData={{ /* optional context */ }}
+  source="ComponentName"
+  variant="outline"
+  size="default"
+>
+  Button text
+</AskAIButton>
+```
+
+**Props:**
+- `message` - Question or prompt to send to AI (required)
+- `contextData` - Additional context object (optional)
+- `source` - Source component name for tracking (optional)
+- `autoSend` - Auto-send message after opening (default: `true`)
+- `showIcon` - Show Bot icon (default: `true`)
+- All standard Button props (`variant`, `size`, `className`, etc.)
+
+### useMcpChat Hook
+
+Custom hook for programmatic chat triggering:
+
+```tsx
+const { sendToChat, isChatAvailable } = useMcpChat();
+
+sendToChat({
+  message: 'Your message',
+  context: {
+    data: { /* contextual data */ },
+    source: 'ComponentName'
+  },
+  autoSend: true,
+  displayMode: 'floating' | 'sidebar'
+});
+```
+
+## Real-World Examples
+
+### Error Handling
+
+```tsx
+function ErrorBoundary({ error, children }) {
+  if (error) {
+    return (
+      <div>
+        <h2>Error: {error.message}</h2>
+        <AskAIButton
+          message="Explain this error and how to fix it"
+          contextData={{
+            error: error.message,
+            stack: error.stack,
+            component: 'UserForm'
+          }}
+          source="ErrorBoundary"
+        >
+          Explain error
+        </AskAIButton>
+      </div>
+    );
+  }
+  return children;
+}
+```
+
+### Feature Documentation
+
+```tsx
+function FeatureCard({ feature }) {
+  return (
+    <Card>
+      <CardHeader>{feature.name}</CardHeader>
+      <CardContent>{feature.description}</CardContent>
+      <CardFooter>
+        <AskAIButton
+          message={`Explain how ${feature.name} works`}
+          contextData={{
+            feature: feature.name,
+            version: feature.version
+          }}
+          source="FeatureCard"
+        >
+          Learn more
+        </AskAIButton>
+      </CardFooter>
+    </Card>
+  );
+}
+```
+
+### Settings Page
+
+```tsx
+function DatabaseSettings() {
+  return (
+    <div>
+      <h3>Database Configuration</h3>
+      <form>{/* form fields */}</form>
+      <AskAIButton
+        message="What are the best practices for PostgreSQL optimization?"
+        contextData={{
+          topic: "database-optimization",
+          dbType: "PostgreSQL"
+        }}
+        source="DatabaseSettings"
+      >
+        Get tips
+      </AskAIButton>
+    </div>
+  );
+}
+```
+
+### Pricing Comparison
+
+```tsx
+function PricingSection() {
+  return (
+    <div>
+      {/* pricing cards */}
+      <AskAIButton
+        message="Which package is right for my team?"
+        contextData={{
+          packages: ["starter", "professional", "enterprise"],
+          intent: "decision-making"
+        }}
+        source="PricingSection"
+      >
+        Which package?
+      </AskAIButton>
+    </div>
+  );
+}
+```
+
+### Installation Help
+
+```tsx
+function QuickStart() {
+  return (
+    <div>
+      <h2>Installation</h2>
+      <pre>{installCommands}</pre>
+      <AskAIButton
+        message="I need help with Django-CFG installation"
+        contextData={{
+          topic: "installation",
+          os: detectedOS
+        }}
+        source="QuickStart"
+      >
+        Installation help?
+      </AskAIButton>
+    </div>
+  );
+}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────┐
+│  Any Component                      │
+│  ┌──────────────────────────────┐  │
+│  │ AskAIButton / useMcpChat()   │  │
+│  │ sendToChat({ message, ... }) │  │
+│  └──────────────┬───────────────┘  │
+└─────────────────┼───────────────────┘
+                  │
+                  │ CustomEvent
+                  │ 'mcp:chat:send'
+                  ▼
+┌─────────────────────────────────────┐
+│  AIChatProvider (Event Listener)    │
+│  ┌──────────────────────────────┐  │
+│  │ 1. Receives event            │  │
+│  │ 2. Sends confirmation        │  │
+│  │ 3. Opens chat                │  │
+│  │ 4. Sends message to AI       │  │
+│  └──────────────────────────────┘  │
+└─────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│  AIChatWidget (UI)                  │
+│  - Floating panel or sidebar        │
+│  - Message display                  │
+│  - Streaming responses              │
+└─────────────────────────────────────┘
+```
+
+## API
+
+### AskAIButton Props
+
+```tsx
+interface AskAIButtonProps extends ButtonProps {
+  /** Message to send to AI */
+  message: string;
+  /** Additional context data */
+  contextData?: Record<string, any>;
+  /** Source component name */
+  source?: string;
+  /** Auto-send message (default: true) */
+  autoSend?: boolean;
+  /** Show icon (default: true) */
+  showIcon?: boolean;
+  /** Callback after sending */
+  onSent?: () => void;
+}
+```
+
+### McpChatEventDetail
+
+```tsx
+interface McpChatEventDetail {
+  message: string;
+  context?: {
+    data?: Record<string, any>;
+    source?: string;
+  };
+  autoSend?: boolean;
+  displayMode?: 'floating' | 'sidebar' | 'closed';
+}
+```
+
+### UseMcpChatReturn
+
+```tsx
+interface UseMcpChatReturn {
+  /** Send message to chat */
+  sendToChat: (detail: McpChatEventDetail) => void;
+  /** Check if chat is available */
+  isChatAvailable: () => boolean;
+}
+```
+
+## Best Practices
+
+1. **Always provide source** - Helps track where requests come from
+   ```tsx
+   <AskAIButton message="..." source="ComponentName">
+   ```
+
+2. **Include contextData** - More context = better AI responses
+   ```tsx
+   <AskAIButton
+     message="..."
+     contextData={{ feature: "auth", version: "2.0" }}
+   >
+   ```
+
+3. **Keep messages clear** - Write clear questions or prompts
+   ```tsx
+   // Good
+   message="Why is Django faster than FastAPI in enterprise scenarios?"
+
+   // Too vague
+   message="Explain this"
+   ```
+
+4. **Short button labels** - Keep button text concise (max 3 words)
+   ```tsx
+   <AskAIButton message="...">
+     Explain this  {/* Good */}
+   </AskAIButton>
+   ```
+
+5. **Check availability** - Use `isChatAvailable()` for conditional UI
+   ```tsx
+   const { isChatAvailable } = useMcpChat();
+   if (!isChatAvailable()) {
+     return <p>Chat loading...</p>;
+   }
+   ```
+
+## Error Handling
+
+If chat is not available:
+- Console error logged
+- Alert shown to user
+- Button automatically disabled
+
+```tsx
+const { sendToChat, isChatAvailable } = useMcpChat();
+
+if (!isChatAvailable()) {
+  console.log('Chat not loaded');
+}
+```
+
+## TypeScript Support
+
+Fully typed with TypeScript for excellent IDE support:
+
+```tsx
+import type {
+  McpChatEventDetail,
+  UseMcpChatReturn,
+  AskAIButtonProps
+} from '@djangocfg/layouts/snippets/McpChat';
+```
+
+## Common Use Cases
+
+### Documentation Pages
+```tsx
+<AskAIButton message="How do I set this up?">
+  Setup help?
+</AskAIButton>
+```
+
+### Comparison Tables
+```tsx
+<AskAIButton message="Why is option A better than option B?">
+  Explain difference
+</AskAIButton>
+```
+
+### Feature Sections
+```tsx
+<AskAIButton message="Which features should I explore first?">
+  Explore features?
+</AskAIButton>
+```
+
+### Benchmarks
+```tsx
+<AskAIButton message="Why is this faster in production?">
+  Explain benchmarks?
+</AskAIButton>
+```
+
+## Contributing
+
+When adding new features:
+1. Update type definitions in `types.ts`
+2. Add examples to this README
+3. Test with different scenarios
+4. Keep the API simple and consistent
+
+## License
+
+MIT - Part of DjangoCFG project

package/src/snippets/McpChat/components/AskAIButton.tsx

@@ -0,0 +1,92 @@
+'use client';
+
+import { Button, type ButtonProps } from '@djangocfg/ui-nextjs';
+import { Bot } from 'lucide-react';
+import { useMcpChat } from '../hooks/useMcpChat';
+import type { McpChatEventDetail } from '../types';
+
+export interface AskAIButtonProps extends Omit<ButtonProps, 'onClick'> {
+  /** Message to send to AI */
+  message: string;
+  /** Additional context data */
+  contextData?: Record<string, any>;
+  /** Source component name */
+  source?: string;
+  /** Auto-send message (default: true) */
+  autoSend?: boolean;
+  /** Show icon (default: true) */
+  showIcon?: boolean;
+  /** Callback after sending */
+  onSent?: () => void;
+}
+
+/**
+ * Universal AI chat trigger button
+ *
+ * @example Basic usage
+ * ```tsx
+ * <AskAIButton message="Explain this feature">
+ *   Explain this
+ * </AskAIButton>
+ * ```
+ *
+ * @example With context
+ * ```tsx
+ * <AskAIButton
+ *   message="Why is this failing?"
+ *   contextData={{ error: error.stack }}
+ *   source="ErrorBoundary"
+ * >
+ *   Ask AI
+ * </AskAIButton>
+ * ```
+ */
+export function AskAIButton({
+  message,
+  contextData,
+  source,
+  autoSend = true,
+  showIcon = true,
+  onSent,
+  children = 'Ask AI',
+  variant = 'outline',
+  size = 'default',
+  className,
+  ...buttonProps
+}: AskAIButtonProps) {
+  const { sendToChat, isChatAvailable } = useMcpChat();
+
+  const handleClick = () => {
+    const detail: McpChatEventDetail = {
+      message,
+      autoSend,
+    };
+
+    if (contextData || source) {
+      detail.context = {
+        data: contextData,
+        source,
+      };
+    }
+
+    sendToChat(detail);
+    onSent?.();
+  };
+
+  const isAvailable = isChatAvailable();
+
+  return (
+    <Button
+      onClick={handleClick}
+      variant={variant}
+      size={size}
+      className={className}
+      disabled={!isAvailable}
+      title={!isAvailable ? 'AI Chat not available' : undefined}
+      {...buttonProps}
+    >
+      {showIcon && <Bot className="h-4 w-4 mr-2" />}
+      {children}
+    </Button>
+  );
+}

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

@@ -19,3 +19,6 @@ export type { AIMessageInputProps } from './MessageInput';
 
 export { ChatSidebar } from './ChatSidebar';
 export type { ChatSidebarProps } from './ChatSidebar';
+
+export { AskAIButton } from './AskAIButton';
+export type { AskAIButtonProps } from './AskAIButton';

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

@@ -1,6 +1,6 @@
 'use client';
 
-import React, { createContext, useContext, useState, useCallback, useMemo, useEffect, type ReactNode } from 'react';
+import { createContext, useContext, useState, useCallback, useMemo, useEffect, type ReactNode } from 'react';
 import { useLocalStorage, useIsMobile } from '@djangocfg/ui-nextjs/hooks';
 import { useAIChat } from '../hooks/useAIChat';
 import { mcpEndpoints, type AIChatMessage, type ChatWidgetConfig, type ChatDisplayMode } from '../types';
@@ -223,6 +223,67 @@ export function AIChatProvider({
     ]
   );
 
+  // =============================================================================
+  // Global Chat Event Listener
+  // =============================================================================
+
+  /**
+   * Listen for mcp:chat:send events from useMcpChat hook
+   * This allows any component to trigger chat from anywhere in the app
+   */
+  useEffect(() => {
+    // Register chat as available
+    if (typeof window !== 'undefined') {
+      (window as any).__MCP_CHAT_AVAILABLE__ = true;
+    }
+
+    const handleChatEvent = (event: Event) => {
+      const customEvent = event as CustomEvent<import('../types').McpChatEventDetail>;
+      const { message, context, autoSend = true, displayMode: requestedMode } = customEvent.detail;
+
+      // Send confirmation that event was handled
+      window.dispatchEvent(new CustomEvent('mcp:chat:handled'));
+
+      // Format message with context if provided
+      let fullMessage = message;
+      if (context) {
+        if (context.type) {
+          fullMessage = `[${context.type.toUpperCase()}] ${message}`;
+        }
+        if (context.data) {
+          fullMessage += `\n\n**Context:**\n\`\`\`json\n${JSON.stringify(context.data, null, 2)}\n\`\`\``;
+        }
+        if (context.source) {
+          fullMessage += `\n\n_Source: ${context.source}_`;
+        }
+      }
+
+      // Open chat in requested mode (or default to floating)
+      if (requestedMode) {
+        setDisplayMode(requestedMode);
+      } else {
+        openChat();
+      }
+
+      // Auto-send message if requested
+      if (autoSend) {
+        // Small delay to ensure chat is open and ready
+        setTimeout(() => {
+          sendMessage(fullMessage);
+        }, 100);
+      }
+    };
+
+    window.addEventListener('mcp:chat:send', handleChatEvent);
+
+    return () => {
+      window.removeEventListener('mcp:chat:send', handleChatEvent);
+      if (typeof window !== 'undefined') {
+        (window as any).__MCP_CHAT_AVAILABLE__ = false;
+      }
+    };
+  }, [sendMessage, openChat, setDisplayMode]);
+
   return <AIChatContext.Provider value={value}>{children}</AIChatContext.Provider>;
 }
 

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

@@ -2,4 +2,5 @@
 
 export { useAIChat } from './useAIChat';
 export { useChatLayout } from './useChatLayout';
+export { useMcpChat } from './useMcpChat';
 export type { ChatLayoutConfig, UseChatLayoutReturn } from './useChatLayout';

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

@@ -0,0 +1,89 @@
+'use client';
+
+import { useCallback } from 'react';
+import type { McpChatEventDetail, UseMcpChatReturn } from '../types';
+
+/**
+ * Hook to send messages to MCP Chat from anywhere in the app
+ *
+ * @example
+ * ```tsx
+ * function ErrorBoundary({ error }) {
+ *   const { sendToChat } = useMcpChat();
+ *
+ *   const explainError = () => {
+ *     sendToChat({
+ *       message: `Explain this error: ${error.message}`,
+ *       context: {
+ *         type: 'error',
+ *         data: { error: error.stack },
+ *         source: 'ErrorBoundary'
+ *       }
+ *     });
+ *   };
+ *
+ *   return <button onClick={explainError}>Explain Error</button>;
+ * }
+ * ```
+ */
+export function useMcpChat(): UseMcpChatReturn {
+  /**
+   * Send message to chat via CustomEvent
+   */
+  const sendToChat = useCallback((detail: McpChatEventDetail) => {
+    if (typeof window === 'undefined') {
+      console.error('[useMcpChat] Cannot send message: window is not available');
+      return;
+    }
+
+    // Create custom event
+    const event = new CustomEvent('mcp:chat:send', {
+      detail,
+      bubbles: true,
+    });
+
+    // Set up handler confirmation listener
+    let handled = false;
+    const handleConfirmation = () => {
+      handled = true;
+    };
+
+    window.addEventListener('mcp:chat:handled', handleConfirmation, { once: true });
+
+    // Dispatch event
+    window.dispatchEvent(event);
+
+    // Check if event was handled
+    setTimeout(() => {
+      window.removeEventListener('mcp:chat:handled', handleConfirmation);
+
+      if (!handled) {
+        const errorMessage = 'AI Chat is not available. Please make sure the chat component is loaded.';
+        console.error('[useMcpChat]', errorMessage);
+
+        // Import consola dynamically if available
+        if (typeof window !== 'undefined' && (window as any).consola) {
+          (window as any).consola.error('[useMcpChat] Chat not available');
+        }
+
+        // Show user-friendly alert
+        alert(errorMessage);
+      }
+    }, 100);
+  }, []);
+
+  /**
+   * Check if chat is available
+   */
+  const isChatAvailable = useCallback(() => {
+    if (typeof window === 'undefined') return false;
+
+    // Check if chat registered itself
+    return (window as any).__MCP_CHAT_AVAILABLE__ === true;
+  }, []);
+
+  return {
+    sendToChat,
+    isChatAvailable,
+  };
+}

package/src/snippets/McpChat/index.ts

@@ -42,12 +42,13 @@
  */
 
 // Components
-export { ChatWidget, AIChatWidget, ChatPanel, MessageBubble, AIMessageInput } from './components';
+export { ChatWidget, AIChatWidget, ChatPanel, MessageBubble, AIMessageInput, AskAIButton } from './components';
 export type {
   ChatWidgetProps,
   AIChatWidgetProps,
   MessageBubbleProps,
   AIMessageInputProps,
+  AskAIButtonProps,
 } from './components';
 
 // Context
@@ -60,7 +61,7 @@ export type {
 } from './context';
 
 // Hooks
-export { useAIChat, useChatLayout } from './hooks';
+export { useAIChat, useChatLayout, useMcpChat } from './hooks';
 export type { ChatLayoutConfig, UseChatLayoutReturn } from './hooks';
 
 // Types
@@ -72,4 +73,7 @@ export type {
   UseAIChatOptions,
   UseAIChatReturn,
   ChatWidgetConfig,
+  McpChatContextType,
+  McpChatEventDetail,
+  UseMcpChatReturn,
 } from './types';

package/src/snippets/McpChat/types.ts

@@ -141,3 +141,49 @@ export interface UseAIChatReturn {
   clearMessages: () => void;
   stopStreaming: () => void;
 }
+
+// =============================================================================
+// MCP Chat Events (Global Chat Trigger)
+// =============================================================================
+
+/**
+ * Context type for chat messages triggered from different parts of the app
+ */
+export type McpChatContextType =
+  | 'error'      // Error explanation
+  | 'question'   // General question
+  | 'explain'    // Explain something
+  | 'advice'     // Get advice
+  | 'help'       // Help request
+  | 'custom';    // Custom context
+
+/**
+ * Event detail for mcp:chat:send custom event
+ */
+export interface McpChatEventDetail {
+  /** Message to send to chat */
+  message: string;
+  /** Optional context about the message */
+  context?: {
+    /** Type of context */
+    type?: McpChatContextType;
+    /** Additional data (error object, selected element, etc.) */
+    data?: Record<string, any>;
+    /** Source component/page that triggered the event */
+    source?: string;
+  };
+  /** Auto-send message after opening chat (default: true) */
+  autoSend?: boolean;
+  /** Open chat in specific mode (default: 'floating') */
+  displayMode?: ChatDisplayMode;
+}
+
+/**
+ * useMcpChat hook return type
+ */
+export interface UseMcpChatReturn {
+  /** Send message to chat from anywhere in the app */
+  sendToChat: (detail: McpChatEventDetail) => void;
+  /** Check if chat is available */
+  isChatAvailable: () => boolean;
+}

package/src/snippets/index.ts

@@ -18,6 +18,8 @@ export {
   useAIChatContextOptional,
   useAIChat,
   useChatLayout,
+  useMcpChat,
+  AskAIButton,
 } from './McpChat';
 export type {
   AIChatWidgetProps,
@@ -36,4 +38,8 @@ export type {
   UseAIChatOptions,
   UseAIChatReturn,
   ChatWidgetConfig,
+  McpChatContextType,
+  McpChatEventDetail,
+  UseMcpChatReturn,
+  AskAIButtonProps,
 } from './McpChat';