specra 0.1.0

package/src/app/docs-page.tsx

@@ -0,0 +1,212 @@
+import type { Metadata } from "next"
+import { extractTableOfContents, getAdjacentDocs, isCategoryPage } from "../lib/mdx"
+import { getCachedVersions, getCachedAllDocs, getCachedDocBySlug } from "../lib/mdx-cache"
+import { DocLayout } from "../components/docs/doc-layout"
+import { TableOfContents } from "../components/docs/table-of-contents"
+import { Header } from "../components/docs/header"
+import { DocLayoutWrapper } from "../components/docs/doc-layout-wrapper"
+import { HotReloadIndicator } from "../components/docs/hot-reload-indicator"
+import { DevModeBadge } from "../components/docs/dev-mode-badge"
+import { MdxHotReload } from "../components/docs/mdx-hot-reload"
+import { CategoryIndex } from "../components/docs/category-index"
+import { NotFoundContent } from "../components/docs/not-found-content"
+import { getConfig } from "../lib/config"
+import { Suspense } from "react"
+import { DocLoading } from "../components/docs/doc-loading"
+
+interface PageProps {
+  params: Promise<{
+    version: string
+    slug: string[]
+  }>
+}
+
+/**
+ * Generate metadata for documentation pages
+ * This is exported so users can re-export it from their page.tsx
+ */
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { version, slug: slugArray } = await params
+  const slug = slugArray.join("/")
+
+  const doc = await getCachedDocBySlug(slug, version)
+
+  if (!doc) {
+    return {
+      title: "Page Not Found",
+      description: "The requested documentation page could not be found.",
+    }
+  }
+
+  const title = doc.meta.title || doc.title
+  const description = doc.meta.description || `Documentation for ${title}`
+  const url = `/docs/${version}/${slug}`
+
+  return {
+    title: `${title}`,
+    description,
+    openGraph: {
+      title,
+      description,
+      url,
+      siteName: "Documentation Platform",
+      type: "article",
+      locale: "en_US",
+    },
+    twitter: {
+      card: "summary_large_image",
+      title,
+      description,
+    },
+    alternates: {
+      canonical: url,
+    },
+  }
+}
+
+/**
+ * Generate static params for all documentation pages
+ * This enables static generation at build time
+ */
+export async function generateStaticParams() {
+  const versions = getCachedVersions()
+  const params = []
+
+  for (const version of versions) {
+    const docs = await getCachedAllDocs(version)
+    for (const doc of docs) {
+      // Add the custom slug path
+      params.push({
+        version,
+        slug: doc.slug.split("/").filter(Boolean),
+      })
+    }
+  }
+
+  return params
+}
+
+/**
+ * Documentation page component
+ * Handles:
+ * - Regular documentation pages
+ * - Category index pages (with or without content)
+ * - 404 pages (when doc not found)
+ */
+export default async function DocPage({ params }: PageProps) {
+  const { version, slug: slugArray } = await params
+  const slug = slugArray.join("/")
+
+  const allDocs = await getCachedAllDocs(version)
+  const versions = getCachedVersions()
+  const config = getConfig()
+  const isCategory = isCategoryPage(slug, allDocs)
+
+  // Try to get the doc (might be index.mdx or regular .mdx)
+  const doc = await getCachedDocBySlug(slug, version)
+
+  // If no doc found and it's a category, show category index
+  if (!doc && isCategory) {
+    // Find a doc in this category to get the tab group
+    const categoryDoc = allDocs.find((d) => d.slug.startsWith(slug + "/"))
+    const categoryTabGroup = categoryDoc?.meta?.tab_group || categoryDoc?.categoryTabGroup
+
+    return (
+      <>
+        <DocLayoutWrapper
+          header={<Header currentVersion={version} versions={versions} config={config} />}
+          docs={allDocs}
+          version={version}
+          content={
+            <CategoryIndex
+              categoryPath={slug}
+              version={version}
+              allDocs={allDocs}
+              title={slug.split("/").pop()?.replace(/-/g, " ").replace(/\b\w/g, (l) => l.toUpperCase()) || "Category"}
+              description="Browse the documentation in this section."
+              config={config}
+            />
+          }
+          toc={<div />}
+          config={config}
+          currentPageTabGroup={categoryTabGroup}
+        />
+        <MdxHotReload />
+        <HotReloadIndicator />
+        <DevModeBadge />
+      </>
+    )
+  }
+
+  // If no doc found, render 404 content within the layout (keeps sidebar visible)
+  if (!doc) {
+    return (
+      <>
+        <Suspense fallback={<DocLoading />}>
+          <DocLayoutWrapper
+            header={<Header currentVersion={version} versions={versions} config={config} />}
+            docs={allDocs}
+            version={version}
+            content={<NotFoundContent version={version} />}
+            toc={<div />}
+            config={config}
+            currentPageTabGroup={undefined}
+          />
+          <MdxHotReload />
+          <HotReloadIndicator />
+          <DevModeBadge />
+        </Suspense>
+      </>
+    )
+  }
+
+  const toc = extractTableOfContents(doc.content)
+  const { previous, next } = getAdjacentDocs(slug, allDocs)
+
+  // If doc exists but is also a category, show both content and children
+  const showCategoryIndex = isCategory && doc
+
+  // Get current page's tab group from doc metadata or category
+  const currentPageTabGroup = doc.meta?.tab_group || doc.categoryTabGroup
+
+  return (
+    <>
+      <Suspense fallback={<DocLoading />}>
+        <DocLayoutWrapper
+          header={<Header currentVersion={version} versions={versions} config={config} />}
+          docs={allDocs}
+          version={version}
+          content={
+            showCategoryIndex ? (
+              <CategoryIndex
+                categoryPath={slug}
+                version={version}
+                allDocs={allDocs}
+                title={doc.meta.title}
+                description={doc.meta.description}
+                content={doc.content}
+                config={config}
+              />
+            ) : (
+              <DocLayout
+                meta={doc.meta}
+                content={doc.content}
+                previousDoc={previous ? { title: previous.meta.title, slug: previous.slug } : undefined}
+                nextDoc={next ? { title: next.meta.title, slug: next.slug } : undefined}
+                version={version}
+                slug={slug}
+                config={config}
+              />
+            )
+          }
+          toc={showCategoryIndex ? <div /> : <TableOfContents items={toc} config={config} />}
+          config={config}
+          currentPageTabGroup={currentPageTabGroup}
+        />
+        <MdxHotReload />
+        <HotReloadIndicator />
+        <DevModeBadge />
+      </Suspense>
+    </>
+  )
+}

package/src/app/layout.tsx

@@ -0,0 +1,74 @@
+import type React from "react"
+import type { Metadata } from "next"
+import { Geist, Geist_Mono } from "next/font/google"
+import { getConfig } from "../lib/config"
+import { getAssetPath } from "../lib/utils"
+import { TabProvider } from "../components/docs/tab-context"
+import "../styles/globals.css"
+
+const geist = Geist({ subsets: ["latin"] })
+const geistMono = Geist_Mono({ subsets: ["latin"] })
+
+/**
+ * Generate metadata for the root layout
+ * This can be imported and used by the user's app/layout.tsx
+ */
+export function generateMetadata(): Metadata {
+  const config = getConfig()
+
+  return {
+    title: {
+      default: config.site.title,
+      template: `%s | ${config.site.title}`,
+    },
+    description: config.site.description || "Modern documentation platform",
+    generator: "Specra Documentation",
+    metadataBase: config.site.url ? new URL(config.site.url) : undefined,
+    icons: {
+      icon: getAssetPath(config.site.favicon ?? "") ? [
+        {
+          url: getAssetPath(config.site.favicon ?? ""),
+        },
+      ] : [],
+      apple: getAssetPath("/apple-icon.png"),
+    },
+    openGraph: {
+      title: config.site.title,
+      description: config.site.description,
+      url: config.site.url,
+      siteName: config.site.title,
+      locale: config.site.language || "en",
+      type: "website",
+    },
+    twitter: {
+      card: "summary_large_image",
+      title: config.site.title,
+      description: config.site.description,
+    },
+  }
+}
+
+export const metadata: Metadata = generateMetadata()
+
+/**
+ * Root layout component for Specra documentation sites
+ * This provides the HTML structure and global providers
+ */
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode
+}>) {
+  const config = getConfig()
+  const defaultTab = config.navigation?.tabGroups?.[0]?.id || ""
+
+  return (
+    <html lang={config.site.language || "en"} suppressHydrationWarning>
+      <body className={`${geist.className} font-sans antialiased`}>
+        <TabProvider defaultTab={defaultTab}>
+          {children}
+        </TabProvider>
+      </body>
+    </html>
+  )
+}

package/src/components/docs/accordion.tsx

@@ -0,0 +1,53 @@
+"use client"
+
+import { ChevronDown } from "lucide-react"
+import { useState } from "react"
+
+interface AccordionItemProps {
+  title: string | React.ReactNode
+  children: React.ReactNode
+  defaultOpen?: boolean
+  value?: string  // For compatibility with radix-ui style API
+}
+
+export function AccordionItem({ title, children, defaultOpen = false }: AccordionItemProps) {
+  const [isOpen, setIsOpen] = useState(defaultOpen)
+
+  return (
+    <div className="border border-border rounded-xl overflow-hidden mb-2">
+      <button
+        onClick={() => setIsOpen(!isOpen)}
+        className="w-full flex items-center justify-between p-4 text-left bg-muted/30 hover:bg-muted/50 transition-colors"
+      >
+        <span className="font-medium text-foreground">{title}</span>
+        <ChevronDown
+          className={`h-5 w-5 text-muted-foreground transition-transform ${
+            isOpen ? "rotate-180" : ""
+          }`}
+        />
+      </button>
+      {isOpen && (
+        <div className="p-4 border-t border-border bg-background">
+          <div className="prose prose-sm dark:prose-invert max-w-none [&>*:last-child]:mb-0">
+            {children}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+interface AccordionProps {
+  children: React.ReactNode
+  type?: "single" | "multiple"
+  collapsible?: boolean  // For compatibility with radix-ui style API
+  className?: string
+}
+
+export function Accordion({ children, type = "multiple", className }: AccordionProps) {
+  return (
+    <div className={className || "my-6 space-y-2"}>
+      {children}
+    </div>
+  )
+}

package/src/components/docs/api/api-endpoint.tsx

@@ -0,0 +1,59 @@
+"use client"
+
+import { type ReactNode, useState } from "react"
+import { ChevronDown } from "lucide-react"
+import { cn } from "@/lib/utils"
+
+interface ApiEndpointProps {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
+  path: string
+  summary?: string
+  children?: ReactNode
+  defaultOpen?: boolean
+}
+
+const methodColors = {
+  GET: "bg-blue-500/10 text-blue-600 dark:text-blue-400",
+  POST: "bg-green-500/10 text-green-600 dark:text-green-400",
+  PUT: "bg-orange-500/10 text-orange-600 dark:text-orange-400",
+  PATCH: "bg-purple-500/10 text-purple-600 dark:text-purple-400",
+  DELETE: "bg-red-500/10 text-red-600 dark:text-red-400",
+}
+
+export function ApiEndpoint({ method, path, summary, children, defaultOpen = false }: ApiEndpointProps) {
+  const [isOpen, setIsOpen] = useState(defaultOpen)
+
+  return (
+    <div className="not-prose mb-4 rounded-xl border border-border overflow-hidden">
+      {/* Accordion Header */}
+      <button
+        onClick={() => setIsOpen(!isOpen)}
+        className="w-full flex items-center gap-3 px-4 py-3 text-left bg-muted/30 hover:bg-muted/50 transition-colors"
+      >
+        <span
+          className={cn(
+            "text-xs font-semibold px-2 py-0.5 rounded",
+            methodColors[method]
+          )}
+        >
+          {method}
+        </span>
+        <code className="text-sm font-mono">{path}</code>
+        {summary && <span className="text-sm text-muted-foreground ml-auto mr-2">{summary}</span>}
+        <ChevronDown
+          className={cn(
+            "h-5 w-5 text-muted-foreground transition-transform flex-shrink-0",
+            isOpen ? "rotate-180" : ""
+          )}
+        />
+      </button>
+
+      {/* Accordion Content */}
+      {isOpen && children && (
+        <div className="border-t border-border bg-background">
+          <div className="px-4 py-4 space-y-6">{children}</div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/docs/api/api-params.tsx

@@ -0,0 +1,43 @@
+interface ApiParam {
+  name: string
+  type: string
+  required?: boolean
+  description?: string
+  default?: string
+}
+
+interface ApiParamsProps {
+  title?: string
+  params: ApiParam[]
+}
+
+export function ApiParams({ title = "Parameters", params }: ApiParamsProps) {
+  if (!params || params.length === 0) return null
+
+  return (
+    <div className="mb-6">
+      <h4 className="text-sm font-semibold text-foreground mb-3">{title}</h4>
+      <div className="space-y-3">
+        {params.map((param) => (
+          <div key={param.name} className="flex flex-col gap-1">
+            <div className="flex items-center gap-2">
+              <code className="text-sm font-mono text-foreground">{param.name}</code>
+              <span className="text-xs text-muted-foreground">{param.type}</span>
+              {param.required && (
+                <span className="text-xs text-red-600 dark:text-red-400">required</span>
+              )}
+              {param.default && (
+                <span className="text-xs text-muted-foreground">
+                  default: <code className="text-xs">{param.default}</code>
+                </span>
+              )}
+            </div>
+            {param.description && (
+              <p className="text-sm text-muted-foreground">{param.description}</p>
+            )}
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}

package/src/components/docs/api/api-playground.tsx

@@ -0,0 +1,233 @@
+"use client"
+
+import { useState, useMemo } from "react"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Textarea } from "@/components/ui/textarea"
+import { Badge } from "@/components/ui/badge"
+import { CodeBlock } from "../code-block"
+import { Play, Loader2 } from "lucide-react"
+
+interface PathParam {
+  name: string
+  type: string
+  example?: any
+}
+
+interface ApiPlaygroundProps {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
+  path: string
+  baseUrl?: string
+  headers?: Record<string, string>
+  defaultBody?: string
+  pathParams?: PathParam[]
+}
+
+export function ApiPlayground({
+  method,
+  path,
+  baseUrl = "",
+  headers = {},
+  defaultBody,
+  pathParams = []
+}: ApiPlaygroundProps) {
+  const [loading, setLoading] = useState(false)
+  const [response, setResponse] = useState<any>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [requestBody, setRequestBody] = useState(defaultBody || "")
+
+  // Initialize headers with empty strings if not provided
+  const initialHeaders = useMemo(() => {
+    const cleanHeaders: Record<string, string> = {}
+    Object.entries(headers).forEach(([key, value]) => {
+      cleanHeaders[key] = value || ""
+    })
+    return cleanHeaders
+  }, [headers])
+
+  const [requestHeaders, setRequestHeaders] = useState(JSON.stringify(initialHeaders, null, 2))
+
+  // Extract path parameters and initialize with defaults
+  const extractedParams = useMemo(() => {
+    const params: Record<string, string> = {}
+    const pathParamPattern = /:(\w+)/g
+    let match
+
+    while ((match = pathParamPattern.exec(path)) !== null) {
+      const paramName = match[1]
+      const paramConfig = pathParams.find(p => p.name === paramName)
+
+      // Set default value based on example or type
+      if (paramConfig?.example !== undefined) {
+        params[paramName] = String(paramConfig.example)
+      } else if (paramConfig?.type === "number") {
+        params[paramName] = "1"
+      } else {
+        params[paramName] = ""
+      }
+    }
+
+    return params
+  }, [path, pathParams])
+
+  const [pathParamValues, setPathParamValues] = useState<Record<string, string>>(extractedParams)
+
+  // Build the final URL with path params replaced
+  const buildUrl = () => {
+    let finalPath = path
+    Object.entries(pathParamValues).forEach(([key, value]) => {
+      finalPath = finalPath.replace(`:${key}`, value)
+    })
+    return `${baseUrl}${finalPath}`
+  }
+
+  const handleSend = async () => {
+    setLoading(true)
+    setError(null)
+    setResponse(null)
+
+    try {
+      const url = buildUrl()
+      const parsedHeaders = JSON.parse(requestHeaders)
+
+      const options: RequestInit = {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          ...parsedHeaders,
+        },
+      }
+
+      if (method !== "GET" && method !== "DELETE" && requestBody) {
+        options.body = requestBody
+      }
+
+      const res = await fetch(url, options)
+      const data = await res.json()
+
+      setResponse({
+        status: res.status,
+        statusText: res.statusText,
+        headers: Object.fromEntries(res.headers.entries()),
+        body: data,
+      })
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "An error occurred")
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div className="not-prose border border-border rounded-lg overflow-hidden bg-card/30">
+      <div className="bg-muted/50 px-4 py-2 border-b border-border">
+        <h4 className="text-sm font-semibold text-foreground">API Playground</h4>
+      </div>
+
+      <div className="p-4 space-y-4">
+        {/* Path Parameters */}
+        {Object.keys(pathParamValues).length > 0 && (
+          <div>
+            <label className="text-xs font-semibold text-muted-foreground mb-2 block">
+              Path Parameters
+            </label>
+            <div className="space-y-2">
+              {Object.entries(pathParamValues).map(([paramName, paramValue]) => {
+                const paramConfig = pathParams.find(p => p.name === paramName)
+                return (
+                  <div key={paramName} className="flex items-center gap-2">
+                    <span className="text-xs text-muted-foreground min-w-[80px]">
+                      :{paramName}
+                    </span>
+                    <Input
+                      value={paramValue}
+                      onChange={(e) =>
+                        setPathParamValues((prev) => ({ ...prev, [paramName]: e.target.value }))
+                      }
+                      placeholder={paramConfig?.example || paramConfig?.type || "value"}
+                      className="font-mono text-sm"
+                    />
+                  </div>
+                )
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* URL */}
+        <div>
+          <label className="text-xs font-semibold text-muted-foreground mb-2 block">
+            Request URL
+          </label>
+          <div className="flex items-center gap-2">
+            <Badge variant="outline" className="font-mono">
+              {method}
+            </Badge>
+            <Input value={buildUrl()} readOnly className="font-mono text-sm" />
+          </div>
+        </div>
+
+        {/* Headers */}
+        <div>
+          <label className="text-xs font-semibold text-muted-foreground mb-2 block">
+            Headers (JSON)
+          </label>
+          <Textarea
+            value={requestHeaders}
+            onChange={(e) => setRequestHeaders(e.target.value)}
+            className="font-mono text-sm"
+            rows={4}
+          />
+        </div>
+
+        {/* Body (for POST, PUT, PATCH) */}
+        {method !== "GET" && method !== "DELETE" && (
+          <div>
+            <label className="text-xs font-semibold text-muted-foreground mb-2 block">
+              Request Body (JSON)
+            </label>
+            <Textarea
+              value={requestBody}
+              onChange={(e) => setRequestBody(e.target.value)}
+              className="font-mono text-sm"
+              rows={6}
+              placeholder='{\n  "key": "value"\n}'
+            />
+          </div>
+        )}
+
+        {/* Send Button */}
+        <Button onClick={handleSend} disabled={loading} className="w-full">
+          {loading ? (
+            <>
+              <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+              Sending...
+            </>
+          ) : (
+            <>
+              <Play className="mr-2 h-4 w-4" />
+              Send Request
+            </>
+          )}
+        </Button>
+
+        {/* Response */}
+        {response && (
+          <div className="mt-4">
+            <label className="text-xs font-semibold text-muted-foreground mb-2 block">
+              Response ({response.status} {response.statusText})
+            </label>
+            <CodeBlock code={JSON.stringify(response.body, null, 2)} language="json" />
+          </div>
+        )}
+
+        {/* Error */}
+        {error && (
+          <div className="mt-4 p-3 bg-red-500/10 border border-red-500/20 rounded-md">
+            <p className="text-sm text-red-600 dark:text-red-400">{error}</p>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}