@brainfish-ai/devdoc 0.1.21 → 0.1.23

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

@@ -15,7 +15,6 @@ import { CollectionTree } from './collection-tree'
 import { SidebarSection } from './sidebar-section'
 import { SidebarItem, SlidingIndicatorProvider } from './sidebar-item'
 import { SidebarGroup } from './sidebar-group'
-import { extractMarkdownHeadings, type MarkdownHeading } from '@/lib/api-docs/utils'
 import { useMobile } from '@/lib/api-docs/mobile-context'
 import { cn } from '@/lib/utils'
 
@@ -84,92 +83,8 @@ export function DocsSidebar({
     }
   }
   
-  // Extract documentation headings from collection description
-  const docHeadings = useMemo(() => {
-    return collection.description 
-      ? extractMarkdownHeadings(collection.description)
-      : []
-  }, [collection.description])
-  
   // Get doc groups from collection
   const docGroups = collection.docGroups || []
-
-  const handleDocClick = (headingId: string) => {
-    handleDocClickWithClose(headingId)
-  }
-  
-  // Determine if Introduction should be highlighted
-  const isIntroductionSelected = !selectedRequest && !selectedDocSection && !selectedDocPage
-
-  // Check if a heading or any of its children is selected
-  const isHeadingSelected = (heading: MarkdownHeading): boolean => {
-    if (selectedDocSection === heading.id) return true
-    if (heading.children?.some(child => selectedDocSection === child.id)) return true
-    return false
-  }
-  
-  // Get the selected child heading ID for a heading group
-  const getSelectedChildHeading = (heading: MarkdownHeading): string | null => {
-    if (selectedDocSection === heading.id) return heading.id
-    const selected = heading.children?.find(child => selectedDocSection === child.id)
-    return selected?.id || null
-  }
-
-  // Render a documentation heading item (may have children)
-  const renderHeading = (heading: MarkdownHeading, index: number) => {
-    const hasChildren = heading.children && heading.children.length > 0
-    const isSelected = selectedDocSection === heading.id
-    
-    // If heading is "Introduction", handle it specially
-    if (heading.text === 'Introduction') {
-      return (
-        <SidebarItem
-          key={`${heading.id}-${index}`}
-          itemId={`heading-introduction`}
-          selected={isIntroductionSelected}
-          onClick={() => handleDocClick('introduction')}
-        >
-          Introduction
-        </SidebarItem>
-      )
-    }
-    
-    if (hasChildren) {
-      return (
-        <SidebarGroup
-          key={`${heading.id}-${index}`}
-          title={heading.text}
-          defaultOpen={isHeadingSelected(heading)}
-          selected={isSelected}
-          selectedChildSlug={getSelectedChildHeading(heading)}
-          onClick={() => handleDocClick(heading.id)}
-        >
-          {heading.children!.map((child, childIndex) => (
-            <SidebarItem
-              key={`${child.id}-${childIndex}`}
-              itemId={`heading-${child.id}`}
-              selected={selectedDocSection === child.id}
-              indent={1}
-              onClick={() => handleDocClick(child.id)}
-            >
-              {child.text}
-            </SidebarItem>
-          ))}
-        </SidebarGroup>
-      )
-    }
-    
-    return (
-      <SidebarItem
-        key={`${heading.id}-${index}`}
-        itemId={`heading-${heading.id}`}
-        selected={isSelected}
-        onClick={() => handleDocClick(heading.id)}
-      >
-        {heading.text}
-      </SidebarItem>
-    )
-  }
   
   // Check if any child in a group is selected
   const isChildSelected = (page: BrainfishDocPage): boolean => {
@@ -300,14 +215,7 @@ export function DocsSidebar({
 
         {/* Scrollable content with sliding indicator */}
         <SlidingIndicatorProvider className="docs-sidebar-content flex-1 overflow-y-auto overflow-x-hidden custom-scroll">
-          {/* Documentation Section (from description headings) - Only shown in API Reference tab */}
-          {activeTab === 'api-reference' && docHeadings.length > 0 && (
-            <SidebarSection title="Documentation">
-              {docHeadings.map((heading, index) => renderHeading(heading, index))}
-            </SidebarSection>
-          )}
-          
-          {/* Documentation Pages Section (from docs.json) */}
+          {/* Documentation Pages Section (from docs.json groups) */}
           {docGroups.length > 0 && (
             <>
               {docGroups.map((group, index) => (
@@ -315,7 +223,7 @@ export function DocsSidebar({
                   key={group.id} 
                   title={group.title}
                   icon={group.icon}
-                  className={index > 0 || (activeTab === 'api-reference' && docHeadings.length > 0) ? '' : ''}
+                  className={index > 0 ? '' : ''}
                 >
                   {group.pages.map(renderDocPage)}
                 </SidebarSection>
@@ -327,7 +235,7 @@ export function DocsSidebar({
           {(collection.folders.length > 0 || collection.requests.length > 0) && (
             <SidebarSection 
               title="Endpoints" 
-              className={((activeTab === 'api-reference' && docHeadings.length > 0) || docGroups.length > 0) ? 'border-t border-sidebar-border' : ''}
+              className={docGroups.length > 0 ? 'border-t border-sidebar-border' : ''}
             >
               <CollectionTree
                 collection={collection}

package/renderer/components/docs-viewer/sidebar/sidebar-item.tsx

@@ -2,21 +2,7 @@
 
 import { ReactNode, useRef, useEffect, useLayoutEffect, useState, createContext, useContext } from 'react'
 import { cn } from '@/lib/utils'
-import * as PhosphorIcons from '@phosphor-icons/react'
-
-// Helper to get Phosphor icon component from name
-function getIcon(iconName?: string): React.ComponentType<{ className?: string; weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone" }> | null {
-  if (!iconName) return null
-  
-  // Convert kebab-case to PascalCase for Phosphor icons
-  const pascalCase = iconName
-    .split('-')
-    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
-    .join('')
-  
-  const IconComponent = (PhosphorIcons as Record<string, unknown>)[pascalCase] as React.ComponentType<{ className?: string; weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone" }> | undefined
-  return IconComponent || null
-}
+import { getPhosphorIcon } from '@/lib/utils/icons'
 
 // Context for the sliding indicator
 interface SlidingIndicatorContextType {
@@ -152,7 +138,7 @@ export function SidebarItem({
   const buttonRef = useRef<HTMLButtonElement>(null)
   const context = useContext(SlidingIndicatorContext)
   const id = itemId || String(children)
-  const IconComponent = getIcon(icon)
+  const IconComponent = getPhosphorIcon(icon)
 
   // Register this item with the sliding indicator provider
   useEffect(() => {

package/renderer/components/docs-viewer/sidebar/sidebar-section.tsx

@@ -2,7 +2,7 @@
 
 import { ReactNode } from 'react'
 import { cn } from '@/lib/utils'
-import * as PhosphorIcons from '@phosphor-icons/react'
+import { getPhosphorIcon } from '@/lib/utils/icons'
 
 interface SidebarSectionProps {
   title: string
@@ -12,25 +12,11 @@ interface SidebarSectionProps {
   icon?: string
 }
 
-// Map of common icon names to Phosphor components
-function getIcon(iconName?: string): React.ComponentType<{ className?: string; weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone" }> | null {
-  if (!iconName) return null
-  
-  // Convert kebab-case to PascalCase for Phosphor icons
-  const pascalCase = iconName
-    .split('-')
-    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
-    .join('')
-  
-  const IconComponent = (PhosphorIcons as Record<string, unknown>)[pascalCase] as React.ComponentType<{ className?: string; weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone" }> | undefined
-  return IconComponent || null
-}
-
 /**
  * Sidebar Section component - groups items under a title with optional icon
  */
 export function SidebarSection({ title, children, className = '', icon }: SidebarSectionProps) {
-  const IconComponent = getIcon(icon)
+  const IconComponent = getPhosphorIcon(icon)
   
   return (
     <div className={cn('docs-sidebar-section flex flex-col', className)}>

package/renderer/lib/api-docs/factories.ts

@@ -11,39 +11,61 @@ import type {
 } from './types'
 
 /**
- * Generates a unique ID for collections and requests
- * If a seed is provided, generates a deterministic hash-based ID
+ * Generates a URL-friendly slug from a string
+ * Converts to lowercase, replaces spaces and special chars with hyphens
  */
-function generateUniqueId(prefix: string, seed?: string): string {
-  if (seed) {
-    // Generate deterministic ID from seed using simple hash
-    let hash = 0
-    for (let i = 0; i < seed.length; i++) {
-      const char = seed.charCodeAt(i)
-      hash = ((hash << 5) - hash) + char
-      hash = hash & hash // Convert to 32bit integer
-    }
-    // Convert to positive number and base36
-    const hashStr = Math.abs(hash).toString(36)
-    return `${prefix}_${hashStr}`
+function slugify(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/[{}]/g, '') // Remove braces from path params
+    .replace(/[^a-z0-9]+/g, '-') // Replace non-alphanumeric with hyphens
+    .replace(/^-+|-+$/g, '') // Remove leading/trailing hyphens
+    .replace(/-+/g, '-') // Collapse multiple hyphens
+}
+
+/**
+ * Generates a human-readable, deterministic ID for requests
+ * Uses operationId if available, otherwise method + path
+ */
+function generateRequestId(method: string, path: string, operationId?: string): string {
+  if (operationId) {
+    // Use operationId directly (it's already unique per spec)
+    return slugify(operationId)
+  }
+  
+  // Generate from method + path: "get-users-id" for "GET /users/{id}"
+  const pathSlug = slugify(path)
+  return `${method.toLowerCase()}-${pathSlug}`
+}
+
+/**
+ * Generates a unique ID for collections
+ * If a seed is provided, generates a deterministic slug-based ID
+ */
+function generateCollectionId(name?: string): string {
+  if (name) {
+    return `coll-${slugify(name)}`
   }
-  return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
+  return `coll_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
 }
 
 /**
  * Creates a BrainfishRESTRequest with defaults
- * If method and endpoint are provided, generates a deterministic ID
+ * Generates human-readable, deterministic IDs based on operationId or method+path
  */
 export function makeBrainfishRESTRequest(
-  request: Omit<BrainfishRESTRequest, 'id'>
+  request: Omit<BrainfishRESTRequest, 'id'> & { operationId?: string }
 ): BrainfishRESTRequest {
-  // Generate deterministic ID from method + endpoint
-  const idSeed = request.method && request.endpoint 
-    ? `${request.method}:${request.endpoint}` 
-    : undefined
+  // Extract path from endpoint (remove base URL)
+  const path = request.endpoint 
+    ? request.endpoint.replace(/^https?:\/\/[^/]+/, '') || '/'
+    : '/'
+  
+  // Generate human-readable ID
+  const id = generateRequestId(request.method || 'GET', path, request.operationId)
   
   return {
-    id: generateUniqueId('req', idSeed),
+    id,
     name: request.name || 'Untitled Request',
     description: request.description ?? null,
     method: request.method || 'GET',
@@ -65,11 +87,8 @@ export function makeBrainfishRESTRequest(
 export function makeBrainfishCollection(
   collection: Omit<BrainfishCollection, 'id'>
 ): BrainfishCollection {
-  // Generate deterministic ID from collection name
-  const idSeed = collection.name ? `collection:${collection.name}` : undefined
-  
   return {
-    id: generateUniqueId('coll', idSeed),
+    id: generateCollectionId(collection.name),
     name: collection.name || 'Untitled Collection',
     description: collection.description ?? null,
     folders: collection.folders || [],

package/renderer/lib/api-docs/parsers/graphql/parser.ts

@@ -238,7 +238,7 @@ function extractOperations(
   const fields = rootType.getFields()
   
   return Object.values(fields).map(field => ({
-    id: `${operationType}-${field.name}`,
+    id: `${operationType}-${field.name}`.toLowerCase(),
     name: field.name,
     description: field.description || null,
     operationType,

package/renderer/lib/api-docs/parsers/openapi/transformer.ts

@@ -178,6 +178,7 @@ function convertPathToBrainfishReqs(
         requestVariables,
         responses,
         tags: (info as any).tags ?? [],
+        operationId: (info as any).operationId ?? undefined,
       })
 
       return {

package/renderer/lib/docs/config/schema.ts

@@ -58,6 +58,16 @@ const openapiTabSchema = z.object({
   path: z.string().optional(),
   versions: z.array(openapiVersionSchema).optional(),
   spec: z.string().optional(),
+  groups: z.array(groupSchema).optional(), // Doc groups alongside API reference
+})
+
+const graphqlTabSchema = z.object({
+  tab: z.string(),
+  type: z.literal('graphql'),
+  path: z.string().optional(),
+  schema: z.string(), // GraphQL schema file path
+  endpoint: z.string().optional(), // GraphQL endpoint URL
+  groups: z.array(groupSchema).optional(), // Doc groups alongside API reference
 })
 
 const changelogTabSchema = z.object({
@@ -66,7 +76,7 @@ const changelogTabSchema = z.object({
   path: z.string().optional(),
 })
 
-const tabSchema = z.union([docsTabSchema, openapiTabSchema, changelogTabSchema])
+const tabSchema = z.union([docsTabSchema, openapiTabSchema, graphqlTabSchema, changelogTabSchema])
 
 const navigationSchema = z.object({
   tabs: z.array(tabSchema).optional(),

package/renderer/lib/docs/mdx/frontmatter.ts

@@ -17,8 +17,19 @@ export const frontmatterSchema = z.object({
   icon: z.string().optional(),
   
   // Page behavior
+  // - 'default': Standard documentation page with max-width container
+  // - 'wide': Wide container for content that needs more space
+  // - 'custom': Full-width custom layout (no container, no header) - for landing pages
   mode: z.enum(['default', 'wide', 'custom']).optional(),
   
+  // Custom page options (only used when mode: 'custom')
+  // Hides the default page header (title & description)
+  hideHeader: z.boolean().optional(),
+  // Full-width layout without container constraints
+  fullWidth: z.boolean().optional(),
+  // Custom background color or gradient
+  background: z.string().optional(),
+  
   // OpenAPI integration
   openapi: z.string().optional(),
   api: z.string().optional(),

package/renderer/lib/utils/icons.ts

@@ -0,0 +1,48 @@
+import * as PhosphorIcons from '@phosphor-icons/react'
+
+export type PhosphorIconWeight = 'thin' | 'light' | 'regular' | 'bold' | 'fill' | 'duotone'
+
+export type PhosphorIconComponent = React.ComponentType<{
+  className?: string
+  weight?: PhosphorIconWeight
+}>
+
+/**
+ * Get a Phosphor icon component by its kebab-case name
+ * 
+ * @param iconName - The icon name in kebab-case (e.g., "arrow-right", "github-logo")
+ * @returns The Phosphor icon component or null if not found
+ * 
+ * @example
+ * const Icon = getPhosphorIcon('arrow-right')
+ * if (Icon) {
+ *   return <Icon className="h-5 w-5" weight="bold" />
+ * }
+ */
+export function getPhosphorIcon(iconName?: string): PhosphorIconComponent | null {
+  if (!iconName) return null
+  
+  // Convert kebab-case to PascalCase for Phosphor icons
+  const pascalCase = iconName
+    .split('-')
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+  
+  const IconComponent = (PhosphorIcons as Record<string, unknown>)[pascalCase]
+  
+  if (typeof IconComponent === 'function') {
+    return IconComponent as PhosphorIconComponent
+  }
+  
+  return null
+}
+
+/**
+ * Check if a Phosphor icon exists by name
+ * 
+ * @param iconName - The icon name in kebab-case
+ * @returns true if the icon exists
+ */
+export function hasPhosphorIcon(iconName?: string): boolean {
+  return getPhosphorIcon(iconName) !== null
+}

package/renderer/components/docs-viewer/content/introduction.tsx

@@ -1,21 +0,0 @@
-'use client'
-
-import { MarkdownRenderer } from '../shared/markdown-renderer'
-import type { BrainfishCollection } from '@/lib/api-docs/types'
-
-interface IntroductionProps {
-  collection: BrainfishCollection
-}
-
-export function Introduction({ collection }: IntroductionProps) {
-  return (
-    <div className="docs-introduction docs-content max-w-4xl mx-auto px-4 py-6 sm:px-8 sm:py-8">
-      <h1 className="docs-content-title text-2xl sm:text-3xl font-bold mb-4 sm:mb-6 text-foreground">{collection.name}</h1>
-      {collection.description && (
-        <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">
-          <MarkdownRenderer content={collection.description} />
-        </div>
-      )}
-    </div>
-  )
-}