specra 0.1.0

package/src/components/docs/math.tsx

@@ -0,0 +1,46 @@
+"use client"
+
+import { useEffect, useRef } from "react"
+
+interface MathProps {
+  children: string
+  block?: boolean
+}
+
+export function Math({ children, block = false }: MathProps) {
+  const containerRef = useRef<HTMLSpanElement | HTMLDivElement>(null)
+
+  useEffect(() => {
+    const renderMath = async () => {
+      try {
+        // Dynamically import KaTeX
+        const katex = (await import("katex")).default
+
+        if (containerRef.current) {
+          katex.render(children, containerRef.current, {
+            throwOnError: false,
+            displayMode: block,
+          })
+        }
+      } catch (err) {
+        console.error("KaTeX rendering error:", err)
+        if (containerRef.current) {
+          containerRef.current.textContent = children
+        }
+      }
+    }
+
+    renderMath()
+  }, [children, block])
+
+  if (block) {
+    return (
+      <div
+        ref={containerRef as React.RefObject<HTMLDivElement>}
+        className="my-6 overflow-x-auto text-center"
+      />
+    )
+  }
+
+  return <span ref={containerRef as React.RefObject<HTMLSpanElement>} className="inline-block" />
+}

package/src/components/docs/mdx-components.tsx

@@ -0,0 +1,166 @@
+import type { ReactNode } from "react"
+import { CodeBlock } from "./code-block"
+import { Callout } from "./callout"
+import { Accordion, AccordionItem } from "./accordion"
+import { Tabs, Tab } from "./tabs"
+import { Image } from "./image"
+import { Video } from "./video"
+import { Card, CardGrid } from "./card"
+import { ImageCard, ImageCardGrid } from "./image-card"
+import { Steps, Step } from "./steps"
+import { Icon } from "./icon"
+import { Mermaid } from "./mermaid"
+import { Math } from "./math"
+import { Columns, Column } from "./columns"
+import { Badge } from "./badge"
+import { Tooltip } from "./tooltip"
+import { Frame } from "./frame"
+import { ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference } from "./api"
+
+export const mdxComponents = {
+  h1: ({ children }: { children: ReactNode }) => (
+    <h1 className="text-3xl font-semibold tracking-tight mb-6 text-foreground">{children}</h1>
+  ),
+  h2: ({ children, id }: { children: ReactNode; id?: string }) => (
+    <h2 id={id} className="text-2xl font-semibold tracking-tight mt-10 mb-4 text-foreground scroll-mt-24">
+      {children}
+    </h2>
+  ),
+  h3: ({ children, id }: { children: ReactNode; id?: string }) => (
+    <h3 id={id} className="text-xl font-medium tracking-tight mt-8 mb-3 text-foreground scroll-mt-24">
+      {children}
+    </h3>
+  ),
+  p: ({ children }: { children: ReactNode }) => (
+    <p className="text-base leading-7 text-muted-foreground mb-4">{children}</p>
+  ),
+  code: ({ children, className, meta, ...props }: { children: ReactNode; className?: string; meta?: string; [key: string]: any }) => {
+    const isInline = !className
+    if (isInline) {
+      return (
+        <code className="px-1.5 py-0.5 rounded-md bg-muted/50 text-primary font-mono text-[13px] border border-border/50">
+          {children}
+        </code>
+      )
+    }
+    
+    // Extract language from className
+    const language = className?.replace("language-", "") || "text"
+    
+    // Use meta string as filename if provided
+    const filename = meta || undefined
+    
+    const code = String(children).replace(/\n$/, "")
+
+    return <CodeBlock code={code} language={language} filename={filename} />
+  },
+  pre: ({ children }: { children: ReactNode }) => <>{children}</>,
+  ul: ({ children }: { children: ReactNode }) => (
+    <ul className="list-disc list-outside pl-5 space-y-2 mb-4 text-muted-foreground [&_p]:mb-0 [&_p]:inline [&_ul]:ml-6 [&_ol]:ml-6">{children}</ul>
+  ),
+  ol: ({ children }: { children: ReactNode }) => (
+    <ol className="list-decimal list-outside pl-5 space-y-2 mb-4 text-muted-foreground [&_p]:mb-0 [&_p]:inline [&_ul]:ml-6 [&_ol]:ml-6">{children}</ol>
+  ),
+  li: ({ children }: { children: ReactNode }) => <li className="leading-7 [&>p]:mb-0 [&>p]:inline">{children}</li>,
+  a: ({ children, href }: { children: ReactNode; href?: string }) => (
+    <a
+      href={href}
+      className="text-primary hover:underline font-medium"
+      target={href?.startsWith("http") ? "_blank" : undefined}
+      rel={href?.startsWith("http") ? "noopener noreferrer" : undefined}
+    >
+      {children}
+    </a>
+  ),
+  blockquote: ({ children }: { children: ReactNode }) => {
+    // Check if this is a GitHub-style alert blockquote
+    const childrenArray = Array.isArray(children) ? children : [children]
+    const firstChild = childrenArray[0]
+
+    // Extract text content from the blockquote
+    let textContent = ""
+    if (firstChild && typeof firstChild === "object" && "props" in firstChild) {
+      const props = (firstChild as any).props
+      if (props.children) {
+        const text = Array.isArray(props.children) ? props.children.join("") : String(props.children)
+        textContent = text
+      }
+    }
+
+    // Check for alert patterns like [!INFO], [!WARNING], etc.
+    const alertMatch = textContent.match(/^\[!(INFO|TIP|WARNING|SUCCESS|ERROR)\]/)
+
+    if (alertMatch) {
+      const type = alertMatch[1].toLowerCase() as "info" | "tip" | "warning" | "success" | "error"
+
+      // Extract the content after the alert marker
+      const processChildren = (node: any): any => {
+        if (typeof node === "string") {
+          return node.replace(/^\[!(INFO|TIP|WARNING|SUCCESS|ERROR)\]\s*\n?/, "")
+        }
+        if (node && typeof node === "object" && "props" in node) {
+          return {
+            ...node,
+            props: {
+              ...node.props,
+              children: Array.isArray(node.props.children)
+                ? node.props.children.map(processChildren)
+                : processChildren(node.props.children),
+            },
+          }
+        }
+        return node
+      }
+
+      const cleanedChildren = Array.isArray(children) ? children.map(processChildren) : processChildren(children)
+
+      return <Callout type={type}>{cleanedChildren}</Callout>
+    }
+
+    // Regular blockquote
+    return (
+      <blockquote className="border-l-4 border-primary/50 bg-muted/30 pl-4 pr-4 py-3 my-6 rounded-r-lg">
+        <div className="text-muted-foreground italic [&>p]:mb-0">{children}</div>
+      </blockquote>
+    )
+  },
+  table: ({ children }: { children: ReactNode }) => (
+    <div className="overflow-x-auto mb-6 rounded-xl border border-border">
+      <table className="min-w-full border-collapse">{children}</table>
+    </div>
+  ),
+  th: ({ children }: { children: ReactNode }) => (
+    <th className="border-b border-r border-border bg-muted px-4 py-2 text-left font-semibold text-foreground last:border-r-0">{children}</th>
+  ),
+  td: ({ children }: { children: ReactNode }) => (
+    <td className="border-b border-r border-border px-4 py-2 text-muted-foreground last:border-r-0">{children}</td>
+  ),
+  // Custom components
+  Callout,
+  Accordion,
+  AccordionItem,
+  Tabs,
+  Tab,
+  Image,
+  Video,
+  Card,
+  CardGrid,
+  ImageCard,
+  ImageCardGrid,
+  Steps,
+  Step,
+  Icon,
+  Mermaid,
+  Math,
+  Columns,
+  Column,
+  Badge,
+  Tooltip,
+  Frame,
+  // API Documentation components
+  ApiEndpoint,
+  ApiParams,
+  ApiResponse,
+  ApiPlayground,
+  ApiReference,
+}

package/src/components/docs/mdx-hot-reload.tsx

@@ -0,0 +1,37 @@
+"use client"
+
+import { useEffect } from "react"
+import { useRouter } from "next/navigation"
+
+export function MdxHotReload() {
+  const router = useRouter()
+
+  useEffect(() => {
+    if (process.env.NODE_ENV !== "development") return
+
+    // Use Server-Sent Events to watch for file changes
+    const eventSource = new EventSource('/api/mdx-watch')
+
+    eventSource.onmessage = (event) => {
+      const data = JSON.parse(event.data)
+      
+      if (data.type === 'change') {
+        console.log('[MDX Hot Reload] File changed:', data.file)
+        router.refresh()
+      } else if (data.type === 'connected') {
+        console.log('[MDX Hot Reload] Watching for changes...')
+      }
+    }
+
+    eventSource.onerror = (error) => {
+      console.error('[MDX Hot Reload] Connection error:', error)
+      eventSource.close()
+    }
+
+    return () => {
+      eventSource.close()
+    }
+  }, [router])
+
+  return null
+}

package/src/components/docs/mermaid.tsx

@@ -0,0 +1,77 @@
+"use client"
+
+import { useEffect, useRef, useState } from "react"
+
+interface MermaidProps {
+  chart: string
+  caption?: string
+}
+
+export function Mermaid({ chart, caption }: MermaidProps) {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    const renderChart = async () => {
+      try {
+        // Dynamically import mermaid
+        const mermaid = (await import("mermaid")).default
+
+        mermaid.initialize({
+          startOnLoad: false,
+          theme: document.documentElement.classList.contains("dark") ? "dark" : "default",
+          securityLevel: "loose",
+          fontFamily: "inherit",
+        })
+
+        if (containerRef.current) {
+          const id = `mermaid-${Math.random().toString(36).substr(2, 9)}`
+          const { svg } = await mermaid.render(id, chart)
+          containerRef.current.innerHTML = svg
+        }
+      } catch (err) {
+        console.error("Mermaid rendering error:", err)
+        setError(err instanceof Error ? err.message : "Failed to render diagram")
+      }
+    }
+
+    renderChart()
+
+    // Re-render on theme change
+    const observer = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        if (mutation.attributeName === "class") {
+          renderChart()
+        }
+      })
+    })
+
+    observer.observe(document.documentElement, { attributes: true })
+
+    return () => observer.disconnect()
+  }, [chart])
+
+  if (error) {
+    return (
+      <div className="my-6 p-4 rounded-xl border border-red-500/50 bg-red-500/10">
+        <p className="text-sm text-red-600 dark:text-red-400 font-mono">
+          Mermaid Error: {error}
+        </p>
+      </div>
+    )
+  }
+
+  return (
+    <figure className="my-6">
+      <div
+        ref={containerRef}
+        className="flex justify-center items-center p-6 rounded-xl border border-border bg-muted/30 overflow-x-auto"
+      />
+      {caption && (
+        <figcaption className="mt-2 text-center text-sm text-muted-foreground italic">
+          {caption}
+        </figcaption>
+      )}
+    </figure>
+  )
+}

package/src/components/docs/mobile-doc-layout.tsx

@@ -0,0 +1,115 @@
+"use client"
+
+import { useState, ReactNode, cloneElement, isValidElement } from "react"
+import { Footer } from "./footer"
+import { SiteBanner } from "./site-banner"
+import { TabGroups } from "./tab-groups"
+import { Sidebar } from "./sidebar"
+import type { SpecraConfig } from "@/lib/config"
+import type { Doc } from "@/lib/mdx"
+
+interface MobileDocLayoutProps {
+  header: ReactNode
+  docs: Doc[]
+  version: string
+  content: ReactNode
+  toc: ReactNode
+  config: SpecraConfig
+  activeTabGroup?: string
+  onTabChange?: (tabId: string) => void
+}
+
+export function MobileDocLayout({ header, docs, version, content, toc, config, activeTabGroup, onTabChange }: MobileDocLayoutProps) {
+  const [sidebarOpen, setSidebarOpen] = useState(false)
+
+  const handleTabChange = (tabId: string) => {
+    onTabChange?.(tabId)
+  }
+
+  const closeSidebar = () => setSidebarOpen(false)
+  const toggleSidebar = () => setSidebarOpen(!sidebarOpen)
+
+  // Clone header and pass onMenuClick prop if it's a valid React element
+  const headerWithProps = isValidElement(header)
+    ? cloneElement(header as React.ReactElement<any>, {
+      onMenuClick: toggleSidebar,
+    })
+    : header
+
+  return (
+    <div className="min-h-screen bg-background">
+      {/* Header */}
+      {headerWithProps}
+
+      {/* Site-wide Banner */}
+      <SiteBanner config={config} />
+
+      {/* Tab Groups - shown only if configured */}
+      {config.navigation?.tabGroups && config.navigation.tabGroups.length > 0 && (
+        <TabGroups
+          tabGroups={config.navigation.tabGroups}
+          activeTabId={activeTabGroup}
+          onTabChange={handleTabChange}
+        />
+      )}
+
+      {/* Mobile Sidebar Overlay */}
+      {sidebarOpen && (
+        <div
+          className="lg:hidden fixed inset-0 bg-background/80 backdrop-blur-sm z-40"
+          onClick={() => setSidebarOpen(false)}
+        />
+      )}
+
+      {/* Mobile Sidebar */}
+      <div
+        className={`lg:hidden fixed top-0 left-0 h-full w-64 bg-background border-r border-border z-40 transform transition-transform duration-300 ease-in-out overflow-y-auto ${sidebarOpen ? "translate-x-0" : "-translate-x-full"
+          }`}
+      >
+        <div className="pt-20 px-4">
+          <Sidebar
+            docs={docs}
+            version={version}
+            config={config}
+            onLinkClick={closeSidebar}
+            activeTabGroup={activeTabGroup}
+          />
+        </div>
+      </div>
+
+      {/* Main Content */}
+      <main className="container mx-auto px-6 py-8">
+        <div className="flex">
+          {/* Desktop Sidebar */}
+          <div className="hidden lg:block">
+            <Sidebar
+              docs={docs}
+              version={version}
+              config={config}
+              activeTabGroup={activeTabGroup}
+            />
+          </div>
+
+          <div className="flex-1 min-w-0">
+            <div className="flex flex-col gap-2 px-2 md:px-8">
+              {/* Content */}
+              {content}
+
+              {/* Footer */}
+              <Footer config={config} />
+
+            </div>
+          </div>
+
+          {/* ToC */}
+          {toc}
+        </div>
+
+
+      </main>
+
+
+
+    </div>
+  )
+}

package/src/components/docs/not-found-content.tsx

@@ -0,0 +1,55 @@
+"use client"
+
+import Link from "next/link"
+import { AlertTriangle, Home, ArrowLeft } from "lucide-react"
+
+interface NotFoundContentProps {
+  version: string
+}
+
+export function NotFoundContent({ version }: NotFoundContentProps) {
+  return (
+    <div className="flex min-h-[calc(100vh-12rem)] items-center justify-center px-4 py-12">
+      <div className="w-full max-w-2xl text-center">
+        <div className="mb-6 flex justify-center">
+          <div className="rounded-full bg-yellow-500/10 p-4">
+            <AlertTriangle className="h-16 w-16 text-yellow-500" />
+          </div>
+        </div>
+
+        <h1 className="mb-3 text-5xl font-bold tracking-tight">404</h1>
+        <h2 className="mb-4 text-2xl font-semibold">Page Not Found</h2>
+
+        <p className="mb-8 text-base text-muted-foreground">
+          The documentation page you're looking for doesn't exist or may have been moved.
+          <br />
+          Try using the sidebar to find what you're looking for, or return to the documentation home.
+        </p>
+
+        <div className="flex flex-col items-center justify-center gap-3 sm:flex-row">
+          <Link
+            href={`/docs/${version}`}
+            className="inline-flex items-center gap-2 rounded-lg bg-primary px-6 py-3 text-sm font-medium text-primary-foreground hover:bg-primary/90 transition-colors"
+          >
+            <ArrowLeft className="h-4 w-4" />
+            Back to Documentation
+          </Link>
+
+          <Link
+            href="/"
+            className="inline-flex items-center gap-2 rounded-lg border border-border bg-background px-6 py-3 text-sm font-medium hover:bg-muted transition-colors"
+          >
+            <Home className="h-4 w-4" />
+            Go to Homepage
+          </Link>
+        </div>
+
+        <div className="mt-12 rounded-lg border border-border bg-muted/30 p-6">
+          <p className="text-sm text-muted-foreground">
+            <strong className="font-medium text-foreground">Tip:</strong> Use the sidebar navigation on the left to browse all available documentation pages.
+          </p>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/docs/search-highlight.tsx

@@ -0,0 +1,127 @@
+"use client"
+
+import { useEffect } from "react"
+import { useSearchParams } from "next/navigation"
+
+export function SearchHighlight() {
+  const searchParams = useSearchParams()
+  const query = searchParams.get("q")
+
+  useEffect(() => {
+    if (!query) {
+      // Remove any existing highlights
+      document.querySelectorAll("mark.search-highlight").forEach((mark) => {
+        const parent = mark.parentNode
+        if (parent) {
+          parent.replaceChild(document.createTextNode(mark.textContent || ""), mark)
+          parent.normalize()
+        }
+      })
+      return
+    }
+
+    // Wait for content to load
+    const timeout = setTimeout(() => {
+      highlightSearchTerm(query)
+    }, 100)
+
+    return () => {
+      clearTimeout(timeout)
+      // Cleanup highlights on unmount
+      document.querySelectorAll("mark.search-highlight").forEach((mark) => {
+        const parent = mark.parentNode
+        if (parent) {
+          parent.replaceChild(document.createTextNode(mark.textContent || ""), mark)
+          parent.normalize()
+        }
+      })
+    }
+  }, [query])
+
+  return null
+}
+
+function highlightSearchTerm(searchTerm: string) {
+  // Remove existing highlights first
+  document.querySelectorAll("mark.search-highlight").forEach((mark) => {
+    const parent = mark.parentNode
+    if (parent) {
+      parent.replaceChild(document.createTextNode(mark.textContent || ""), mark)
+      parent.normalize()
+    }
+  })
+
+  // Only highlight in the main content area
+  const contentArea = document.querySelector("main") || document.body
+  
+  const walker = document.createTreeWalker(
+    contentArea,
+    NodeFilter.SHOW_TEXT,
+    {
+      acceptNode: (node) => {
+        // Skip if parent is already a mark, script, style, or code element
+        const parent = node.parentElement
+        if (!parent) return NodeFilter.FILTER_REJECT
+        
+        const tagName = parent.tagName.toLowerCase()
+        if (["mark", "script", "style", "code", "pre"].includes(tagName)) {
+          return NodeFilter.FILTER_REJECT
+        }
+        
+        // Check if text contains the search term
+        if (node.textContent && node.textContent.toLowerCase().includes(searchTerm.toLowerCase())) {
+          return NodeFilter.FILTER_ACCEPT
+        }
+        
+        return NodeFilter.FILTER_REJECT
+      }
+    }
+  )
+
+  const nodesToHighlight: { node: Text; text: string }[] = []
+  let currentNode: Node | null
+
+  while ((currentNode = walker.nextNode())) {
+    if (currentNode.textContent) {
+      nodesToHighlight.push({
+        node: currentNode as Text,
+        text: currentNode.textContent
+      })
+    }
+  }
+
+  // Highlight all found nodes
+  nodesToHighlight.forEach(({ node, text }) => {
+    const regex = new RegExp(`(${escapeRegex(searchTerm)})`, "gi")
+    const parts = text.split(regex)
+    
+    if (parts.length > 1) {
+      const fragment = document.createDocumentFragment()
+      
+      parts.forEach((part) => {
+        if (part.toLowerCase() === searchTerm.toLowerCase()) {
+          const mark = document.createElement("mark")
+          mark.className = "search-highlight bg-yellow-200 dark:bg-yellow-900/50 text-foreground px-1 rounded"
+          mark.textContent = part
+          fragment.appendChild(mark)
+        } else if (part) {
+          fragment.appendChild(document.createTextNode(part))
+        }
+      })
+      
+      node.parentNode?.replaceChild(fragment, node)
+    }
+  })
+
+  // Scroll to first highlight
+  const firstHighlight = document.querySelector("mark.search-highlight")
+  if (firstHighlight) {
+    setTimeout(() => {
+      firstHighlight.scrollIntoView({ behavior: "smooth", block: "center" })
+    }, 200)
+  }
+}
+
+function escapeRegex(string: string) {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}