@brainfish-ai/devdoc 0.1.21

package/renderer/components/docs/mdx/mermaid.tsx

@@ -0,0 +1,240 @@
+'use client'
+
+import { useEffect, useRef, useState, useCallback } from 'react'
+import { createPortal } from 'react-dom'
+import { cn } from '@/lib/utils'
+import { ArrowsOut, X } from '@phosphor-icons/react'
+
+interface MermaidProps {
+  children: string
+  className?: string
+}
+
+// Helper to detect dark mode
+function useIsDarkMode() {
+  const [isDark, setIsDark] = useState(false)
+  
+  useEffect(() => {
+    const checkDarkMode = () => {
+      setIsDark(document.documentElement.classList.contains('dark'))
+    }
+    
+    checkDarkMode()
+    
+    // Watch for theme changes
+    const observer = new MutationObserver(checkDarkMode)
+    observer.observe(document.documentElement, { 
+      attributes: true, 
+      attributeFilter: ['class'] 
+    })
+    
+    return () => observer.disconnect()
+  }, [])
+  
+  return isDark
+}
+
+export function Mermaid({ children, className }: MermaidProps) {
+  const contentRef = useRef<HTMLDivElement>(null)
+  const [isLoaded, setIsLoaded] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [isModalOpen, setIsModalOpen] = useState(false)
+  const [mounted, setMounted] = useState(false)
+  const [modalSvg, setModalSvg] = useState<string>('')
+  const [modalLoading, setModalLoading] = useState(false)
+  const isDarkMode = useIsDarkMode()
+
+  const code = typeof children === 'string' ? children.trim() : ''
+
+  // Track if component is mounted (for portal)
+  useEffect(() => {
+    setMounted(true)
+  }, [])
+
+  // Render inline diagram
+  useEffect(() => {
+    if (!code || !contentRef.current) return
+
+    const renderDiagram = async () => {
+      try {
+        const mermaid = (await import('mermaid')).default
+        
+        mermaid.initialize({
+          startOnLoad: false,
+          theme: isDarkMode ? 'dark' : 'default',
+          securityLevel: 'loose',
+          fontFamily: 'inherit',
+        })
+
+        const id = `mermaid-inline-${Math.random().toString(36).substr(2, 9)}`
+        const { svg } = await mermaid.render(id, code)
+        
+        if (contentRef.current) {
+          contentRef.current.innerHTML = svg
+          setIsLoaded(true)
+          setError(null)
+        }
+      } catch (err) {
+        console.error('Mermaid rendering error:', err)
+        setError(err instanceof Error ? err.message : 'Failed to render diagram')
+        setIsLoaded(true)
+      }
+    }
+
+    renderDiagram()
+  }, [code, isDarkMode])
+
+  // Render modal diagram when modal opens
+  useEffect(() => {
+    if (!isModalOpen || !code) return
+
+    setModalLoading(true)
+    setModalSvg('')
+
+    const renderModalDiagram = async () => {
+      try {
+        const mermaid = (await import('mermaid')).default
+        
+        mermaid.initialize({
+          startOnLoad: false,
+          theme: isDarkMode ? 'dark' : 'default',
+          securityLevel: 'loose',
+          fontFamily: 'inherit',
+        })
+
+        const id = `mermaid-modal-${Math.random().toString(36).substr(2, 9)}`
+        const { svg } = await mermaid.render(id, code)
+        
+        setModalSvg(svg)
+        setModalLoading(false)
+      } catch (err) {
+        console.error('Mermaid modal rendering error:', err)
+        setModalSvg(`<div class="p-4 text-red-500">Failed to render diagram</div>`)
+        setModalLoading(false)
+      }
+    }
+
+    renderModalDiagram()
+  }, [isModalOpen, code, isDarkMode])
+
+  // Close modal on escape key
+  useEffect(() => {
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === 'Escape' && isModalOpen) {
+        setIsModalOpen(false)
+      }
+    }
+
+    document.addEventListener('keydown', handleEscape)
+    return () => document.removeEventListener('keydown', handleEscape)
+  }, [isModalOpen])
+
+  // Prevent body scroll when modal is open
+  useEffect(() => {
+    if (isModalOpen) {
+      document.body.style.overflow = 'hidden'
+    } else {
+      document.body.style.overflow = ''
+    }
+    return () => {
+      document.body.style.overflow = ''
+    }
+  }, [isModalOpen])
+
+  const openModal = useCallback(() => {
+    setIsModalOpen(true)
+  }, [])
+
+  const closeModal = useCallback(() => {
+    setIsModalOpen(false)
+  }, [])
+
+  if (error) {
+    return (
+      <div className={cn(
+        'my-4 p-4 rounded-lg border border-red-200 bg-red-50 dark:border-red-800 dark:bg-red-950',
+        className
+      )}>
+        <p className="text-sm text-red-600 dark:text-red-400 font-medium">
+          Failed to render Mermaid diagram
+        </p>
+        <pre className="mt-2 text-xs text-red-500 dark:text-red-400 overflow-auto">
+          {error}
+        </pre>
+      </div>
+    )
+  }
+
+  return (
+    <>
+      <div 
+        className={cn(
+          'my-4 relative rounded-lg border border-border bg-muted/30 overflow-hidden group',
+          className
+        )}
+      >
+        {/* Inline diagram */}
+        <div className="overflow-hidden min-h-[200px] relative">
+          <div
+            ref={contentRef}
+            className={cn(
+              'flex items-center justify-center p-4',
+              !isLoaded && 'opacity-0'
+            )}
+          />
+          {!isLoaded && (
+            <div className="absolute inset-0 flex items-center justify-center">
+              <div className="text-sm text-muted-foreground">Loading diagram...</div>
+            </div>
+          )}
+        </div>
+
+        {/* Fullscreen button */}
+        {isLoaded && (
+          <button
+            onClick={openModal}
+            className="absolute bottom-3 right-3 p-2 bg-background/90 backdrop-blur-sm rounded-lg border border-border shadow-sm hover:bg-muted transition-colors opacity-0 group-hover:opacity-100"
+            title="View fullscreen"
+          >
+            <ArrowsOut className="h-4 w-4" weight="bold" />
+          </button>
+        )}
+      </div>
+
+      {/* Modal via Portal */}
+      {mounted && isModalOpen && createPortal(
+        <div 
+          className="fixed inset-0 z-[9999] flex items-center justify-center bg-black/80 backdrop-blur-sm"
+          onClick={closeModal}
+        >
+          <div 
+            className="relative bg-background rounded-lg border border-border shadow-2xl w-[95vw] h-[95vh] overflow-auto flex items-center justify-center"
+            onClick={(e) => e.stopPropagation()}
+          >
+            {/* Close button */}
+            <button
+              onClick={closeModal}
+              className="absolute top-4 right-4 p-2 bg-muted/80 hover:bg-muted rounded-lg transition-colors z-10"
+              title="Close (Esc)"
+            >
+              <X className="h-5 w-5" weight="bold" />
+            </button>
+            
+            {/* Modal diagram */}
+            {modalLoading ? (
+              <div className="text-sm text-muted-foreground">Loading diagram...</div>
+            ) : modalSvg ? (
+              <div 
+                className="p-8 flex items-center justify-center [&_svg]:w-auto [&_svg]:h-auto [&_svg]:min-w-[60vw] [&_svg]:min-h-[60vh] [&_svg]:max-w-[90vw] [&_svg]:max-h-[90vh]"
+                dangerouslySetInnerHTML={{ __html: modalSvg }}
+              />
+            ) : (
+              <div className="text-sm text-muted-foreground">No diagram content (modalSvg is empty)</div>
+            )}
+          </div>
+        </div>,
+        document.body
+      )}
+    </>
+  )
+}

package/renderer/components/docs/mdx/param-field.tsx

@@ -0,0 +1,200 @@
+'use client'
+
+import React from 'react'
+import { cn } from '@/lib/utils'
+
+/**
+ * ParamField and ResponseField Components for MDX Documentation
+ * 
+ * Mintlify-compatible components for documenting API parameters and responses.
+ */
+
+interface ParamFieldProps {
+  /** Parameter path/name (e.g., "body.user.name" or "query.limit") */
+  path?: string
+  /** Parameter name (alternative to path) */
+  name?: string
+  /** Parameter type (e.g., "string", "number", "object") */
+  type?: string
+  /** Whether the parameter is required */
+  required?: boolean
+  /** Whether the parameter is deprecated */
+  deprecated?: boolean
+  /** Default value */
+  default?: string
+  /** Placeholder text */
+  placeholder?: string
+  /** Additional description as children */
+  children?: React.ReactNode
+  className?: string
+}
+
+export function ParamField({
+  path,
+  name,
+  type,
+  required = false,
+  deprecated = false,
+  default: defaultValue,
+  placeholder,
+  children,
+  className,
+}: ParamFieldProps) {
+  const paramName = name || path?.split('.').pop() || 'param'
+  const paramPath = path || name
+  
+  return (
+    <div
+      className={cn(
+        'py-4 border-b border-border last:border-0',
+        deprecated && 'opacity-60',
+        className
+      )}
+    >
+      <div className="flex flex-wrap items-baseline gap-2 mb-1">
+        {/* Parameter name */}
+        <code className="text-sm font-semibold text-foreground">
+          {paramName}
+        </code>
+        
+        {/* Type badge */}
+        {type && (
+          <span className="text-xs px-1.5 py-0.5 rounded bg-muted text-muted-foreground font-mono">
+            {type}
+          </span>
+        )}
+        
+        {/* Required badge */}
+        {required && (
+          <span className="text-xs px-1.5 py-0.5 rounded bg-red-500/10 text-red-600 dark:text-red-400 font-medium">
+            required
+          </span>
+        )}
+        
+        {/* Deprecated badge */}
+        {deprecated && (
+          <span className="text-xs px-1.5 py-0.5 rounded bg-amber-500/10 text-amber-600 dark:text-amber-400 font-medium">
+            deprecated
+          </span>
+        )}
+      </div>
+      
+      {/* Full path if different from name */}
+      {paramPath && paramPath !== paramName && (
+        <div className="text-xs text-muted-foreground mb-2 font-mono">
+          {paramPath}
+        </div>
+      )}
+      
+      {/* Default value */}
+      {defaultValue && (
+        <div className="text-xs text-muted-foreground mb-2">
+          Default: <code className="bg-muted px-1 py-0.5 rounded">{defaultValue}</code>
+        </div>
+      )}
+      
+      {/* Placeholder */}
+      {placeholder && (
+        <div className="text-xs text-muted-foreground mb-2">
+          Example: <code className="bg-muted px-1 py-0.5 rounded">{placeholder}</code>
+        </div>
+      )}
+      
+      {/* Description */}
+      {children && (
+        <div className="text-sm text-foreground/90 [&>p]:mb-2 [&>p:last-child]:mb-0">
+          {children}
+        </div>
+      )}
+    </div>
+  )
+}
+
+interface ResponseFieldProps {
+  /** Field name */
+  name: string
+  /** Field type */
+  type?: string
+  /** Whether the field is always present */
+  required?: boolean
+  /** Additional description */
+  children?: React.ReactNode
+  className?: string
+}
+
+export function ResponseField({
+  name,
+  type,
+  required = false,
+  children,
+  className,
+}: ResponseFieldProps) {
+  return (
+    <div className={cn('py-4 border-b border-border last:border-0', className)}>
+      <div className="flex flex-wrap items-baseline gap-2 mb-1">
+        {/* Field name */}
+        <code className="text-sm font-semibold text-foreground">
+          {name}
+        </code>
+        
+        {/* Type badge */}
+        {type && (
+          <span className="text-xs px-1.5 py-0.5 rounded bg-muted text-muted-foreground font-mono">
+            {type}
+          </span>
+        )}
+        
+        {/* Required/always present badge */}
+        {required && (
+          <span className="text-xs px-1.5 py-0.5 rounded bg-green-500/10 text-green-600 dark:text-green-400 font-medium">
+            always present
+          </span>
+        )}
+      </div>
+      
+      {/* Description */}
+      {children && (
+        <div className="text-sm text-foreground/90 [&>p]:mb-2 [&>p:last-child]:mb-0">
+          {children}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Expandable component for nested objects
+ */
+interface ExpandableProps {
+  title?: string
+  defaultOpen?: boolean
+  children: React.ReactNode
+  className?: string
+}
+
+export function Expandable({
+  title = 'Show child attributes',
+  defaultOpen = false,
+  children,
+  className,
+}: ExpandableProps) {
+  const [isOpen, setIsOpen] = React.useState(defaultOpen)
+  
+  return (
+    <div className={cn('mt-2 ml-4 border-l-2 border-border', className)}>
+      <button
+        type="button"
+        onClick={() => setIsOpen(!isOpen)}
+        className="text-xs text-primary hover:text-primary/80 transition-colors pl-3 py-1"
+      >
+        {isOpen ? 'Hide' : 'Show'} {title.replace('Show ', '').replace('Hide ', '')}
+      </button>
+      
+      {isOpen && (
+        <div className="pl-4 pt-2">
+          {children}
+        </div>
+      )}
+    </div>
+  )
+}

package/renderer/components/docs/mdx/steps.tsx

@@ -0,0 +1,113 @@
+'use client'
+
+import React from 'react'
+import { cn } from '@/lib/utils'
+import * as PhosphorIcons from '@phosphor-icons/react'
+
+/**
+ * Steps Components for MDX Documentation
+ * 
+ * Mintlify-compatible step-by-step guide components.
+ */
+
+// Dynamic icon resolver
+function getIcon(iconName: string): React.ComponentType<{ className?: string; weight?: string }> | null {
+  if (!iconName) return null
+  
+  const pascalCase = iconName
+    .split(/[-_]/)
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join('')
+  
+  const Icon = (PhosphorIcons as Record<string, unknown>)[pascalCase] as React.ComponentType<{ className?: string; weight?: string }> | undefined
+  return Icon || null
+}
+
+interface StepProps {
+  title: string
+  children: React.ReactNode
+  icon?: string
+  iconType?: string
+  stepNumber?: number
+  titleSize?: 'p' | 'h2' | 'h3' | 'h4'
+  className?: string
+}
+
+interface StepsContextValue {
+  titleSize: 'p' | 'h2' | 'h3' | 'h4'
+}
+
+const StepsContext = React.createContext<StepsContextValue>({ titleSize: 'p' })
+
+export function Step({
+  title,
+  children,
+  icon,
+  stepNumber,
+  titleSize: localTitleSize,
+  className,
+}: StepProps) {
+  const { titleSize: contextTitleSize } = React.useContext(StepsContext)
+  const titleSize = localTitleSize ?? contextTitleSize
+  
+  const Icon = icon ? getIcon(icon) : null
+  
+  const TitleTag = titleSize === 'p' ? 'div' : titleSize
+  const titleClass = cn(
+    'font-semibold text-foreground',
+    titleSize === 'h2' && 'text-xl',
+    titleSize === 'h3' && 'text-lg',
+    titleSize === 'h4' && 'text-base',
+    titleSize === 'p' && 'text-base'
+  )
+  
+  return (
+    <div className={cn('relative pl-8 pb-8 last:pb-0', className)}>
+      {/* Vertical line */}
+      <div className="absolute left-[11px] top-8 bottom-0 w-px bg-border last:hidden" />
+      
+      {/* Step indicator */}
+      <div className="absolute left-0 top-0 flex h-6 w-6 items-center justify-center rounded-full bg-primary text-primary-foreground text-xs font-semibold">
+        {Icon ? (
+          <Icon className="h-3.5 w-3.5" weight="bold" />
+        ) : (
+          stepNumber
+        )}
+      </div>
+      
+      {/* Content */}
+      <div className="pt-0.5">
+        <TitleTag className={titleClass}>{title}</TitleTag>
+        <div className="mt-2 text-sm text-foreground/90 [&>p]:mb-2 [&>p:last-child]:mb-0 [&>pre]:my-3 [&>ul]:mt-2 [&>ol]:mt-2">
+          {children}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+interface StepsProps {
+  children: React.ReactNode
+  titleSize?: 'p' | 'h2' | 'h3' | 'h4'
+  className?: string
+}
+
+export function Steps({ children, titleSize = 'p', className }: StepsProps) {
+  // Auto-number steps
+  const numberedChildren = React.Children.map(children, (child, index) => {
+    if (React.isValidElement<StepProps>(child) && child.type === Step) {
+      return React.cloneElement(child, {
+        stepNumber: child.props.stepNumber ?? index + 1,
+      })
+    }
+    return child
+  })
+  
+  return (
+    <StepsContext.Provider value={{ titleSize }}>
+      <div className={cn('my-6', className)}>
+        {numberedChildren}
+      </div>
+    </StepsContext.Provider>
+  )
+}

package/renderer/components/docs/mdx/tabs.tsx

@@ -0,0 +1,86 @@
+'use client'
+
+import React, { useState } from 'react'
+import { cn } from '@/lib/utils'
+
+/**
+ * Tabs Components for MDX Documentation
+ * 
+ * Mintlify-compatible tab components for organizing content.
+ */
+
+interface TabProps {
+  title: string
+  children: React.ReactNode
+  className?: string
+}
+
+interface TabsProps {
+  children: React.ReactNode
+  defaultValue?: string
+  className?: string
+}
+
+// Context for sharing tab state
+interface TabsContextValue {
+  activeTab: string
+  setActiveTab: (tab: string) => void
+}
+
+const TabsContext = React.createContext<TabsContextValue | null>(null)
+
+export function Tab({ children, className }: TabProps) {
+  // Tab content is rendered by Tabs parent
+  return <div className={className}>{children}</div>
+}
+
+export function Tabs({ children, defaultValue, className }: TabsProps) {
+  // Extract tab titles and content from children
+  const tabs: { title: string; content: React.ReactNode }[] = []
+  
+  React.Children.forEach(children, (child) => {
+    if (React.isValidElement<TabProps>(child) && child.type === Tab) {
+      tabs.push({
+        title: child.props.title,
+        content: child.props.children,
+      })
+    }
+  })
+  
+  const [activeTab, setActiveTab] = useState(defaultValue || tabs[0]?.title || '')
+  
+  const activeContent = tabs.find(tab => tab.title === activeTab)?.content
+  
+  return (
+    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
+      <div className={cn('my-4', className)}>
+        {/* Tab headers */}
+        <div className="flex border-b border-border overflow-x-auto">
+          {tabs.map((tab) => (
+            <button
+              key={tab.title}
+              type="button"
+              onClick={() => setActiveTab(tab.title)}
+              className={cn(
+                'px-4 py-2 text-sm font-medium whitespace-nowrap transition-colors',
+                'hover:text-foreground',
+                'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary/50',
+                'border-b-2 -mb-px',
+                activeTab === tab.title
+                  ? 'border-primary text-foreground'
+                  : 'border-transparent text-muted-foreground'
+              )}
+            >
+              {tab.title}
+            </button>
+          ))}
+        </div>
+        
+        {/* Tab content */}
+        <div className="pt-4">
+          {activeContent}
+        </div>
+      </div>
+    </TabsContext.Provider>
+  )
+}