@brainfish-ai/devdoc 0.1.25 → 0.1.27

package/renderer/components/docs-viewer/content/not-found-page.tsx

@@ -0,0 +1,330 @@
+'use client'
+
+import { useEffect, useState, useCallback, useRef } from 'react'
+import { FileX, House, ArrowLeft, MagnifyingGlass, Spinner } from '@phosphor-icons/react'
+import { Button } from '@/components/ui/button'
+import { useDocsNavigation } from '@/lib/docs-navigation-context'
+import { MDXRemote, MDXRemoteSerializeResult } from 'next-mdx-remote'
+import { useCodeCopy } from '@/hooks/use-code-copy'
+
+// Import MDX components for custom 404 pages
+import {
+  Note,
+  Warning,
+  Info,
+  Tip,
+  Check,
+  Error as ErrorCallout,
+  Callout,
+  Card,
+  CardGroup,
+  Accordion,
+  AccordionGroup,
+  Steps,
+  Step,
+  Tabs,
+  Tab,
+  CodeGroup,
+  Frame,
+  Columns,
+  Snippet,
+  Latex,
+  ParamField,
+  ResponseField,
+  Expandable,
+  Iframe,
+  Video,
+  Loom,
+  Image,
+  Screenshot,
+  Logo,
+  Icon,
+  Highlight,
+  Marker,
+  Underline,
+  Badge,
+  Mermaid,
+  PDF,
+  Audio,
+  Download,
+  Hero,
+  Pre,
+  Tagline,
+  Headline,
+  Description,
+  CommandBox,
+  Section,
+  Center,
+  FeatureGrid,
+  FeatureItem,
+  ButtonLink,
+  Spacer,
+  Divider,
+} from '../../docs/mdx/index'
+
+// MDX components mapping for custom 404 pages
+const mdxComponents = {
+  Note,
+  Warning,
+  Info,
+  Tip,
+  Check,
+  Error: ErrorCallout,
+  Callout,
+  Card,
+  CardGroup,
+  Accordion,
+  AccordionGroup,
+  Steps,
+  Step,
+  Tabs,
+  Tab,
+  CodeGroup,
+  Frame,
+  Columns,
+  Snippet,
+  Latex,
+  ParamField,
+  ResponseField,
+  Expandable,
+  Iframe,
+  Video,
+  Loom,
+  Image,
+  Screenshot,
+  Logo,
+  Icon,
+  Highlight,
+  Marker,
+  Underline,
+  Badge,
+  Mermaid,
+  PDF,
+  Audio,
+  Download,
+  Hero,
+  Pre,
+  Tagline,
+  Headline,
+  Description,
+  CommandBox,
+  Section,
+  Center,
+  FeatureGrid,
+  FeatureItem,
+  ButtonLink,
+  Spacer,
+  Divider,
+}
+
+interface NotFoundPageProps {
+  slug?: string
+  onGoBack?: () => void
+  onSearch?: () => void
+}
+
+interface Custom404Data {
+  frontmatter: {
+    title?: string
+    description?: string
+    mode?: 'default' | 'wide' | 'custom'
+    hideHeader?: boolean
+    background?: string
+  }
+  mdxSource: MDXRemoteSerializeResult
+}
+
+export function NotFoundPage({ slug, onGoBack, onSearch }: NotFoundPageProps) {
+  const docsNav = useDocsNavigation()
+  const [customPage, setCustomPage] = useState<Custom404Data | null>(null)
+  const [loading, setLoading] = useState(true)
+  const contentRef = useRef<HTMLDivElement>(null)
+  
+  // Add copy buttons to code blocks after content loads
+  useCodeCopy(contentRef, [customPage])
+  
+  // Try to load custom 404.mdx page
+  useEffect(() => {
+    async function loadCustom404() {
+      try {
+        const response = await fetch('/api/docs?slug=404&is404=true')
+        if (response.ok) {
+          const data = await response.json()
+          setCustomPage(data)
+        }
+      } catch {
+        // No custom 404 page, use default
+      } finally {
+        setLoading(false)
+      }
+    }
+    loadCustom404()
+  }, [])
+  
+  const handleGoHome = useCallback(() => {
+    // Navigate to the first page of the current tab or just switch to first tab
+    if (docsNav?.switchToTab) {
+      window.location.hash = ''
+      window.location.reload()
+    } else {
+      window.location.hash = ''
+    }
+  }, [docsNav])
+  
+  const handleGoBack = useCallback(() => {
+    if (onGoBack) {
+      onGoBack()
+    } else {
+      window.history.back()
+    }
+  }, [onGoBack])
+  
+  // Show loading state briefly while checking for custom 404
+  if (loading) {
+    return (
+      <div className="docs-page docs-page-not-found w-full min-h-[200px]">
+        <div className="flex items-center justify-center py-12">
+          <Spinner className="h-6 w-6 animate-spin text-muted-foreground" />
+        </div>
+      </div>
+    )
+  }
+  
+  // Render custom 404 page if available
+  if (customPage) {
+    const { mode = 'default', hideHeader, background } = customPage.frontmatter
+    const isCustomMode = mode === 'custom'
+    const showHeader = !hideHeader && !isCustomMode
+    
+    // Custom mode: Full-width layout
+    if (isCustomMode) {
+      return (
+        <div 
+          ref={contentRef}
+          className="docs-page docs-page-not-found docs-content w-full min-h-full"
+          style={{ background: background || 'var(--background)' }}
+        >
+          <div className="docs-custom-content [&>*]:w-full">
+            <MDXRemote {...customPage.mdxSource} components={mdxComponents} />
+          </div>
+        </div>
+      )
+    }
+    
+    // Default mode with optional header
+    const containerClass = mode === 'wide' ? 'max-w-6xl' : 'max-w-4xl'
+    
+    return (
+      <div ref={contentRef} className={`docs-page docs-page-not-found docs-content ${containerClass} mx-auto px-4 py-6 sm:px-8 sm:py-8`}>
+        {showHeader && customPage.frontmatter.title && (
+          <div className="docs-page-header mb-6">
+            <h1 className="docs-content-title text-2xl sm:text-3xl font-bold mb-2 text-foreground">
+              {customPage.frontmatter.title}
+            </h1>
+            {customPage.frontmatter.description && (
+              <p className="docs-content-description text-lg text-muted-foreground">
+                {customPage.frontmatter.description}
+              </p>
+            )}
+          </div>
+        )}
+        <div className="docs-prose prose prose-sm max-w-none prose-headings:text-foreground prose-p:text-muted-foreground prose-strong:text-foreground">
+          <MDXRemote {...customPage.mdxSource} components={mdxComponents} />
+        </div>
+        
+        {/* Always show navigation actions for custom 404 */}
+        <div className="mt-8 pt-6 border-t border-border">
+          <div className="flex flex-col sm:flex-row items-center justify-center gap-3">
+            <Button variant="outline" size="sm" onClick={handleGoBack} className="gap-2 min-w-[120px]">
+              <ArrowLeft className="w-4 h-4" />
+              Go back
+            </Button>
+            <Button variant="default" size="sm" onClick={handleGoHome} className="gap-2 min-w-[120px]">
+              <House className="w-4 h-4" />
+              Go home
+            </Button>
+            {onSearch && (
+              <Button variant="outline" size="sm" onClick={onSearch} className="gap-2 min-w-[120px]">
+                <MagnifyingGlass className="w-4 h-4" />
+                Search
+              </Button>
+            )}
+          </div>
+        </div>
+      </div>
+    )
+  }
+  
+  // Default 404 page
+  return (
+    <div className="docs-page docs-page-not-found w-full min-h-[calc(100vh-200px)] flex items-center justify-center">
+      <div className="text-center px-4 py-12 max-w-md mx-auto">
+        {/* Icon */}
+        <div className="mb-6">
+          <div className="inline-flex items-center justify-center w-20 h-20 rounded-full bg-muted/50 text-muted-foreground">
+            <FileX className="w-10 h-10" weight="light" />
+          </div>
+        </div>
+        
+        {/* Title */}
+        <h1 className="text-2xl font-semibold text-foreground mb-2">
+          Page not found
+        </h1>
+        
+        {/* Description */}
+        <p className="text-muted-foreground mb-2">
+          The page you&apos;re looking for doesn&apos;t exist or has been moved.
+        </p>
+        
+        {/* Show the slug that wasn't found */}
+        {slug && (
+          <p className="text-sm text-muted-foreground/70 mb-6 font-mono bg-muted/30 px-3 py-1.5 rounded-md inline-block">
+            /{slug}
+          </p>
+        )}
+        
+        {!slug && <div className="mb-6" />}
+        
+        {/* Actions */}
+        <div className="flex flex-col sm:flex-row items-center justify-center gap-3">
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={handleGoBack}
+            className="gap-2 min-w-[120px]"
+          >
+            <ArrowLeft className="w-4 h-4" />
+            Go back
+          </Button>
+          
+          <Button
+            variant="default"
+            size="sm"
+            onClick={handleGoHome}
+            className="gap-2 min-w-[120px]"
+          >
+            <House className="w-4 h-4" />
+            Go home
+          </Button>
+          
+          {onSearch && (
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={onSearch}
+              className="gap-2 min-w-[120px]"
+            >
+              <MagnifyingGlass className="w-4 h-4" />
+              Search
+            </Button>
+          )}
+        </div>
+        
+        {/* Help text */}
+        <p className="text-xs text-muted-foreground/60 mt-8">
+          If you believe this is an error, please check the URL or contact the documentation maintainer.
+        </p>
+      </div>
+    </div>
+  )
+}

package/renderer/components/docs-viewer/index.tsx

@@ -4,6 +4,7 @@ import { useEffect, useState, useCallback, useRef } from 'react'
 import { Spinner } from '@phosphor-icons/react'
 import type { BrainfishCollection, BrainfishRESTRequest, BrainfishDocGroup } from '@/lib/api-docs/types'
 import { DocsSidebar } from './sidebar'
+import { NotFoundPage } from './content/not-found-page'
 import { ApiPlayground } from './playground'
 import type { DebugContext } from './playground/response-viewer'
 import { RightSidebar } from './sidebar/right-sidebar'
@@ -391,6 +392,7 @@ function DocsContent() {
   const [isVersionLoading, setIsVersionLoading] = useState(false) // For version switch only
   const [error, setError] = useState<string | null>(null)
   const [showAuthModal, setShowAuthModal] = useState(false)
+  const [notFoundSlug, setNotFoundSlug] = useState<string | null>(null) // Track 404 for invalid URLs
   
   // Prefill context for agent
   const { setPrefill } = usePlaygroundPrefill()
@@ -481,13 +483,16 @@ function DocsContent() {
         setSelectedRequest(request)
         setSelectedDocSection(null)
         setSelectedDocPage(null)
+        setNotFoundSlug(null)
       } else {
-        // Endpoint not found - clear selection
+        // Endpoint not found - show 404 page
         setSelectedRequest(null)
         setSelectedDocSection(null)
         setSelectedDocPage(null)
+        setNotFoundSlug(`endpoint/${actualId}`)
       }
     } else if (actualType === 'page' && actualId) {
+      setNotFoundSlug(null) // Clear not found state - DocPage handles its own 404
       setSelectedDocPage(actualId)
       setSelectedRequest(null)
       setSelectedDocSection(null)
@@ -515,6 +520,7 @@ function DocsContent() {
     setSelectedRequest(request)
     setSelectedDocSection(null)
     setSelectedDocPage(null)
+    setNotFoundSlug(null) // Clear 404 state when selecting an endpoint
     updateUrlHash(`endpoint/${request.id}`)
     // Reset tab navigation so the new endpoint can determine its default tab
     resetNavigation()
@@ -527,6 +533,7 @@ function DocsContent() {
     setSelectedDocSection(isIntro ? null : headingId)
     setSelectedRequest(null)
     setSelectedDocPage(null)
+    setNotFoundSlug(null) // Clear 404 state
     
     updateUrlHash(isIntro ? '' : `doc/${headingId}`)
     
@@ -599,6 +606,7 @@ function DocsContent() {
     setSelectedDocPage(pageSlug)
     setSelectedRequest(null)
     setSelectedDocSection(null)
+    setNotFoundSlug(null) // Clear 404 state
     updateUrlHash(`page/${pageSlug}`, targetTab)
     switchToDocs()
     
@@ -1162,6 +1170,7 @@ function DocsContent() {
         selectedApiVersion={selectedApiVersion}
         handleApiVersionChange={handleApiVersionChange}
         isVersionLoading={isVersionLoading}
+        notFoundSlug={notFoundSlug}
       />
     </NavigationProvider>
   )
@@ -1193,6 +1202,7 @@ interface DocsWithModeProps {
   selectedApiVersion: string | null
   handleApiVersionChange: (version: string) => void
   isVersionLoading: boolean
+  notFoundSlug: string | null
 }
 
 // Mode toggle tabs - switches between Docs, API Client, and Notes
@@ -1268,6 +1278,7 @@ function DocsWithMode({
   selectedApiVersion,
   handleApiVersionChange,
   isVersionLoading,
+  notFoundSlug,
 }: DocsWithModeProps) {
   const { mode, switchToDocs } = useModeContext()
   const { setTheme } = useTheme()
@@ -1340,6 +1351,7 @@ function DocsWithMode({
     if (!showGraphQL || !schemaPath) {
       setGraphqlOperations([])
       setGraphqlCollection(null)
+      setSelectedGraphQLOperation(null) // Clear selection when leaving GraphQL tab
       return
     }
     
@@ -1364,6 +1376,44 @@ function DocsWithMode({
     loadGraphQLSchema()
   }, [showGraphQL, schemaPath, schemaEndpoint])
   
+  // Auto-select GraphQL operation from URL hash or default to first operation
+  useEffect(() => {
+    if (!showGraphQL || graphqlOperations.length === 0) {
+      return
+    }
+    
+    // Check if there's a selection in the URL hash first
+    const hash = window.location.hash.slice(1) // Remove #
+    if (hash) {
+      const parts = hash.split('/')
+      const hashType = parts[1]
+      const hashId = parts.slice(2).join('/')
+      
+      if (hashType === 'endpoint' && hashId) {
+        // Try to find and select the operation from the URL hash
+        const operation = graphqlOperations.find(op => op.id === hashId)
+        if (operation) {
+          setSelectedGraphQLOperation(operation)
+          return
+        }
+      }
+    }
+    
+    // If already have a selection, don't override it
+    if (selectedGraphQLOperation) {
+      return
+    }
+    
+    // Check if there are doc groups for this tab first
+    const hasGroups = hasDocGroupsForTab(collection?.docGroups, activeTab)
+    if (!hasGroups) {
+      // No doc groups - auto-select first GraphQL operation
+      const firstOperation = graphqlOperations[0]
+      setSelectedGraphQLOperation(firstOperation)
+      window.history.pushState(null, '', `#${activeTab}/endpoint/${firstOperation.id}`)
+    }
+  }, [showGraphQL, graphqlOperations, selectedGraphQLOperation, activeTab, collection?.docGroups])
+  
   // Handle GraphQL operation selection from sidebar
   const handleSelectGraphQLOperation = useCallback((request: BrainfishRESTRequest) => {
     // Find the matching GraphQL operation
@@ -1500,10 +1550,10 @@ function DocsWithMode({
                 ref={contentRef}
                 className={cn(
                   "docs-content-area flex-1 bg-background min-w-0",
-                  (showChangelog || showGraphQL) ? "overflow-hidden flex flex-col" : "overflow-y-auto scroll-smooth"
+                  (showChangelog || (showGraphQL && selectedGraphQLOperation)) ? "overflow-hidden flex flex-col" : "overflow-y-auto scroll-smooth"
                 )}
               >
-                {showGraphQL ? (
+                {showGraphQL && selectedGraphQLOperation ? (
                   <div className="flex-1 flex flex-col h-full">
                     <GraphQLPlayground
                       endpoint={activeGraphQLSchemas[0]?.endpoint || ''}
@@ -1523,7 +1573,9 @@ function DocsWithMode({
                 ) : selectedRequest ? (
                   <RequestDetails request={selectedRequest} />
                 ) : selectedDocPage ? (
-                  <DocPage slug={selectedDocPage} />
+                  <DocPage slug={selectedDocPage} onSearch={openSearch} />
+                ) : notFoundSlug ? (
+                  <NotFoundPage slug={notFoundSlug} onSearch={openSearch} />
                 ) : (
                   <div className="flex-1 flex items-center justify-center bg-background">
                     <div className="text-center text-muted-foreground">

package/renderer/components/docs-viewer/sidebar/collection-tree.tsx

@@ -77,6 +77,26 @@ export function CollectionTree({
     }
     return expanded
   })
+  
+  // Re-expand all folders when collection folders change (e.g., tab switch)
+  // This ensures folders are expanded when switching between tabs with different folder sets
+  const folderIds = useMemo(() => 
+    collection.folders.map(f => f.id).sort().join(','), 
+    [collection.folders]
+  )
+  
+  useEffect(() => {
+    if (level === 0 && collection.folders.length > 0) {
+      setExpandedFolders(prev => {
+        const newExpanded = new Set(prev)
+        // Add all current folder IDs to expanded set
+        collection.folders.forEach((folder) => {
+          newExpanded.add(folder.id)
+        })
+        return newExpanded
+      })
+    }
+  }, [folderIds, level, collection.folders])
 
   // Auto-expand folder when selectedRequest changes (e.g., via agent navigation)
   useEffect(() => {

package/templates/basic/README.md

@@ -1,139 +0,0 @@
-# My Documentation
-
-Documentation site built with [DevDoc](https://github.com/brainfish-ai/devdoc).
-
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/brainfish-ai/devdoc-starter)
-
-## Quick Start
-
-### Prerequisites
-
-- [Node.js](https://nodejs.org/) 18.0 or later
-- npm, yarn, or pnpm
-
-### Installation
-
-1. **Clone this repository**
-
-   ```bash
-   git clone https://github.com/your-username/your-docs.git
-   cd your-docs
-   ```
-
-   Or use the GitHub template button above.
-
-2. **Install dependencies**
-
-   ```bash
-   npm install
-   ```
-
-3. **Start the development server**
-
-   ```bash
-   npm run dev
-   ```
-
-4. **Open your browser**
-
-   Visit [http://localhost:3000](http://localhost:3000) to see your docs.
-
-## Project Structure
-
-```
-.
-├── docs.json              # Site configuration
-├── index.mdx              # Homepage
-├── quickstart.mdx         # Quickstart guide
-├── guides/
-│   ├── overview.mdx       # Overview page
-│   └── configuration.mdx  # Configuration guide
-├── public/
-│   ├── logo.svg           # Site logo
-│   └── favicon.svg        # Favicon
-├── package.json
-├── vercel.json            # Vercel deployment config
-└── README.md
-```
-
-## Configuration
-
-Edit `docs.json` to customize your site:
-
-```json
-{
-  "name": "My Documentation",
-  "logo": "/logo.svg",
-  "navigation": {
-    "tabs": [
-      {
-        "tab": "Documentation",
-        "type": "docs",
-        "groups": [
-          {
-            "group": "Getting Started",
-            "pages": ["index", "quickstart"]
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-## Writing Content
-
-Create `.mdx` files with frontmatter:
-
-```mdx
----
-title: Page Title
-description: Page description for SEO
----
-
-# Your Content Here
-
-Write Markdown with React components.
-
-<Note>
-  Use components like Note, Card, Steps, and more.
-</Note>
-```
-
-## Available Commands
-
-| Command | Description |
-|---------|-------------|
-| `npm run dev` | Start development server |
-| `npm run build` | Build for production |
-| `npm run start` | Start production server |
-| `npm run check` | Validate configuration |
-
-## Deployment
-
-### Vercel (Recommended)
-
-Click the "Deploy with Vercel" button above, or:
-
-1. Push your code to GitHub
-2. Import the repository in [Vercel](https://vercel.com)
-3. Deploy!
-
-### Other Platforms
-
-```bash
-# Build the site
-npm run build
-
-# Output is in the dist/ directory
-```
-
-## Learn More
-
-- [DevDoc Documentation](https://devdoc.sh/docs)
-- [MDX Documentation](https://mdxjs.com/)
-- [Vercel Documentation](https://vercel.com/docs)
-
-## License
-
-MIT

package/templates/basic/assets/favicon.svg

@@ -1,4 +0,0 @@
-<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
-  <rect width="32" height="32" rx="8" fill="#10b981"/>
-  <path d="M8 16L14 22L24 10" stroke="white" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
-</svg>