react-docs-module 0.1.0

package/README.md

@@ -0,0 +1,279 @@
+# React Docs Module
+
+A powerful, embeddable documentation system with built-in search and AI chat capabilities. Perfect for creating beautiful, interactive documentation pages with minimal setup.
+
+## Features
+
+- 🎨 **Themeable** - Customize colors and appearance via `docs.json` configuration
+- 🔍 **Full-text Search** - Fast, client-side search with caching
+- 🤖 **AI Chat** - Integrated AI assistant for documentation Q&A
+- 📱 **Responsive** - Mobile-friendly design with adaptive layouts
+- ⚡ **Fast** - Built with Next.js and optimized for performance
+- 🎯 **TypeScript** - Full type safety and excellent DX
+- 📝 **MDX Support** - Rich content with React components
+- 📋 **Mintlify Compatible** - Full support for Mintlify docs.json schema
+
+## Quick Start
+
+### 1. Installation
+
+```bash
+npm install react-docs-module
+```
+
+### 2. Configuration
+
+Create a `docs.json` file with your documentation configuration using the **Mintlify schema**:
+
+```json
+{
+  "$schema": "https://leaves.mintlify.com/schema/docs.json",
+  "theme": "mint",  
+  "name": "My Documentation",
+  "description": "Comprehensive documentation for my project",
+  "logo": {
+    "dark": "/assets/logo-dark.png",
+    "light": "/assets/logo-light.png"
+  },
+  "favicon": "/assets/favicon.png",
+  "colors": {
+    "primary": "#3B82F6",
+    "light": "#60A5FA", 
+    "dark": "#1D4ED8"
+  },
+  "navbar": {
+    "cta": {
+      "type": "github",
+      "url": "https://github.com/your-org/your-repo"
+    }
+  },
+  "navigation": {
+    "groups": [
+      {
+        "group": "Getting Started",
+        "pages": [
+          "introduction",
+          "installation", 
+          "quick-start"
+        ]
+      },
+      {
+        "group": "API Reference",
+        "pages": [
+          "api/overview",
+          "api/authentication"
+        ]
+      }
+    ]
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/your-org/your-repo",
+      "twitter": "https://twitter.com/your-handle"
+    }
+  },
+  "feedback": {
+    "thumbsRating": true
+  }
+}
+```
+
+### 3. Basic Usage
+
+```tsx
+import { DocumentationLayout, createReactDocsConfig } from 'react-docs-module';
+
+// Create config with defaults or custom overrides
+const config = createReactDocsConfig({
+  basePath: "/docs",
+  contentPath: "content/docs",
+  // searchApiPath and aiChatApiPath use defaults
+});
+
+export default function DocsPage() {
+  return (
+    <DocumentationLayout
+      config={config}
+      navigation={navigation}
+      currentPath="/docs/introduction"
+      headings={headings}
+    >
+      <div>Your documentation content here</div>
+    </DocumentationLayout>
+  );
+}
+```
+
+## Configuration
+
+### ReactDocsConfig
+
+```typescript
+interface ReactDocsConfig {
+  basePath: string;        // Base URL path for docs
+  contentPath: string;     // Path to MDX content files
+  searchApiPath: string;   // API endpoint for search index
+  aiChatApiPath: string;   // API endpoint for AI chat
+}
+
+// Factory function with optional overrides
+function createReactDocsConfig(options?: ReactDocsConfigOptions): ReactDocsConfig
+
+interface ReactDocsConfigOptions {
+  basePath?: string;       // Default: "/docs"
+  contentPath?: string;    // Default: "content/docs"
+  searchApiPath?: string;  // Default: "/api/docs/search-index"
+  aiChatApiPath?: string;  // Default: "/api/docs/chat"
+}
+```
+
+### Configuration Examples
+
+```typescript
+// Use all defaults
+const config = createReactDocsConfig();
+
+// Override specific fields
+const config = createReactDocsConfig({
+  basePath: "/documentation",
+  aiChatApiPath: "/api/custom-chat"
+});
+
+// Override all fields
+const config = createReactDocsConfig({
+  basePath: "/my-docs",
+  contentPath: "docs",
+  searchApiPath: "/api/search",
+  aiChatApiPath: "/api/ai-chat"
+});
+```
+
+### docs.json Schema (Mintlify Compatible)
+
+The `docs.json` file uses the complete **[Mintlify schema](https://leaves.mintlify.com/schema/docs.json)** for full compatibility:
+
+- **Required**: `theme`, `name`, `colors.primary`, `navigation`
+- **Optional**: `description`, `logo`, `favicon`, `navbar`, `footer`, `feedback`, and more
+- **Migration**: Existing Mintlify projects can use their `mint.json` structure in `docs.json`
+
+## Components
+
+### Core Components
+
+- `DocumentationLayout` - Main layout wrapper with sidebar and TOC
+- `Search` - Search component with AI chat integration
+- `DocsIndex` - Documentation index/landing page
+- `DocsSidebar` - Navigation sidebar
+- `TableOfContents` - Page table of contents
+- `DocPagination` - Previous/next page navigation
+
+### Theme System
+
+```tsx
+import { DocsThemeProvider, useDocsColors } from 'react-docs-module';
+
+function CustomComponent() {
+  const colors = useDocsColors();
+  
+  return (
+    <div style={{ color: colors.primary }}>
+      Themed content
+    </div>
+  );
+}
+```
+
+### AI Chat Integration
+
+```tsx
+import { streamDocsChatResponse } from 'react-docs-module/chat-api';
+
+// API route example
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  
+  return streamDocsChatResponse(
+    config,
+    messages,
+    "You are a helpful documentation assistant.",
+    async (result) => {
+      // Handle completion
+      console.log(result.text);
+    }
+  );
+}
+```
+
+## API Reference
+
+### Functions
+
+- `getDocsSidebar(config)` - Generate sidebar navigation from docs.json
+- `getAllDocs(config)` - Get all documentation files metadata  
+- `getAllDocsContent(config)` - Get all documentation content (cached)
+- `getDocBySlug(config, slug)` - Get specific document by slug
+- `buildSearchIndex(config)` - Build search index from content
+- `streamDocsChatResponse(...)` - Stream AI chat responses
+
+### Types
+
+- `ReactDocsConfig` - Main configuration interface
+- `ReactDocsConfigOptions` - Configuration factory options
+- `DocsJsonConfig` - docs.json configuration schema (Mintlify compatible)
+- `ThemeColors` - Color theme interface
+- `ModelProvider` - AI model provider configuration
+
+## Advanced Usage
+
+### Custom Search API
+
+```typescript
+// pages/api/search-index.ts
+import { buildSearchIndex, createReactDocsConfig } from 'react-docs-module';
+
+const DOCS_CONFIG = createReactDocsConfig({
+  contentPath: "content/docs"
+});
+
+export default async function handler(req, res) {
+  const searchIndex = await buildSearchIndex(DOCS_CONFIG);
+  res.json(searchIndex);
+}
+```
+
+### Custom AI Models
+
+```typescript
+const modelProvider: ModelProvider = {
+  providerType: 'anthropic',
+  model: 'claude-3-sonnet',
+  apiKey: process.env.ANTHROPIC_API_KEY
+};
+
+streamDocsChatResponse(config, messages, prompt, callback, modelProvider);
+```
+
+### Custom Theming
+
+```css
+/* Use CSS custom properties set by DocsThemeProvider */
+.custom-element {
+  color: var(--docs-primary);
+  border-color: var(--docs-primary-light);
+  background-color: var(--docs-primary-dark);
+}
+```
+
+## Requirements
+
+- React 19+
+- TypeScript 5.6+
+- Node.js 18+
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please read our contributing guidelines and submit pull requests to the main repository.

package/ai-chat.tsx

@@ -0,0 +1,222 @@
+"use client";
+import React, { useEffect, useRef, useCallback } from "react";
+import { Button } from "./ui/button";
+import { Input } from "./ui/input";
+import { useChat } from 'ai/react';
+import ReactMarkdown from 'react-markdown';
+import { CodeBlock } from "./mdx/code-block";
+import { ReactDocsConfig } from "./config";
+import { useDocsColors } from "./theme-context";
+
+interface Message {
+  role: 'user' | 'assistant' | 'system' | 'data';
+  content: string;
+  id?: string;
+}
+
+const MemoizedMarkdown = React.memo(({ content }: { content: string }) => (
+  <ReactMarkdown
+    className="w-full [&_pre]:max-w-full [&_pre]:overflow-x-auto [&_p]:leading-relaxed"
+    components={{
+      code({ node, className, children, ...props }) {
+        const match = /language-(\w+)/.exec(className || '');
+        if (match) {
+          const codeContent = Array.isArray(children)
+            ? children.join('')
+            : String(children);
+
+          return (
+            <div className="max-w-full overflow-auto">
+              <CodeBlock
+                {...props}
+                className={className}
+              >
+                {codeContent}
+              </CodeBlock>
+            </div>
+          );
+        }
+        return (
+          <code {...props} className="bg-gray-800/50 px-1.5 py-0.5 rounded text-sm font-mono">
+            {children}
+          </code>
+        );
+      },
+    }}
+  >
+    {content}
+  </ReactMarkdown>
+));
+
+MemoizedMarkdown.displayName = 'MemoizedMarkdown';
+
+const Message = React.memo(({ message }: { message: Message }) => (
+  <div className="rounded-lg bg-gray-800/50 p-4">
+    <div className="flex gap-3 items-start">
+      <div className={`p-2 rounded-md ${message.role === 'assistant'
+        ? 'bg-blue-500/10 text-blue-400'
+        : 'bg-gray-700/50 text-gray-400'
+        } mt-0.5`}>
+        {message.role === 'assistant' ? (
+          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+            <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+          </svg>
+        ) : (
+          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+            <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2" />
+            <circle cx="12" cy="7" r="4" />
+          </svg>
+        )}
+      </div>
+      <div className="flex-1 space-y-2 min-w-0">
+        <div className="text-sm text-white leading-relaxed">
+          <MemoizedMarkdown content={message.content} />
+        </div>
+      </div>
+    </div>
+  </div>
+));
+
+Message.displayName = 'Message';
+
+export const AIChatOption = React.memo(({ query, onClick }: { query: string; onClick: () => void }) => {
+  const colors = useDocsColors();
+  
+  return (
+    <button
+      className="block w-full text-left p-4 rounded-lg hover:bg-gray-800/50 transition-colors border border-gray-800"
+      onClick={onClick}
+    >
+      <div className="flex items-center gap-3">
+        <div 
+          className="p-2 rounded-md"
+          style={{
+            backgroundColor: `${colors.primary}10`,
+            color: colors.primary,
+          }}
+        >
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+            <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+          </svg>
+        </div>
+        <div>
+          <h3 className="text-sm font-medium text-white mb-1">Ask AI (Experimental)</h3>
+          <p className="text-sm text-gray-400">&quot;{query}&quot;</p>
+        </div>
+      </div>
+    </button>
+  );
+});
+
+AIChatOption.displayName = 'AIChatOption';
+
+export function AIChat({ query, onBack, config }: { query: string; onBack: () => void; config: ReactDocsConfig }) {
+  const colors = useDocsColors();
+  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat({
+    initialMessages: [],
+    api: config.aiChatApiPath,
+    id: query,
+    initialInput: query,
+  });
+
+  const messagesEndRef = useRef<HTMLDivElement>(null);
+  const hasSubmittedInitialMessage = useRef(false);
+
+  const scrollToBottom = useCallback(() => {
+    if (messagesEndRef.current) {
+      const behavior = messages.length <= 2 ? "auto" : "smooth";
+      messagesEndRef.current.scrollIntoView({ behavior });
+    }
+  }, [messages.length]);
+
+  useEffect(() => {
+    scrollToBottom();
+  }, [scrollToBottom]);
+
+  useEffect(() => {
+    if (!hasSubmittedInitialMessage.current) {
+      const event = new Event('submit');
+      Object.defineProperty(event, 'target', { value: { value: query } });
+      handleSubmit(event as any);
+      hasSubmittedInitialMessage.current = true;
+    }
+  }, [query, handleSubmit]);
+
+  useEffect(() => {
+    if (error) {
+      console.error('Chat API Error:', error);
+    }
+  }, [error]);
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center gap-2">
+        <button
+          onClick={onBack}
+          className="p-1 hover:bg-gray-800 rounded-md text-gray-400 hover:text-white transition-colors"
+        >
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+            <path d="M19 12H5M12 19l-7-7 7-7" />
+          </svg>
+        </button>
+        <h3 className="text-sm font-medium text-white">Ask AI (Experimental)</h3>
+      </div>
+
+      <div className="space-y-4 max-h-[50vh] overflow-y-auto">
+        {error && (
+          <div className="rounded-lg bg-red-900/50 border border-red-900 p-4">
+            <div className="text-sm text-red-400">
+              Error: Failed to send message. Please try again.
+            </div>
+          </div>
+        )}
+        {messages.map((message) => (
+          <Message key={message.id} message={message} />
+        ))}
+        {isLoading && (
+          <div className="rounded-lg bg-gray-800/50 p-4">
+            <div className="flex gap-3 items-start">
+              <div className="p-2 rounded-md bg-blue-500/10 text-blue-400 mt-0.5">
+                <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                  <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+                </svg>
+              </div>
+              <div className="flex-1">
+                <div className="flex items-center gap-2 text-sm text-white">
+                  <div className="animate-pulse">Thinking</div>
+                  <div className="flex gap-1">
+                    <span className="animate-bounce">.</span>
+                    <span className="animate-bounce" style={{ animationDelay: "0.2s" }}>.</span>
+                    <span className="animate-bounce" style={{ animationDelay: "0.4s" }}>.</span>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        )}
+        <div ref={messagesEndRef} />
+      </div>
+
+      <form onSubmit={handleSubmit} className="relative mt-4">
+        <Input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Ask a follow-up question..."
+          className="w-full bg-gray-800/50 border-gray-700"
+          disabled={isLoading}
+        />
+        <Button
+          type="submit"
+          disabled={isLoading || !input.trim()}
+          className="absolute right-1 top-1 h-8"
+          style={{
+            backgroundColor: colors.primary,
+            '--tw-bg-opacity': '1',
+          } as React.CSSProperties}
+        >
+          Send
+        </Button>
+      </form>
+    </div>
+  );
+}

package/chat-api.ts

@@ -0,0 +1,90 @@
+import { createGroq } from '@ai-sdk/groq';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createOpenAI } from '@ai-sdk/openai';
+import { streamText } from 'ai';
+import { getAllDocsContent } from './mdx';
+import { ReactDocsConfig } from './config';
+
+export interface ModelProvider {
+  providerType: 'groq' | 'anthropic' | 'openai';
+  model?: string;
+  baseURL?: string;
+  apiKey?: string;
+}
+
+export interface Message {
+  role: 'user' | 'assistant' | 'system' | 'data';
+  content: string;
+}
+
+export interface FinishResult {
+  text: string;
+}
+
+export async function streamDocsChatResponse(
+  config: ReactDocsConfig,
+  messages: Message[],
+  systemPrompt?: string,
+  onFinishCallback?: (result: FinishResult) => Promise<void>,
+  modelProvider?: ModelProvider
+) {
+  // Default to groq if no provider specified
+  const provider = modelProvider || {
+    providerType: 'groq',
+    model: 'llama-3.3-70b-versatile'
+  };
+
+  // Create the appropriate model based on provider type
+  let model;
+  switch (provider.providerType) {
+    case 'anthropic':
+      const anthropicProvider = createAnthropic({
+        baseURL: provider.baseURL,
+        apiKey: provider.apiKey,
+      });
+      model = anthropicProvider(provider.model || 'claude-3-5-sonnet-20241022');
+      break;
+    case 'openai':
+      const openaiProvider = createOpenAI({
+        baseURL: provider.baseURL,
+        apiKey: provider.apiKey,
+      });
+      model = openaiProvider(provider.model || 'gpt-4o');
+      break;
+    case 'groq':
+    default:
+      const groqProvider = createGroq({
+        baseURL: provider.baseURL,
+        apiKey: provider.apiKey,
+      });
+      model = groqProvider(provider.model || 'llama-3.3-70b-versatile');
+      break;
+  }
+
+  const docsSystemPrompt = systemPrompt || `You are a helpful assistant for the provided documentation knowledge base.
+Based on user questions you should be able to help them by providing answers based on the knowledge base only.
+Keep your responses concise and focused.`;
+
+  const docsContent = getAllDocsContent(config);
+
+  const stream = streamText({
+    // Type assertion needed due to AI SDK version compatibility between LanguageModelV1/V2
+    model: model as Parameters<typeof streamText>[0]['model'],
+    onFinish: async (result) => {
+      if (onFinishCallback) {
+        await onFinishCallback({ text: result.text });
+      }
+    },
+    messages: [
+      {
+        role: 'system',
+        content: `${docsSystemPrompt}
+Documentation Knowledge Base:
+${docsContent}`,
+      },
+      ...messages,
+    ],
+  });
+
+  return stream.toDataStreamResponse();
+}

package/cn.ts

@@ -0,0 +1,15 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+
+export function slugify(str: string) {
+  return String(str)
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}

package/config.ts

@@ -0,0 +1,29 @@
+export interface ReactDocsConfig {
+  basePath: string;
+  contentPath: string;
+  searchApiPath: string;
+  aiChatApiPath: string;
+}
+
+export interface ReactDocsConfigOptions {
+  basePath?: string;
+  contentPath?: string;
+  searchApiPath?: string;
+  aiChatApiPath?: string;
+}
+
+const DEFAULT_CONFIG: ReactDocsConfig = {
+  basePath: "/docs",
+  contentPath: "content/docs",
+  searchApiPath: "/api/docs/search-index",
+  aiChatApiPath: "/api/docs/chat",
+};
+
+export function createReactDocsConfig(options: ReactDocsConfigOptions = {}): ReactDocsConfig {
+  return {
+    basePath: options.basePath ?? DEFAULT_CONFIG.basePath,
+    contentPath: options.contentPath ?? DEFAULT_CONFIG.contentPath,
+    searchApiPath: options.searchApiPath ?? DEFAULT_CONFIG.searchApiPath,
+    aiChatApiPath: options.aiChatApiPath ?? DEFAULT_CONFIG.aiChatApiPath,
+  };
+}

package/dist/ai-chat.d.ts

@@ -0,0 +1,12 @@
+import React from "react";
+import { ReactDocsConfig } from "./config";
+export declare const AIChatOption: React.MemoExoticComponent<({ query, onClick }: {
+    query: string;
+    onClick: () => void;
+}) => import("react/jsx-runtime").JSX.Element>;
+export declare function AIChat({ query, onBack, config }: {
+    query: string;
+    onBack: () => void;
+    config: ReactDocsConfig;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ai-chat.d.ts.map