specra 0.1.0

package/src/components/docs/doc-navigation.tsx

@@ -0,0 +1,62 @@
+import Link from "next/link"
+import { ChevronLeft, ChevronRight } from "lucide-react"
+
+interface DocNavigationProps {
+  previousDoc?: {
+    title: string
+    slug: string
+  }
+  nextDoc?: {
+    title: string
+    slug: string
+  }
+  version: string
+}
+
+export function DocNavigation({ previousDoc, nextDoc, version }: DocNavigationProps) {
+  if (!previousDoc && !nextDoc) return null
+
+  return (
+    <div className="mt-12 pt-8 border-t border-border grid grid-cols-2 gap-4">
+      {previousDoc ? (
+        <Link
+          href={`/docs/${version}/${previousDoc.slug}`}
+          className="group flex flex-col gap-2 p-4 rounded-xl border border-border hover:border-primary/50 hover:bg-muted/50 transition-all"
+          style={{
+            textDecoration: "none !important"
+          }}
+        >
+          <div className="flex items-center gap-2 text-sm text-muted-foreground">
+            <ChevronLeft className="h-4 w-4" />
+            <span>Previous</span>
+          </div>
+          <div className="text-base font-medium text-foreground group-hover:text-primary transition-colors">
+            {previousDoc.title}
+          </div>
+        </Link>
+      ) : (
+        <div />
+      )}
+
+      {nextDoc ? (
+        <Link
+          href={`/docs/${version}/${nextDoc.slug}`}
+          className="group flex flex-col gap-2 p-4 rounded-xl border border-border hover:border-primary/50 hover:bg-muted/50 transition-all text-right"
+          style={{
+            textDecoration: "none !important"
+          }}
+        >
+          <div className="flex items-center justify-end gap-2 text-sm text-muted-foreground">
+            <span>Next</span>
+            <ChevronRight className="h-4 w-4" />
+          </div>
+          <div className="text-base font-medium text-foreground group-hover:text-primary transition-colors">
+            {nextDoc.title}
+          </div>
+        </Link>
+      ) : (
+        <div />
+      )}
+    </div>
+  )
+}

package/src/components/docs/doc-tags.tsx

@@ -0,0 +1,25 @@
+import { Tag } from "lucide-react"
+
+interface DocTagsProps {
+  tags: string[]
+}
+
+export function DocTags({ tags }: DocTagsProps) {
+  if (!tags || tags.length === 0) {
+    return null
+  }
+
+  return (
+    <div className="flex flex-wrap items-center gap-2 mt-6 pt-6 border-t border-border">
+      <Tag className="h-4 w-4 text-muted-foreground" />
+      {tags.map((tag) => (
+        <span
+          key={tag}
+          className="inline-flex items-center px-2.5 py-0.5 rounded-md text-xs font-medium bg-primary/10 text-primary border border-primary/20"
+        >
+          {tag}
+        </span>
+      ))}
+    </div>
+  )
+}

package/src/components/docs/draft-badge.tsx

@@ -0,0 +1,10 @@
+import { FileWarning } from "lucide-react"
+
+export function DraftBadge() {
+  return (
+    <div className="inline-flex items-center gap-2 px-3 py-1.5 rounded-md bg-yellow-500/10 border border-yellow-500/20 text-yellow-600 dark:text-yellow-400 text-sm font-medium mb-4">
+      <FileWarning className="h-4 w-4" />
+      <span>Draft - Not visible in production</span>
+    </div>
+  )
+}

package/src/components/docs/footer.tsx

@@ -0,0 +1,47 @@
+import Link from "next/link"
+import { getConfig, SpecraConfig } from "@/lib/config"
+
+export function Footer({ config }: { config: SpecraConfig }) {
+  // Server component - can use getConfig directly
+  // const config = getConfig()
+
+  if (!config.footer) {
+    return null
+  }
+
+  return (
+    <footer className="bg-muted/30 dark:bg-muted/10 rounded-2xl mt-24">
+      <div className="px-6 py-12">
+        {config.footer.links && config.footer.links.length > 0 && (
+          <div className="grid grid-cols-2 md:grid-cols-4 gap-8 mb-8">
+            {config.footer.links.map((column, idx) => (
+              <div key={idx}>
+                <h3 className="font-semibold text-foreground mb-4">{column.title}</h3>
+                <ul className="space-y-2">
+                  {column.items.map((item, itemIdx) => (
+                    <li key={itemIdx}>
+                      <Link
+                        href={item.href}
+                        className="text-sm text-muted-foreground hover:text-foreground transition-colors"
+                      >
+                        {item.label}
+                      </Link>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            ))}
+          </div>
+        )}
+
+        {config.footer.copyright && (
+          <div className="pt-8">
+            <p className="text-sm text-muted-foreground text-center">
+              {config.footer.copyright}
+            </p>
+          </div>
+        )}
+      </div>
+    </footer>
+  )
+}

package/src/components/docs/frame.tsx

@@ -0,0 +1,22 @@
+interface FrameProps {
+  src: string
+  title?: string
+  height?: number | string
+  width?: string
+}
+
+export function Frame({ src, title = "Embedded content", height = 500, width = "100%" }: FrameProps) {
+  return (
+    <div className="my-6 rounded-xl border border-border overflow-hidden bg-muted/30">
+      <iframe
+        src={src}
+        title={title}
+        width={width}
+        height={height}
+        className="w-full"
+        loading="lazy"
+        sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
+      />
+    </div>
+  )
+}

package/src/components/docs/header.tsx

@@ -0,0 +1,122 @@
+"use client"
+
+import Link from "next/link"
+import { Search, Menu, Github, Twitter, MessageCircle } from "lucide-react"
+import { Button } from "@/components/ui/button"
+import { VersionSwitcher } from "./version-switcher"
+import { ThemeToggle } from "./theme-toggle"
+import { SearchModal } from "./search-modal"
+import { useState, useEffect } from "react"
+import type { SpecraConfig } from "@/lib/config"
+import { getAssetPath } from "@/lib/utils"
+
+interface HeaderProps {
+  currentVersion: string
+  versions: string[]
+  onMenuClick?: () => void
+  config: SpecraConfig
+}
+
+export function Header({ currentVersion, versions, onMenuClick, config }: HeaderProps) {
+  const [searchOpen, setSearchOpen] = useState(false)
+
+  // Keyboard shortcut for search (Cmd+K or Ctrl+K)
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+        e.preventDefault()
+        setSearchOpen(true)
+      }
+    }
+
+    window.addEventListener("keydown", handleKeyDown)
+    return () => window.removeEventListener("keydown", handleKeyDown)
+  }, [])
+
+  return (
+    <header className="sticky top-0 z-50 w-full border-b border-border bg-background/95 backdrop-blur supports-backdrop-filter:bg-background/60">
+      <div className="container flex h-16 items-center justify-between px-6 mx-auto">
+        <div className="flex items-center gap-2">
+          <button 
+            onClick={onMenuClick}
+            className="lg:hidden hover:bg-muted p-2 rounded-md transition-colors"
+            aria-label="Toggle menu"
+          >
+            <Menu className="h-5 w-5" />
+          </button>
+          <Link href="/" className="flex items-center gap-2">
+            {config.site.logo ? (
+              <img src={getAssetPath(config.site.logo)} alt={config.site.title} className="h-8 w-auto" />
+            ) : (
+              <div className="h-8 w-8 rounded-xl bg-primary flex items-center justify-center">
+                <span className="text-primary-foreground font-bold text-lg">
+                  {config.site.title.charAt(0).toUpperCase()}
+                </span>
+              </div>
+            )}
+            <span className="font-semibold text-lg text-foreground">Specra</span>
+          </Link>
+        </div>
+
+        <div className="flex items-center gap-2">
+          {config.search?.enabled && (
+            <button
+              onClick={() => setSearchOpen(true)}
+              className="flex items-center gap-2 px-3 py-2 text-sm text-muted-foreground hover:text-foreground bg-muted rounded-md transition-colors"
+            >
+              <Search className="h-4 w-4" />
+              <span className="hidden sm:inline">{config.search.placeholder || "Search"}</span>
+              <kbd className="hidden sm:inline-flex h-5 select-none items-center gap-1 rounded border border-border bg-background px-1.5 font-mono text-xs font-medium">
+                ⌘K
+              </kbd>
+            </button>
+          )}
+
+          {config.features?.versioning && (
+            <VersionSwitcher currentVersion={currentVersion} versions={versions} />
+          )}
+
+          {/* Social Links */}
+          {config.social?.github && (
+            <a
+              href={config.social.github}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="hidden md:flex items-center justify-center h-9 w-9 rounded-md hover:bg-muted transition-colors"
+              aria-label="GitHub"
+            >
+              <Github className="h-4 w-4" />
+            </a>
+          )}
+          {config.social?.twitter && (
+            <a
+              href={config.social.twitter}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="hidden md:flex items-center justify-center h-9 w-9 rounded-md hover:bg-muted transition-colors"
+              aria-label="Twitter"
+            >
+              <Twitter className="h-4 w-4" />
+            </a>
+          )}
+          {config.social?.discord && (
+            <a
+              href={config.social.discord}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="hidden md:flex items-center justify-center h-9 w-9 rounded-md hover:bg-muted transition-colors"
+              aria-label="Discord"
+            >
+              <MessageCircle className="h-4 w-4" />
+            </a>
+          )}
+
+          <ThemeToggle />
+        </div>
+      </div>
+
+      {/* Search Modal */}
+      <SearchModal isOpen={searchOpen} onClose={() => setSearchOpen(false)} config={config} />
+    </header>
+  )
+}

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

@@ -0,0 +1,77 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import { usePathname } from "next/navigation"
+import { RefreshCw } from "lucide-react"
+
+export function HotReloadIndicator() {
+  const [isReloading, setIsReloading] = useState(false)
+  const [lastReload, setLastReload] = useState<Date | null>(null)
+  const pathname = usePathname()
+
+  useEffect(() => {
+    if (process.env.NODE_ENV !== "development") return
+
+    // Track when content updates
+    setIsReloading(true)
+    const timer = setTimeout(() => {
+      setIsReloading(false)
+      setLastReload(new Date())
+      
+      // Auto-hide after 3 seconds
+      setTimeout(() => {
+        setLastReload(null)
+      }, 3000)
+    }, 500)
+
+    return () => clearTimeout(timer)
+  }, [pathname])
+
+  useEffect(() => {
+    if (process.env.NODE_ENV !== "development") return
+
+    // Listen for Next.js Fast Refresh
+    const handleBeforeRefresh = () => {
+      setIsReloading(true)
+    }
+
+    const handleAfterRefresh = () => {
+      setIsReloading(false)
+      setLastReload(new Date())
+      setTimeout(() => setLastReload(null), 3000)
+    }
+
+    // @ts-ignore - Next.js internal API
+    if (typeof window !== 'undefined' && window.__NEXT_DATA__) {
+      window.addEventListener('beforeunload', handleBeforeRefresh)
+    }
+
+    return () => {
+      window.removeEventListener('beforeunload', handleBeforeRefresh)
+    }
+  }, [])
+
+  if (process.env.NODE_ENV !== "development") return null
+
+  return (
+    <>
+      {/* Reloading indicator */}
+      {isReloading && (
+        <div className="fixed bottom-4 right-4 z-50 flex items-center gap-2 px-4 py-2 bg-primary text-primary-foreground rounded-xl shadow-lg animate-in slide-in-from-bottom-2">
+          <RefreshCw className="h-4 w-4 animate-spin" />
+          <span className="text-sm font-medium">Reloading...</span>
+        </div>
+      )}
+
+      {/* Success indicator */}
+      {lastReload && !isReloading && (
+        <div className="fixed bottom-4 right-4 z-50 flex items-center gap-2 px-4 py-2 bg-green-500 text-white rounded-xl shadow-lg animate-in slide-in-from-bottom-2">
+          <RefreshCw className="h-4 w-4" />
+          <span className="text-sm font-medium">
+            Updated at {lastReload.toLocaleTimeString()}
+          </span>
+        </div>
+      )}
+    </>
+  )
+}

package/src/components/docs/icon.tsx

@@ -0,0 +1,70 @@
+"use client"
+
+import * as LucideIcons from "lucide-react"
+
+interface IconProps {
+  icon: string | React.ReactNode
+  iconType?: "regular" | "solid" | "light" | "thin" | "sharp-solid" | "duotone" | "brands"
+  color?: string
+  size?: number
+  className?: string
+}
+
+export function Icon({ icon, iconType = "regular", color, size = 20, className = "" }: IconProps) {
+  // If icon is a React node (custom SVG), render it directly
+  if (typeof icon !== "string") {
+    return <span className={`inline-flex items-center ${className}`} style={{ color }}>{icon}</span>
+  }
+
+  // Check if it's a URL (external or local file)
+  if (icon.startsWith("http") || icon.startsWith("/")) {
+    return (
+      <img
+        src={icon}
+        alt=""
+        width={size}
+        height={size}
+        className={`inline-block ${className}`}
+        style={{ color }}
+      />
+    )
+  }
+
+  // Check if it's a Font Awesome icon (starts with fa-)
+  if (icon.startsWith("fa-")) {
+    const faClass = `fa-${iconType} ${icon}`
+    return (
+      <i
+        className={`${faClass} ${className}`}
+        style={{ fontSize: size, color }}
+        aria-hidden="true"
+      />
+    )
+  }
+
+  // Try to find Lucide icon
+  const iconName = icon
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join("")
+
+  const LucideIcon = (LucideIcons as any)[iconName]
+
+  if (LucideIcon) {
+    return (
+      <LucideIcon
+        size={size}
+        className={`inline-block ${className}`}
+        style={{ color }}
+        aria-hidden="true"
+      />
+    )
+  }
+
+  // Fallback: render the icon name
+  return (
+    <span className={`inline-flex items-center font-mono text-xs ${className}`} style={{ color }}>
+      [{icon}]
+    </span>
+  )
+}

package/src/components/docs/image-card.tsx

@@ -0,0 +1,95 @@
+import NextImage from "next/image"
+import Link from "next/link"
+
+interface ImageCardProps {
+  src: string
+  alt: string
+  title?: string
+  description?: string
+  href?: string
+  external?: boolean
+  aspectRatio?: "square" | "video" | "portrait"
+}
+
+export function ImageCard({
+  src,
+  alt,
+  title,
+  description,
+  href,
+  external = false,
+  aspectRatio = "video",
+}: ImageCardProps) {
+  const aspectRatios = {
+    square: "aspect-square",
+    video: "aspect-video",
+    portrait: "aspect-[3/4]",
+  }
+
+  const content = (
+    <div className="flex flex-col gap-0 p-0">
+      <div className={`w-full ${aspectRatios[aspectRatio]} overflow-hidden ${(title || description) ? 'rounded-t-xl' : 'rounded-xl'} bg-muted relative`}>
+        <NextImage
+          src={src}
+          alt={alt}
+          fill
+          sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+          className="object-cover transition-transform duration-300 group-hover:scale-105"
+        />
+      </div>
+      {(title || description) && (
+        <div className="p-3 flex flex-col gap-1">
+          {title && (
+            <h3 className={`font-semibold text-foreground mb-0 no-underline ${href ? 'group-hover:text-primary transition-colors' : ''}`}>
+              {title}
+            </h3>
+          )}
+          {description && (
+            <p className="text-sm text-muted-foreground line-clamp-2 no-underline mb-0">
+              {description}
+            </p>
+          )}
+        </div>
+      )}
+    </div>
+  )
+
+  if (href) {
+    const Component = external ? "a" : Link
+    return (
+      <Component
+        href={href}
+        className="image-card-link group block rounded-xl border border-border hover:border-primary/50 hover:shadow-lg transition-all overflow-hidden p-0"
+        {...(external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+      >
+        {content}
+      </Component>
+    )
+  }
+
+  return (
+    <div className="block rounded-xl border border-border overflow-hidden bg-card p-0">
+      {content}
+    </div>
+  )
+}
+
+interface ImageCardGridProps {
+  children: React.ReactNode
+  cols?: 1 | 2 | 3 | 4
+}
+
+export function ImageCardGrid({ children, cols = 3 }: ImageCardGridProps) {
+  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",
+    4: "grid-cols-1 md:grid-cols-2 lg:grid-cols-4",
+  }
+
+  return (
+    <div className={`grid ${gridCols[cols]} gap-4 my-6`}>
+      {children}
+    </div>
+  )
+}

package/src/components/docs/image.tsx

@@ -0,0 +1,73 @@
+"use client"
+
+import NextImage from "next/image"
+import { useState } from "react"
+import { ZoomIn, X } from "lucide-react"
+
+interface ImageProps {
+  src: string
+  alt: string
+  caption?: string
+  width?: number
+  height?: number
+  zoom?: boolean
+}
+
+export function Image({ src, alt, caption, width, height, zoom = true }: ImageProps) {
+  const [isZoomed, setIsZoomed] = useState(false)
+
+  return (
+    <>
+      <figure className="my-6">
+        <div className="relative group rounded-xl border border-border overflow-hidden bg-muted/30">
+          <NextImage
+            src={src}
+            alt={alt}
+            width={width || 1200}
+            height={height || 675}
+            className="w-full h-auto"
+          />
+          {zoom && (
+            <button
+              onClick={() => setIsZoomed(true)}
+              className="absolute top-3 right-3 p-2 rounded-md bg-background/80 backdrop-blur-sm border border-border opacity-0 group-hover:opacity-100 transition-opacity hover:bg-background"
+              aria-label="Zoom image"
+            >
+              <ZoomIn className="h-4 w-4 text-foreground" />
+            </button>
+          )}
+        </div>
+        {caption && (
+          <figcaption className="mt-2 text-center text-sm text-muted-foreground italic">
+            {caption}
+          </figcaption>
+        )}
+      </figure>
+
+      {/* Zoom Modal */}
+      {isZoomed && (
+        <div
+          className="fixed inset-0 z-50 bg-background/95 backdrop-blur-sm flex items-center justify-center p-4"
+          onClick={() => setIsZoomed(false)}
+        >
+          <button
+            onClick={() => setIsZoomed(false)}
+            className="absolute top-4 right-4 p-2 rounded-md bg-muted hover:bg-muted/80 transition-colors"
+            aria-label="Close"
+          >
+            <X className="h-5 w-5 text-foreground" />
+          </button>
+          <div className="max-w-7xl max-h-[90vh] overflow-auto">
+            <NextImage
+              src={src}
+              alt={alt}
+              width={width || 1920}
+              height={height || 1080}
+              className="w-full h-auto"
+            />
+          </div>
+        </div>
+      )}
+    </>
+  )
+}

package/src/components/docs/index.ts

@@ -0,0 +1,48 @@
+// Core documentation components
+export * from "./accordion"
+export { Badge as DocBadge } from "./badge"
+export * from "./breadcrumb"
+export * from "./callout"
+export * from "./card"
+export * from "./category-index"
+export * from "./code-block"
+export * from "./columns"
+export * from "./componentTextProps"
+export * from "./dev-mode-badge"
+export * from "./doc-layout"
+export * from "./doc-layout-wrapper"
+export * from "./doc-loading"
+export * from "./doc-metadata"
+export * from "./doc-navigation"
+export * from "./doc-tags"
+export * from "./draft-badge"
+export * from "./footer"
+export * from "./frame"
+export * from "./header"
+export * from "./hot-reload-indicator"
+export * from "./icon"
+export * from "./image-card"
+export * from "./image"
+export * from "./math"
+export * from "./mdx-components"
+export * from "./mdx-hot-reload"
+export * from "./mermaid"
+export * from "./mobile-doc-layout"
+export * from "./not-found-content"
+export * from "./search-highlight"
+export * from "./search-modal"
+export * from "./sidebar-skeleton"
+export * from "./sidebar"
+export * from "./site-banner"
+export * from "./steps"
+export * from "./tab-context"
+export * from "./tab-groups"
+export * from "./table-of-contents"
+export * from "./tabs"
+export * from "./theme-toggle"
+export * from "./tooltip"
+export * from "./version-switcher"
+export * from "./video"
+
+// API documentation components
+export * from "./api"