@brainfish-ai/devdoc 0.1.21 → 0.1.23

package/renderer/components/docs-viewer/content/doc-page.tsx

@@ -120,6 +120,20 @@ import {
   PDF,
   Audio,
   Download,
+  // Landing Page Components
+  Hero,
+  Pre,
+  Tagline,
+  Headline,
+  Description,
+  CommandBox,
+  Section,
+  Center,
+  FeatureGrid,
+  FeatureItem,
+  ButtonLink,
+  Spacer,
+  Divider,
 } from '../../docs/mdx/index'
 
 // MDX components mapping
@@ -190,6 +204,21 @@ const mdxComponents = {
   Audio,
   Download,
   
+  // Landing Page
+  Hero,
+  Pre,
+  Tagline,
+  Headline,
+  Description,
+  CommandBox,
+  Section,
+  Center,
+  FeatureGrid,
+  FeatureItem,
+  ButtonLink,
+  Spacer,
+  Divider,
+  
   // Links
   a: MdxLink,
 }
@@ -204,6 +233,11 @@ interface DocPageData {
     title: string
     description?: string
     icon?: string
+    // Page mode and layout options
+    mode?: 'default' | 'wide' | 'custom'
+    hideHeader?: boolean
+    fullWidth?: boolean
+    background?: string
   }
   mdxSource: MDXRemoteSerializeResult
 }
@@ -244,7 +278,7 @@ export function DocPage({ slug }: DocPageProps) {
   
   if (loading) {
     return (
-      <div className="docs-page docs-page-loading max-w-4xl mx-auto px-4 py-6 sm:px-8 sm:py-8">
+      <div className="docs-page docs-page-loading w-full min-h-[200px]">
         <div className="docs-loading flex items-center justify-center py-12">
           <Spinner className="h-6 w-6 animate-spin text-muted-foreground" />
         </div>
@@ -254,7 +288,7 @@ export function DocPage({ slug }: DocPageProps) {
   
   if (error || !pageData) {
     return (
-      <div className="docs-page docs-page-error max-w-4xl mx-auto px-4 py-6 sm:px-8 sm:py-8">
+      <div className="docs-page docs-page-error w-full min-h-[200px]">
         <div className="docs-error text-center py-12">
           <p className="text-destructive">{error || 'Page not found'}</p>
         </div>
@@ -262,19 +296,52 @@ export function DocPage({ slug }: DocPageProps) {
     )
   }
   
-  return (
-    <div ref={contentRef} className="docs-page docs-content max-w-4xl mx-auto px-4 py-6 sm:px-8 sm:py-8">
-      {/* Page header */}
-      <div className="docs-page-header mb-6">
-        <h1 className="docs-content-title text-2xl sm:text-3xl font-bold mb-2 text-foreground">
-          {pageData.frontmatter.title}
-        </h1>
-        {pageData.frontmatter.description && (
-          <p className="docs-content-description text-lg text-muted-foreground">
-            {pageData.frontmatter.description}
-          </p>
-        )}
+  const { mode = 'default', hideHeader, fullWidth, background } = pageData.frontmatter
+  const isCustomMode = mode === 'custom'
+  const isWideMode = mode === 'wide'
+  const showHeader = !hideHeader && !isCustomMode
+  
+  // Custom mode: Full-width layout for landing pages
+  if (isCustomMode) {
+    return (
+      <div 
+        ref={contentRef} 
+        className="docs-page docs-page-custom docs-content w-full min-h-full"
+        style={{ 
+          background: background || 'var(--background)',
+          // Ensure the content fills the entire viewport width within the content area
+          marginLeft: 0,
+          marginRight: 0,
+        }}
+      >
+        {/* Custom pages render MDX content directly without container constraints */}
+        <div className="docs-custom-content [&>*]:w-full">
+          <MDXRemote {...pageData.mdxSource} components={mdxComponents} />
+        </div>
       </div>
+    )
+  }
+  
+  // Default/Wide mode: Standard documentation layout
+  const containerClass = isWideMode 
+    ? 'max-w-6xl' // Wide mode
+    : 'max-w-4xl' // Default mode
+  
+  return (
+    <div ref={contentRef} className={`docs-page docs-content ${containerClass} mx-auto px-4 py-6 sm:px-8 sm:py-8`}>
+      {/* Page header - shown unless hideHeader is true */}
+      {showHeader && (
+        <div className="docs-page-header mb-6">
+          <h1 className="docs-content-title text-2xl sm:text-3xl font-bold mb-2 text-foreground">
+            {pageData.frontmatter.title}
+          </h1>
+          {pageData.frontmatter.description && (
+            <p className="docs-content-description text-lg text-muted-foreground">
+              {pageData.frontmatter.description}
+            </p>
+          )}
+        </div>
+      )}
       
       {/* Page content - MDX rendered with custom components */}
       <div className="docs-prose prose prose-sm max-w-none prose-headings:text-foreground prose-p:text-muted-foreground prose-strong:text-foreground prose-code:text-foreground prose-pre:bg-muted prose-code:bg-muted prose-code:px-1 prose-code:py-0.5 prose-code:rounded prose-pre:overflow-x-auto prose-table:w-full prose-th:text-left prose-th:p-3 prose-th:bg-muted prose-td:p-3 prose-td:border-b prose-td:border-border">

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

@@ -7,7 +7,6 @@ import { DocsSidebar } from './sidebar'
 import { ApiPlayground } from './playground'
 import type { DebugContext } from './playground/response-viewer'
 import { RightSidebar } from './sidebar/right-sidebar'
-import { Introduction } from './content/introduction'
 import { RequestDetails } from './content/request-details'
 import { DocPage } from './content/doc-page'
 import { ChangelogPage } from './content/changelog-page'
@@ -241,6 +240,53 @@ function findRequestById(collection: BrainfishCollection, id: string): Brainfish
   return null
 }
 
+// Helper to get the first endpoint from collection
+function getFirstEndpoint(collection: BrainfishCollection): BrainfishRESTRequest | null {
+  // Check direct requests first
+  if (collection.requests.length > 0) {
+    return collection.requests[0]
+  }
+  
+  // Check folders recursively
+  for (const folder of collection.folders) {
+    const firstInFolder = getFirstEndpoint(folder)
+    if (firstInFolder) return firstInFolder
+  }
+  return null
+}
+
+// Helper to check if a doc group belongs to a specific tab
+// Group IDs are formatted as: group-{tab-id}-{group-name}
+function isGroupForTab(groupId: string, tabId: string): boolean {
+  // Check if the group ID starts with "group-{tabId}-"
+  const prefix = `group-${tabId}-`
+  return groupId.startsWith(prefix)
+}
+
+// Helper to check if a tab has doc groups (MDX pages)
+function hasDocGroupsForTab(
+  docGroups: BrainfishDocGroup[] | undefined, 
+  tabId: string
+): boolean {
+  if (!docGroups || docGroups.length === 0) return false
+  
+  // Check if any doc group belongs to this tab and has pages
+  return docGroups.some(g => isGroupForTab(g.id, tabId) && g.pages.length > 0)
+}
+
+// Helper to get the first page from doc groups for a tab
+function getFirstDocPageForTab(
+  docGroups: BrainfishDocGroup[] | undefined,
+  tabId: string
+): string | null {
+  if (!docGroups || docGroups.length === 0) return null
+  
+  const tabDocGroup = docGroups.find(g => isGroupForTab(g.id, tabId) && g.pages.length > 0)
+  
+  return tabDocGroup?.pages[0]?.slug || null
+}
+
+
 // API version
 interface ApiVersion {
   version: string
@@ -391,19 +437,21 @@ function DocsContent() {
   const navigateToHash = useCallback((collectionData: BrainfishCollection) => {
     const hash = window.location.hash.slice(1) // Remove #
 
-    console.log('[Docs] Navigating to hash:', hash)
-
     if (!hash) {
-      // No hash - show Introduction by default
-      setSelectedRequest(null)
+      // No hash - auto-select first endpoint
       setSelectedDocSection(null)
       setSelectedDocPage(null)
+      const firstEndpoint = getFirstEndpoint(collectionData)
+      if (firstEndpoint) {
+        setSelectedRequest(firstEndpoint)
+      } else {
+        setSelectedRequest(null)
+      }
       return
     }
 
     // Notes mode is handled by ModeContext, just clear API selection
     if (hash === 'notes' || hash.startsWith('notes/')) {
-      console.log('[Docs] Notes mode detected, clearing API selection')
       setSelectedRequest(null)
       setSelectedDocSection(null)
       setSelectedDocPage(null)
@@ -428,9 +476,7 @@ function DocsContent() {
     const actualId = id || (legacyType ? hash.replace(`${legacyType}/`, '') : null)
 
     if (actualType === 'endpoint' && actualId) {
-      console.log('[Docs] Looking for endpoint:', actualId)
       const request = findRequestById(collectionData, actualId)
-      console.log('[Docs] Found request:', request?.name || 'NOT FOUND')
       if (request) {
         setSelectedRequest(request)
         setSelectedDocSection(null)
@@ -598,18 +644,55 @@ function DocsContent() {
     // Reset mode to docs when switching tabs (exit sandbox/api-client mode)
     switchToDocs()
 
-    if (tabId === 'api-reference') {
-      // Switch to API Reference - clear doc page and show introduction (no endpoint selected)
-      setSelectedDocPage(null)
-      setSelectedRequest(null)
-      setSelectedDocSection(null)
-      updateUrlHash('', tabId)
-    } else if (tabId === 'changelog') {
+    // Find the tab config to check its type
+    const tabConfig = collection?.navigationTabs?.find(t => t.id === tabId)
+    const isApiTab = tabConfig?.type === 'openapi' || tabConfig?.type === 'graphql' || tabId === 'api-reference'
+
+    if (tabId === 'changelog') {
       // Switch to Changelog tab
       setSelectedDocPage(null)
       setSelectedRequest(null)
       setSelectedDocSection(null)
       updateUrlHash('', tabId)
+    } else if (isApiTab) {
+      // API Reference or GraphQL tab
+      setSelectedDocSection(null)
+      
+      // Check if there are doc groups for this tab (MDX pages)
+      const hasGroups = hasDocGroupsForTab(collection?.docGroups, tabId)
+      
+      if (hasGroups) {
+        // Has doc groups - select the first page from groups
+        const firstPage = getFirstDocPageForTab(collection?.docGroups, tabId)
+        if (firstPage) {
+          setSelectedDocPage(firstPage)
+          setSelectedRequest(null)
+          updateUrlHash(`page/${firstPage}`, tabId)
+          switchToDocs()
+        } else {
+          // No pages in groups - auto-select first endpoint
+          setSelectedDocPage(null)
+          const firstEndpoint = collection ? getFirstEndpoint(collection) : null
+          if (firstEndpoint) {
+            setSelectedRequest(firstEndpoint)
+            updateUrlHash(`endpoint/${firstEndpoint.id}`, tabId)
+          } else {
+            setSelectedRequest(null)
+            updateUrlHash('', tabId)
+          }
+        }
+      } else {
+        // No doc groups - auto-select first endpoint
+        setSelectedDocPage(null)
+        const firstEndpoint = collection ? getFirstEndpoint(collection) : null
+        if (firstEndpoint) {
+          setSelectedRequest(firstEndpoint)
+          updateUrlHash(`endpoint/${firstEndpoint.id}`, tabId)
+        } else {
+          setSelectedRequest(null)
+          updateUrlHash('', tabId)
+        }
+      }
     } else {
       // Switch to a doc group tab - find and select the first page in that tab
       setSelectedRequest(null)
@@ -617,10 +700,7 @@ function DocsContent() {
 
       // Find the first doc group for this tab and select its first page
       if (collection?.docGroups) {
-        const tabDocGroup = collection.docGroups.find(g => {
-          const groupTabPart = g.id.replace('group-', '').split('-')[0]
-          return groupTabPart === tabId
-        })
+        const tabDocGroup = collection.docGroups.find(g => isGroupForTab(g.id, tabId))
 
         if (tabDocGroup && tabDocGroup.pages.length > 0) {
           const firstPage = tabDocGroup.pages[0]
@@ -733,8 +813,6 @@ function DocsContent() {
     // Also update shortcut icon and apple-touch-icon
     updateFaviconLink('shortcut icon', faviconPath)
     updateFaviconLink('apple-touch-icon', faviconPath)
-    
-    console.log('[Docs] Set favicon to:', faviconPath)
   }, [collection?.docsFavicon])
 
   useEffect(() => {
@@ -761,16 +839,6 @@ function DocsContent() {
         }
 
         const data = await response.json()
-        
-        console.log('[Docs] Collection data:', JSON.stringify({
-          hasData: !!data,
-          name: data?.name,
-          requestsCount: data?.requests?.length || 0,
-          foldersCount: data?.folders?.length || 0,
-          apiVersions: data?.apiVersions?.length || 0,
-          selectedVersion: data?.selectedApiVersion,
-        }, null, 2))
-        
         setCollection(data)
         
         // Set initial API version if not already set
@@ -793,24 +861,60 @@ function DocsContent() {
             // Use setTimeout to ensure state is set before navigation
             setTimeout(() => {
               const hash = window.location.hash.slice(1)
-              console.log('[Docs] Initial hash:', hash)
 
               if (!hash) {
                 // No hash - set URL to initial tab
-                updateUrlHash('', initialTabId)
-                setSelectedRequest(null)
                 setSelectedDocSection(null)
 
-                if (initialTabId === 'api-reference') {
-                  // API Reference tab - show introduction
-                  setSelectedDocPage(null)
+                // Find the tab config to check its type
+                const tabConfig = data.navigationTabs?.find((t: NavigationTab) => t.id === initialTabId)
+                const isApiTab = tabConfig?.type === 'openapi' || tabConfig?.type === 'graphql' || initialTabId === 'api-reference'
+
+                if (isApiTab) {
+                  // API Reference or GraphQL tab
+                  setSelectedDocSection(null)
+                  
+                  // Check if there are doc groups for this tab (MDX pages)
+                  const hasGroups = hasDocGroupsForTab(data.docGroups, initialTabId)
+                  
+                  if (hasGroups) {
+                    // Has doc groups - select the first page from groups
+                    const firstPage = getFirstDocPageForTab(data.docGroups, initialTabId)
+                    if (firstPage) {
+                      setSelectedDocPage(firstPage)
+                      setSelectedRequest(null)
+                      updateUrlHash(`page/${firstPage}`, initialTabId)
+                    } else {
+                      // No pages in groups - auto-select first endpoint
+                      setSelectedDocPage(null)
+                      const firstEndpoint = getFirstEndpoint(data)
+                      if (firstEndpoint) {
+                        setSelectedRequest(firstEndpoint)
+                        updateUrlHash(`endpoint/${firstEndpoint.id}`, initialTabId)
+                      } else {
+                        setSelectedRequest(null)
+                        updateUrlHash('', initialTabId)
+                      }
+                    }
+                  } else {
+                    // No doc groups - auto-select first endpoint
+                    setSelectedDocPage(null)
+                    const firstEndpoint = getFirstEndpoint(data)
+                    if (firstEndpoint) {
+                      setSelectedRequest(firstEndpoint)
+                      updateUrlHash(`endpoint/${firstEndpoint.id}`, initialTabId)
+                    } else {
+                      setSelectedRequest(null)
+                      updateUrlHash('', initialTabId)
+                    }
+                  }
                   switchToDocs()
                 } else {
                   // Doc group tab - select first page
-                  const tabDocGroup = data.docGroups?.find((g: BrainfishDocGroup) => {
-                    const groupTabPart = g.id.replace('group-', '').split('-')[0]
-                    return groupTabPart === initialTabId
-                  })
+                  setSelectedRequest(null)
+                  const tabDocGroup = data.docGroups?.find((g: BrainfishDocGroup) => 
+                    isGroupForTab(g.id, initialTabId)
+                  )
 
                   if (tabDocGroup && tabDocGroup.pages.length > 0) {
                     const firstPage = tabDocGroup.pages[0]
@@ -819,12 +923,12 @@ function DocsContent() {
                     switchToDocs()
                   } else {
                     setSelectedDocPage(null)
+                    updateUrlHash('', initialTabId)
                     switchToDocs()
                   }
                 }
               } else if (hash === 'notes' || hash.startsWith('notes/')) {
                 // Notes mode - handled by ModeContext, just clear API selection
-                console.log('[Docs] Initial hash is notes mode')
                 setSelectedRequest(null)
                 setSelectedDocSection(null)
               } else {
@@ -846,14 +950,13 @@ function DocsContent() {
                 const actualId = isLegacyFormat ? parts.slice(1).join('/') : hashId
                 
                 if (actualType === 'endpoint' && actualId) {
-                  console.log('[Docs] Looking for endpoint on load:', actualId)
                   const request = findRequestById(data, actualId)
-                  console.log('[Docs] Found:', request?.name || 'NOT FOUND')
                   if (request) {
                     setSelectedRequest(request)
                     setSelectedDocSection(null)
                     setSelectedDocPage(null)
                     switchToDocs()
+                    return
                   } else {
                     setSelectedRequest(null)
                     setSelectedDocSection(null)
@@ -878,9 +981,49 @@ function DocsContent() {
                   }, 100)
                 } else if (hashTab && !hashType) {
                   // Just a tab, show its default content
-                  setSelectedRequest(null)
                   setSelectedDocSection(null)
-                  setSelectedDocPage(null)
+                  
+                  // Check if this is an API tab
+                  const tabConfig = data.navigationTabs?.find((t: NavigationTab) => t.id === hashTab)
+                  const isApiTab = tabConfig?.type === 'openapi' || tabConfig?.type === 'graphql' || hashTab === 'api-reference'
+                  
+                  if (isApiTab) {
+                    // Check if there are doc groups for this tab (MDX pages)
+                    const hasGroups = hasDocGroupsForTab(data.docGroups, hashTab)
+                    
+                    if (hasGroups) {
+                      // Has doc groups - select the first page from groups
+                      const firstPage = getFirstDocPageForTab(data.docGroups, hashTab)
+                      if (firstPage) {
+                        setSelectedDocPage(firstPage)
+                        setSelectedRequest(null)
+                        updateUrlHash(`page/${firstPage}`, hashTab)
+                      } else {
+                        // No pages in groups - auto-select first endpoint
+                        setSelectedDocPage(null)
+                        const firstEndpoint = getFirstEndpoint(data)
+                        if (firstEndpoint) {
+                          setSelectedRequest(firstEndpoint)
+                          updateUrlHash(`endpoint/${firstEndpoint.id}`, hashTab)
+                        } else {
+                          setSelectedRequest(null)
+                        }
+                      }
+                    } else {
+                      // No doc groups - auto-select first endpoint
+                      setSelectedDocPage(null)
+                      const firstEndpoint = getFirstEndpoint(data)
+                      if (firstEndpoint) {
+                        setSelectedRequest(firstEndpoint)
+                        updateUrlHash(`endpoint/${firstEndpoint.id}`, hashTab)
+                      } else {
+                        setSelectedRequest(null)
+                      }
+                    }
+                  } else {
+                    setSelectedDocPage(null)
+                    setSelectedRequest(null)
+                  }
                   switchToDocs()
                 }
               }
@@ -1170,17 +1313,13 @@ function DocsWithMode({
   // Find the active tab's config
   const activeTabConfig = collection.navigationTabs?.find(t => t.id === activeTab)
   const activeTabType = activeTabConfig?.type || 'docs'
-  // Use the tab name for page header
-  const activeTabTitle = activeTabConfig?.tab || 'Documentation'
 
   
   // Filter doc groups for sidebar based on active tab
   // Group IDs are like "group-guides-getting-started", tab IDs are like "guides"
-  const filteredDocGroups = collection.docGroups?.filter(g => {
-    // Extract the tab part from the group ID (e.g., "guides" from "group-guides-getting-started")
-    const groupTabPart = g.id.replace('group-', '').split('-')[0]
-    return groupTabPart === activeTab
-  }) || []
+  // Filter doc groups for sidebar based on active tab
+  // Group IDs are formatted as: group-{tab-id}-{group-name}
+  const filteredDocGroups = collection.docGroups?.filter(g => isGroupForTab(g.id, activeTab)) || []
   
   // Show endpoints in sidebar only when OpenAPI tab is active
   const showEndpoints = activeTabType === 'openapi'
@@ -1285,7 +1424,7 @@ function DocsWithMode({
   }, [collection?.defaultTheme, setTheme])
   
   return (
-    <>
+    <div className="docs-viewer-root flex flex-col h-screen overflow-hidden">
       {/* Notice */}
       {collection.notice && (
         <Notice config={collection.notice} storageKey="docs-notice" />
@@ -1313,7 +1452,7 @@ function DocsWithMode({
         docsNavbar={collection.docsNavbar}
       />
       
-      <div className="docs-layout flex h-[calc(100vh-6rem)] overflow-hidden relative z-0">
+      <div className="docs-layout flex flex-1 overflow-hidden relative z-0 min-h-0">
         {/* Left Sidebar - Hidden for changelog */}
         {!showChangelog && (
           <DocsSidebar
@@ -1344,9 +1483,9 @@ function DocsWithMode({
         )}
         
         {/* Center - Toggles between API Client/Playground and Notes */}
-        <div className="docs-main flex-1 flex flex-col overflow-hidden min-w-0">
+        <div className="docs-main flex-1 flex flex-col overflow-hidden" style={{ minWidth: 0, flexBasis: 0, flexGrow: 1 }}>
           {/* Mode Toggle Header */}
-          <div className="docs-main-header flex items-center justify-end px-3 sm:px-4 h-[41px] border-b border-border bg-muted/30">
+          <div className="docs-main-header flex items-center justify-end px-3 sm:px-4 h-[41px] border-b border-border bg-muted/30 flex-shrink-0">
             <ModeToggleTabs hasEndpoint={!!selectedRequest} />
           </div>
           
@@ -1386,7 +1525,12 @@ function DocsWithMode({
                 ) : selectedDocPage ? (
                   <DocPage slug={selectedDocPage} />
                 ) : (
-                  <Introduction collection={collection} />
+                  <div className="flex-1 flex items-center justify-center bg-background">
+                    <div className="text-center text-muted-foreground">
+                      <Book className="h-12 w-12 mx-auto mb-3 opacity-40" />
+                      <p className="text-sm">Select an endpoint from the sidebar</p>
+                    </div>
+                  </div>
                 )}
               </div>
             </DocsNavigationProvider>
@@ -1446,7 +1590,7 @@ function DocsWithMode({
         open={showAuthModal} 
         onClose={() => setShowAuthModal(false)} 
       />
-    </>
+    </div>
   )
 }