specra 0.1.0

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

@@ -0,0 +1,291 @@
+"use client"
+
+import { useState, useEffect } from "react"
+import type { SpecraApiSpec } from "@/lib/api-parser.types"
+import { parseApiSpec, type ParserType } from "@/lib/parsers"
+import { Accordion, AccordionItem } from "../accordion"
+import { ApiEndpoint } from "./api-endpoint"
+import { ApiParams } from "./api-params"
+import { ApiResponse } from "./api-response"
+import { ApiPlayground } from "./api-playground"
+import { CodeBlock } from "../code-block"
+import { Loader2 } from "lucide-react"
+
+interface ApiReferenceProps {
+  /**
+   * Path to the API spec JSON file (relative to /public)
+   * Example: "/api-specs/my-api.json"
+   */
+  spec: string
+
+  /**
+   * Parser type - auto-detect by default
+   * - "auto": Auto-detect format (Specra, OpenAPI, or Postman)
+   * - "specra": Native Specra format
+   * - "openapi": OpenAPI 3.x / Swagger
+   * - "postman": Postman Collection v2.x
+   */
+  parser?: ParserType
+
+  /**
+   * Show API playground for testing
+   */
+  showPlayground?: boolean
+}
+
+export function ApiReference({ spec, parser = "auto", showPlayground = true }: ApiReferenceProps) {
+  const [apiSpec, setApiSpec] = useState<SpecraApiSpec | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    async function loadSpec() {
+      try {
+        const response = await fetch(spec)
+        if (!response.ok) {
+          throw new Error(`Failed to load API spec: ${response.statusText}`)
+        }
+        const data = await response.json()
+
+        // Parse using the appropriate parser
+        const parsedSpec = parseApiSpec(data, parser)
+        setApiSpec(parsedSpec)
+      } catch (err) {
+        setError(err instanceof Error ? err.message : "Failed to load API spec")
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    loadSpec()
+  }, [spec, parser])
+
+  // Replace environment variables in text
+  const interpolateEnv = (text: string, env?: Record<string, string>): string => {
+    if (!env) return text
+    return text.replace(/\{(\w+)\}/g, (match, key) => {
+      return env[key] || match
+    })
+  }
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center py-12">
+        <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
+        <span className="ml-2 text-muted-foreground">Loading API specification...</span>
+      </div>
+    )
+  }
+
+  if (error) {
+    return (
+      <div className="rounded-lg border border-red-500/20 bg-red-500/10 p-4">
+        <p className="text-sm text-red-600 dark:text-red-400">Error: {error}</p>
+      </div>
+    )
+  }
+
+  if (!apiSpec) {
+    return null
+  }
+
+  return (
+    <div className="space-y-6">
+      {/* API Info */}
+      {(apiSpec.title || apiSpec.description) && (
+        <div className="mb-8">
+          {apiSpec.title && (
+            <h2 className="text-2xl font-semibold mb-2 text-foreground">{apiSpec.title}</h2>
+          )}
+          {apiSpec.description && (
+            <p className="text-muted-foreground">{apiSpec.description}</p>
+          )}
+          {apiSpec.baseUrl && (
+            <div className="mt-4">
+              <p className="text-sm font-semibold text-muted-foreground mb-1">Base URL</p>
+              <code className="text-sm px-2 py-1 bg-muted rounded">{apiSpec.baseUrl}</code>
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Authentication */}
+      {apiSpec.auth && (
+        <div className="rounded-lg border border-border bg-card/30 p-4 mb-6">
+          <h3 className="text-lg font-semibold mb-2 text-foreground">Authentication</h3>
+          <p className="text-sm text-muted-foreground mb-2">
+            {apiSpec.auth.description || `This API uses ${apiSpec.auth.type} authentication.`}
+          </p>
+          {apiSpec.auth.type === "bearer" && (
+            <CodeBlock
+              code={`Authorization: ${apiSpec.auth.tokenPrefix || "Bearer"} {YOUR_TOKEN}`}
+              language="bash"
+            />
+          )}
+          {apiSpec.auth.type === "apiKey" && (
+            <CodeBlock
+              code={`${apiSpec.auth.headerName || "X-API-Key"}: {YOUR_API_KEY}`}
+              language="bash"
+            />
+          )}
+        </div>
+      )}
+
+      {/* Endpoints as Accordion */}
+      <Accordion type="single" collapsible className="space-y-4">
+        {apiSpec.endpoints.map((endpoint, index) => {
+          // Merge global and endpoint-specific headers
+          const allHeaders = [
+            ...(apiSpec.globalHeaders || []),
+            ...(endpoint.headers || []),
+          ].map((header) => ({
+            ...header,
+            value: interpolateEnv(header.value, apiSpec.env),
+          }))
+
+          return (
+            <AccordionItem
+              key={index}
+              value={`endpoint-${index}`}
+              title={
+                <div className="flex items-center gap-3">
+                  <span
+                    className={`text-xs font-semibold px-2 py-0.5 rounded ${
+                      endpoint.method === "GET"
+                        ? "bg-blue-500/10 text-blue-600 dark:text-blue-400"
+                        : endpoint.method === "POST"
+                        ? "bg-green-500/10 text-green-600 dark:text-green-400"
+                        : endpoint.method === "PUT"
+                        ? "bg-orange-500/10 text-orange-600 dark:text-orange-400"
+                        : endpoint.method === "PATCH"
+                        ? "bg-purple-500/10 text-purple-600 dark:text-purple-400"
+                        : "bg-red-500/10 text-red-600 dark:text-red-400"
+                    }`}
+                  >
+                    {endpoint.method}
+                  </span>
+                  <code className="text-sm font-mono">{endpoint.path}</code>
+                  <span className="text-sm text-muted-foreground ml-auto">{endpoint.title}</span>
+                </div>
+              }
+            >
+              <div className="space-y-6 pt-4">
+                {/* Description */}
+                {endpoint.description && (
+                  <p className="text-sm text-muted-foreground">{endpoint.description}</p>
+                )}
+
+                {/* Path Parameters */}
+                {endpoint.pathParams && endpoint.pathParams.length > 0 && (
+                  <ApiParams title="Path Parameters" params={endpoint.pathParams} />
+                )}
+
+                {/* Query Parameters */}
+                {endpoint.queryParams && endpoint.queryParams.length > 0 && (
+                  <ApiParams title="Query Parameters" params={endpoint.queryParams} />
+                )}
+
+                {/* Headers */}
+                {allHeaders.length > 0 && (
+                  <div>
+                    <h4 className="text-sm font-semibold text-foreground mb-3">Headers</h4>
+                    <div className="space-y-2">
+                      {allHeaders.map((header, idx) => (
+                        <div key={idx} className="flex flex-col gap-1">
+                          <div className="flex items-center gap-2">
+                            <code className="text-sm font-mono text-foreground">{header.name}</code>
+                            <span className="text-xs text-muted-foreground">{header.value}</span>
+                          </div>
+                          {header.description && (
+                            <p className="text-sm text-muted-foreground">{header.description}</p>
+                          )}
+                        </div>
+                      ))}
+                    </div>
+                  </div>
+                )}
+
+                {/* Request Body */}
+                {endpoint.body && (
+                  <div>
+                    <h4 className="text-sm font-semibold text-foreground mb-3">Request Body</h4>
+                    {endpoint.body.description && (
+                      <p className="text-sm text-muted-foreground mb-2">
+                        {endpoint.body.description}
+                      </p>
+                    )}
+                    {endpoint.body.example && (
+                      <CodeBlock
+                        code={
+                          typeof endpoint.body.example === "string"
+                            ? endpoint.body.example
+                            : JSON.stringify(endpoint.body.example, null, 2)
+                        }
+                        language="json"
+                      />
+                    )}
+                  </div>
+                )}
+
+                {/* Responses */}
+                <div>
+                  <h4 className="text-sm font-semibold text-foreground mb-3">Responses</h4>
+                  {endpoint.successResponse && (
+                    <ApiResponse
+                      status={endpoint.successResponse.status}
+                      description={endpoint.successResponse.description}
+                      example={endpoint.successResponse.example}
+                      schema={endpoint.successResponse.schema}
+                    />
+                  )}
+                  {endpoint.errorResponses?.map((response, idx) => (
+                    <ApiResponse
+                      key={idx}
+                      status={response.status}
+                      description={response.description}
+                      example={response.example}
+                      schema={response.schema}
+                    />
+                  ))}
+                </div>
+
+                {/* Code Examples */}
+                {endpoint.examples && endpoint.examples.length > 0 && (
+                  <div>
+                    <h4 className="text-sm font-semibold text-foreground mb-3">Examples</h4>
+                    {endpoint.examples.map((example, idx) => (
+                      <div key={idx} className="mb-3">
+                        <p className="text-xs font-semibold text-muted-foreground mb-2">
+                          {example.title}
+                        </p>
+                        <CodeBlock code={example.code} language={example.language} />
+                      </div>
+                    ))}
+                  </div>
+                )}
+
+                {/* API Playground */}
+                {showPlayground && (
+                  <ApiPlayground
+                    method={endpoint.method}
+                    path={endpoint.path}
+                    baseUrl={apiSpec.baseUrl}
+                    headers={Object.fromEntries(allHeaders.map((h) => [h.name, h.value]))}
+                    pathParams={endpoint.pathParams}
+                    defaultBody={
+                      endpoint.body?.example
+                        ? typeof endpoint.body.example === "string"
+                          ? endpoint.body.example
+                          : JSON.stringify(endpoint.body.example, null, 2)
+                        : undefined
+                    }
+                  />
+                )}
+              </div>
+            </AccordionItem>
+          )
+        })}
+      </Accordion>
+    </div>
+  )
+}

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

@@ -0,0 +1,48 @@
+import { CodeBlock } from "../code-block"
+
+interface ApiResponseProps {
+  status: number
+  description?: string
+  example?: any
+  schema?: any
+}
+
+const statusColors: Record<string, string> = {
+  "2": "text-green-600 dark:text-green-400",
+  "3": "text-blue-600 dark:text-blue-400",
+  "4": "text-orange-600 dark:text-orange-400",
+  "5": "text-red-600 dark:text-red-400",
+}
+
+export function ApiResponse({ status, description, example, schema }: ApiResponseProps) {
+  const statusClass = statusColors[String(status)[0]] || "text-muted-foreground"
+
+  return (
+    <div className="mb-4">
+      <div className="flex items-center gap-2 mb-2">
+        <span className={`text-sm font-semibold ${statusClass}`}>{status}</span>
+        {description && <span className="text-sm text-muted-foreground">{description}</span>}
+      </div>
+
+      {example && (
+        <div className="mb-3">
+          <p className="text-xs font-semibold text-muted-foreground mb-2">Example Response</p>
+          <CodeBlock
+            code={typeof example === "string" ? example : JSON.stringify(example, null, 2)}
+            language="json"
+          />
+        </div>
+      )}
+
+      {schema && (
+        <div>
+          <p className="text-xs font-semibold text-muted-foreground mb-2">Schema</p>
+          <CodeBlock
+            code={typeof schema === "string" ? schema : JSON.stringify(schema, null, 2)}
+            language="json"
+          />
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/docs/api/index.ts

@@ -0,0 +1,5 @@
+export { ApiEndpoint } from "./api-endpoint"
+export { ApiParams } from "./api-params"
+export { ApiResponse as ApiResponseDisplay, ApiResponse } from "./api-response"
+export { ApiPlayground } from "./api-playground"
+export { ApiReference } from "./api-reference"

package/src/components/docs/badge.tsx

@@ -0,0 +1,22 @@
+interface BadgeProps {
+  children: React.ReactNode
+  variant?: "default" | "success" | "warning" | "error" | "info"
+}
+
+export function Badge({ children, variant = "default" }: BadgeProps) {
+  const variants = {
+    default: "bg-muted text-foreground border-border",
+    success: "bg-green-500/10 text-green-600 dark:text-green-400 border-green-500/20",
+    warning: "bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 border-yellow-500/20",
+    error: "bg-red-500/10 text-red-600 dark:text-red-400 border-red-500/20",
+    info: "bg-blue-500/10 text-blue-600 dark:text-blue-400 border-blue-500/20",
+  }
+
+  return (
+    <span
+      className={`inline-flex items-center px-2 py-0.5 rounded-md text-xs font-medium border ${variants[variant]}`}
+    >
+      {children}
+    </span>
+  )
+}

package/src/components/docs/breadcrumb.tsx

@@ -0,0 +1,51 @@
+import Link from "next/link"
+import { ChevronRight } from "lucide-react"
+
+interface BreadcrumbProps {
+  version: string
+  slug: string
+  title: string
+}
+
+export function Breadcrumb({ version, slug, title }: BreadcrumbProps) {
+  const parts = slug.split("/")
+  const breadcrumbs = [
+    { label: "Docs", href: `/docs/${version}` },
+  ]
+
+  // Build breadcrumb path
+  let currentPath = ""
+  for (let i = 0; i < parts.length - 1; i++) {
+    currentPath += (currentPath ? "/" : "") + parts[i]
+    breadcrumbs.push({
+      label: parts[i].replace(/-/g, " ").replace(/\b\w/g, (l) => l.toUpperCase()),
+      href: `/docs/${version}/${currentPath}`,
+    })
+  }
+
+  // Add current page
+  breadcrumbs.push({
+    label: title,
+    href: `/docs/${version}/${slug}`,
+  })
+
+  return (
+    <nav className="flex items-center gap-2 text-sm text-muted-foreground mb-4" aria-label="Breadcrumb">
+      {breadcrumbs.map((crumb, index) => (
+        <div key={crumb.href} className="flex items-center gap-2">
+          {index > 0 && <ChevronRight className="h-4 w-4" />}
+          {index === breadcrumbs.length - 1 ? (
+            <span className="text-foreground font-medium">{crumb.label}</span>
+          ) : (
+            <Link
+              href={crumb.href}
+              className="hover:text-foreground transition-colors"
+            >
+              {crumb.label}
+            </Link>
+          )}
+        </div>
+      ))}
+    </nav>
+  )
+}

package/src/components/docs/callout.tsx

@@ -0,0 +1,109 @@
+"use client"
+
+import type { ReactNode } from "react"
+import { Info, AlertTriangle, CheckCircle2, XCircle, Lightbulb } from "lucide-react"
+
+interface CalloutProps {
+  children: ReactNode
+  type?: "info" | "warning" | "success" | "error" | "tip" | "note" | "danger"
+  title?: string
+}
+
+export function Callout({ children, type = "info", title }: CalloutProps) {
+  const configs = {
+    info: {
+      icon: Info,
+      className: "bg-blue-500/10 border-blue-500/30 text-blue-900 dark:bg-blue-400/5 dark:border-blue-500/20 dark:text-blue-400",
+      iconClassName: "text-blue-600 dark:text-blue-400",
+      titleClassName: "text-blue-700 dark:text-blue-300",
+      defaultTitle: "Info",
+    },
+    note: {
+      icon: Info,
+      className: "bg-blue-500/10 border-blue-500/30 text-blue-900 dark:bg-blue-400/5 dark:border-blue-500/20 dark:text-blue-400",
+      iconClassName: "text-blue-600 dark:text-blue-400",
+      titleClassName: "text-blue-700 dark:text-blue-300",
+      defaultTitle: "Note",
+    },
+    warning: {
+      icon: AlertTriangle,
+      className: "bg-yellow-500/10 border-yellow-500/30 text-yellow-900 dark:bg-yellow-400/5 dark:border-yellow-500/20 dark:text-yellow-400",
+      iconClassName: "text-yellow-600 dark:text-yellow-400",
+      titleClassName: "text-yellow-700 dark:text-yellow-300",
+      defaultTitle: "Warning",
+    },
+    success: {
+      icon: CheckCircle2,
+      className: "bg-green-500/10 border-green-500/30 text-green-900 dark:bg-green-400/5 dark:border-green-500/20 dark:text-green-400",
+      iconClassName: "text-green-600 dark:text-green-400",
+      titleClassName: "text-green-700 dark:text-green-300",
+      defaultTitle: "Success",
+    },
+    error: {
+      icon: XCircle,
+      className: "bg-red-500/10 border-red-500/30 text-red-900 dark:bg-red-400/5 dark:border-red-500/20 dark:text-red-400",
+      iconClassName: "text-red-600 dark:text-red-400",
+      titleClassName: "text-red-700 dark:text-red-300",
+      defaultTitle: "Error",
+    },
+    danger: {
+      icon: XCircle,
+      className: "bg-red-500/10 border-red-500/30 text-red-900 dark:bg-red-400/5 dark:border-red-500/20 dark:text-red-400",
+      iconClassName: "text-red-600 dark:text-red-400",
+      titleClassName: "text-red-700 dark:text-red-300",
+      defaultTitle: "Danger",
+    },
+    tip: {
+      icon: Lightbulb,
+      className: "bg-purple-500/10 border-purple-500/30 text-purple-900 dark:bg-purple-400/5 dark:border-purple-500/20 dark:text-purple-400",
+      iconClassName: "text-purple-600 dark:text-purple-400",
+      titleClassName: "text-purple-700 dark:text-purple-300",
+      defaultTitle: "Tip",
+    },
+  }
+
+  const config = configs[type]
+  const Icon = config.icon
+
+  // Extract title from strong/bold text if present, but ONLY if no explicit title prop was provided
+  let _title = title || config.defaultTitle
+  let content = children
+
+  if (!title && children && typeof children === "object") {
+    const childArray = Array.isArray(children) ? children : [children]
+    const firstElement = childArray[0]
+
+    // Check if first child is a paragraph with a strong element
+    if (firstElement && typeof firstElement === "object" && "props" in firstElement) {
+      const props = (firstElement as any).props
+      if (props.children && Array.isArray(props.children)) {
+        const strongChild = props.children.find(
+          (child: any) => child && typeof child === "object" && child.type === "strong",
+        )
+        if (strongChild) {
+          _title = strongChild.props.children
+          // Remove the title from content
+          content = childArray.map((child, idx) => {
+            if (idx === 0 && typeof child === "object" && "props" in child) {
+              const newChildren = (child as any).props.children.filter((c: any) => c !== strongChild)
+              return { ...child, props: { ...(child as any).props, children: newChildren } }
+            }
+            return child
+          })
+        }
+      }
+    }
+  }
+
+  return (
+    <div className={`flex gap-3 p-4 rounded-xl border my-2 ${config.className}`}>
+      <div className="flex-shrink-0 mt-0.5">
+        <Icon className={`h-5 w-5 ${config.iconClassName}`} />
+      </div>
+      <div className="flex-1 space-y-0">
+        <div className={`font-semibold text-sm ${config.titleClassName}`}>{_title}</div>
+        <div className="text-sm leading-relaxed [&>p]:mb-0 [&>p]:text-current">{content}</div>
+      </div>
+    </div>
+  )
+}

package/src/components/docs/card.tsx

@@ -0,0 +1,84 @@
+import { ArrowRight, ExternalLink } from "lucide-react"
+import Link from "next/link"
+import { Icon } from "./icon"
+
+interface CardProps {
+  title: string
+  description?: string
+  href?: string
+  icon?: string | React.ReactNode
+  children?: React.ReactNode
+  external?: boolean
+}
+
+export function Card({ title, description, href, icon, children, external = false }: CardProps) {
+  const content = (
+    <>
+      <div className="flex items-center gap-3">
+        {icon && (
+          <div className="shrink-0 w-10 h-10 rounded-xl bg-primary/10 flex items-center justify-center text-primary">
+            {typeof icon === "string" ? <Icon icon={icon} size={20} /> : icon}
+          </div>
+        )}
+        <div className="flex-1 min-w-0">
+          <h3 className={`font-semibold text-foreground mb-1 no-underline ${href ? 'group-hover:text-primary transition-colors' : ''}`}>
+            {title}
+          </h3>
+          {description && (
+            <p className="text-sm text-muted-foreground line-clamp-2 no-underline">{description}</p>
+          )}
+          {children && (
+            <div className="mt-2 text-sm text-muted-foreground no-underline">{children}</div>
+          )}
+        </div>
+        {href && (
+          <div className="shrink-0 self-start mt-1">
+            {external ? (
+              <ExternalLink className="h-4 w-4 text-muted-foreground group-hover:text-primary transition-colors" />
+            ) : (
+              <ArrowRight className="h-4 w-4 text-muted-foreground group-hover:text-primary group-hover:translate-x-1 transition-all" />
+            )}
+          </div>
+        )}
+      </div>
+    </>
+  )
+
+  if (href) {
+    const Component = external ? "a" : Link
+    return (
+      <Component
+        href={href}
+        className="card-link group block p-4 rounded-xl border border-border hover:border-primary/50 hover:bg-muted/50 transition-all"
+        {...(external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+      >
+        {content}
+      </Component>
+    )
+  }
+
+  return (
+    <div className="p-4 rounded-xl border border-border bg-muted/30 no-underline">
+      {content}
+    </div>
+  )
+}
+
+interface CardGridProps {
+  children: React.ReactNode
+  cols?: 1 | 2 | 3
+}
+
+export function CardGrid({ children, cols = 2 }: CardGridProps) {
+  const gridCols = {
+    1: "grid-cols-1",
+    2: "grid-cols-1 md:grid-cols-2",
+    3: "grid-cols-1 md:grid-cols-2 lg:grid-cols-3",
+  }
+
+  return (
+    <div className={`grid ${gridCols[cols]} gap-4 my-6`}>
+      {children}
+    </div>
+  )
+}