specra 0.1.0

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

@@ -0,0 +1,223 @@
+"use client"
+
+import { useState, useEffect, useCallback } from "react"
+import { Search, FileText, Loader2 } from "lucide-react"
+import { useRouter } from "next/navigation"
+import type { SpecraConfig } from "@/lib/config"
+import {
+  Dialog,
+  DialogContent,
+} from "@/components/ui/dialog"
+
+interface SearchResult {
+  id: string
+  title: string
+  content: string
+  slug: string
+  version: string
+  category?: string
+}
+
+interface SearchModalProps {
+  isOpen: boolean
+  onClose: () => void
+  config: SpecraConfig
+}
+
+export function SearchModal({ isOpen, onClose, config }: SearchModalProps) {
+  const [query, setQuery] = useState("")
+  const [results, setResults] = useState<SearchResult[]>([])
+  const [isLoading, setIsLoading] = useState(false)
+  const [selectedIndex, setSelectedIndex] = useState(0)
+  const router = useRouter()
+
+  const searchConfig = config.search
+
+  // Search function
+  const performSearch = useCallback(async (searchQuery: string) => {
+    if (!searchQuery.trim() || !searchConfig?.enabled) {
+      setResults([])
+      return
+    }
+
+    setIsLoading(true)
+    try {
+      const response = await fetch("/api/search", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          query: searchQuery,
+          // filter: 'version = "v1.0.0"',
+          distinct: "version",
+          limit: 2
+        }),
+      })
+
+
+      if (response.ok) {
+        const data = await response.json()
+        console.log("Search response:", data)
+        setResults(data.hits || [])
+      } else {
+        console.error("Search failed:", response.status, await response.text())
+      }
+    } catch (error) {
+      console.error("Search error:", error)
+      setResults([])
+    } finally {
+      setIsLoading(false)
+    }
+  }, [searchConfig])
+
+  // Debounced search
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      performSearch(query)
+    }, 300)
+
+    return () => clearTimeout(timer)
+  }, [query, performSearch])
+
+  // Handle keyboard navigation
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (!isOpen) return
+
+      switch (e.key) {
+        case "Escape":
+          onClose()
+          break
+        case "ArrowDown":
+          e.preventDefault()
+          setSelectedIndex((prev) => Math.min(prev + 1, results.length - 1))
+          break
+        case "ArrowUp":
+          e.preventDefault()
+          setSelectedIndex((prev) => Math.max(prev - 1, 0))
+          break
+        case "Enter":
+          e.preventDefault()
+          if (results[selectedIndex]) {
+            handleResultClick(results[selectedIndex])
+          }
+          break
+      }
+    }
+
+    window.addEventListener("keydown", handleKeyDown)
+    return () => window.removeEventListener("keydown", handleKeyDown)
+  }, [isOpen, results, selectedIndex, onClose])
+
+  // Reset on open/close
+  useEffect(() => {
+    if (isOpen) {
+      setQuery("")
+      setResults([])
+      setSelectedIndex(0)
+    }
+  }, [isOpen])
+
+  const handleResultClick = (result: SearchResult) => {
+    // Add search query as URL parameter for highlighting
+    const url = `/docs/${result.version}/${result.slug}?q=${encodeURIComponent(query)}`
+    router.push(url)
+    onClose()
+  }
+
+  const highlightText = (text: string, query: string) => {
+    if (!query.trim()) return text
+
+    const parts = text.split(new RegExp(`(${query})`, "gi"))
+    return parts.map((part, i) =>
+      part.toLowerCase() === query.toLowerCase()
+        ? <mark key={i} className="bg-yellow-200 dark:bg-yellow-900/50 text-foreground">{part}</mark>
+        : part
+    )
+  }
+
+  return (
+    <Dialog open={isOpen} onOpenChange={onClose} modal={true}>
+      <DialogContent
+        className="max-w-2xl p-0 gap-0 top-[10vh] translate-y-0"
+        showCloseButton={false}
+        onOpenAutoFocus={(e) => e.preventDefault()}
+      >
+        {/* Search Input */}
+        <div className="flex items-center gap-3 px-4 py-3 border-b border-border">
+          <Search className="h-5 w-5 text-muted-foreground shrink-0" />
+          <input
+            type="text"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            placeholder={searchConfig?.placeholder || "Search documentation..."}
+            className="flex-1 bg-transparent border-none outline-none text-foreground placeholder:text-muted-foreground"
+            autoFocus
+          />
+          {isLoading && <Loader2 className="h-5 w-5 text-muted-foreground animate-spin" />}
+        </div>
+
+        {/* Results */}
+        <div className="max-h-[60vh] overflow-y-auto">
+          {query.trim() && results.length === 0 && !isLoading && (
+            <div className="px-4 py-8 text-center text-muted-foreground">
+              No results found for "{query}"
+            </div>
+          )}
+
+          {results.length > 0 && (
+            <div className="py-2">
+              {results.map((result, index) => (
+                <button
+                  key={result.id}
+                  onClick={() => handleResultClick(result)}
+                  className={`w-full px-4 py-3 text-left hover:bg-muted/50 transition-colors border-l-2 ${index === selectedIndex
+                      ? "bg-muted/50 border-primary"
+                      : "border-transparent"
+                    }`}
+                  onMouseEnter={() => setSelectedIndex(index)}
+                >
+                  <div className="flex items-start gap-3">
+                    <FileText className="h-5 w-5 text-muted-foreground shrink-0 mt-0.5" />
+                    <div className="flex-1 min-w-0">
+                      <div className="font-medium text-foreground mb-1">
+                        {highlightText(result.title, query)}
+                      </div>
+                      {result.content && (
+                        <div className="text-sm text-muted-foreground line-clamp-2">
+                          {highlightText(result.content, query)}
+                        </div>
+                      )}
+                      <div className="flex items-center gap-2 mt-1 text-xs text-muted-foreground">
+                        <span>{result.version}</span>
+                        {result.category && (
+                          <>
+                            <span>•</span>
+                            <span>{result.category}</span>
+                          </>
+                        )}
+                      </div>
+                    </div>
+                  </div>
+                </button>
+              ))}
+            </div>
+          )}
+
+          {!query.trim() && (
+            <div className="px-4 py-8 text-center text-muted-foreground text-sm">
+              <p>Start typing to search documentation...</p>
+              <div className="mt-4 flex items-center justify-center gap-4 text-xs">
+                <kbd className="px-2 py-1 bg-muted rounded border border-border">↑↓</kbd>
+                <span>Navigate</span>
+                <kbd className="px-2 py-1 bg-muted rounded border border-border">Enter</kbd>
+                <span>Select</span>
+                <kbd className="px-2 py-1 bg-muted rounded border border-border">Esc</kbd>
+                <span>Close</span>
+              </div>
+            </div>
+          )}
+        </div>
+      </DialogContent>
+    </Dialog>
+  )
+}

package/src/components/docs/sidebar-skeleton.tsx

@@ -0,0 +1,39 @@
+export function SidebarSkeleton() {
+  return (
+    <aside className="w-64 pr-8 py-6">
+      <div className="space-y-6">
+        {/* Documentation title */}
+        <div className="px-2">
+          <div className="h-5 w-32 bg-muted/50 rounded animate-pulse" />
+        </div>
+
+        {/* Skeleton items */}
+        <div className="space-y-1">
+          {[...Array(8)].map((_, i) => (
+            <div key={i} className="px-3 py-2">
+              <div
+                className="h-4 bg-muted/50 rounded animate-pulse"
+                style={{ width: `${60 + Math.random() * 40}%` }}
+              />
+            </div>
+          ))}
+        </div>
+
+        {/* Another section */}
+        <div className="space-y-1">
+          <div className="px-2 mb-2">
+            <div className="h-4 w-24 bg-muted/50 rounded animate-pulse" />
+          </div>
+          {[...Array(5)].map((_, i) => (
+            <div key={i} className="px-3 py-2">
+              <div
+                className="h-4 bg-muted/50 rounded animate-pulse"
+                style={{ width: `${50 + Math.random() * 50}%` }}
+              />
+            </div>
+          ))}
+        </div>
+      </div>
+    </aside>
+  )
+}

package/src/components/docs/sidebar.tsx

@@ -0,0 +1,323 @@
+"use client"
+
+import Link from "next/link"
+import { usePathname } from "next/navigation"
+import { ChevronRight, ChevronDown, FolderOpen } from "lucide-react"
+import { useState } from "react"
+import type { SpecraConfig } from "@/lib/config"
+import { Icon } from "./icon"
+import { sortSidebarItems, sortSidebarGroups } from "@/lib/sidebar-utils"
+
+interface DocItem {
+  title: string
+  slug: string
+  filePath: string
+  section?: string
+  group?: string
+  sidebar?: string
+  sidebar_position?: number
+  categoryLabel?: string
+  categoryPosition?: number
+  categoryCollapsible?: boolean
+  categoryCollapsed?: boolean
+  categoryIcon?: string  // Icon from _category_.json
+  categoryTabGroup?: string  // Tab group from _category_.json
+  meta?: {
+    icon?: string  // Icon name from frontmatter
+    tab_group?: string  // Tab group from frontmatter
+    [key: string]: any
+  }
+}
+
+interface SidebarProps {
+  docs: DocItem[]
+  version: string
+  onLinkClick?: () => void
+  config: SpecraConfig
+  activeTabGroup?: string  // Current active tab group filter
+}
+
+interface SidebarGroup {
+  label: string
+  path: string  // Path for navigation (e.g., "components" for /docs/v1.0.0/components)
+  icon?: string  // Icon from _category_.json
+  items: DocItem[]
+  position: number
+  collapsible: boolean
+  defaultCollapsed: boolean
+  children: Record<string, SidebarGroup>
+}
+
+export function Sidebar({ docs, version, onLinkClick, config, activeTabGroup }: SidebarProps) {
+  const pathname = usePathname()
+  const [collapsed, setCollapsed] = useState<Record<string, boolean>>(() => {
+    const initial: Record<string, boolean> = {}
+    return initial
+  })
+
+  if (!config.navigation?.showSidebar) {
+    return null
+  }
+
+  // Filter docs by active tab group if tab groups are configured
+  const hasTabGroups = config.navigation?.tabGroups && config.navigation.tabGroups.length > 0
+  const filteredDocs = hasTabGroups && activeTabGroup
+    ? docs.filter((doc) => {
+        // Get tab group from either frontmatter or category config
+        const docTabGroup = doc.meta?.tab_group || doc.categoryTabGroup
+
+        // If doc has no tab group, include it in the first tab group
+        if (!docTabGroup) {
+          return activeTabGroup === config.navigation?.tabGroups?.[0]?.id
+        }
+
+        return docTabGroup === activeTabGroup
+      })
+    : docs
+
+  // Build a hierarchical tree structure
+  const rootGroups: Record<string, SidebarGroup> = {}
+  const standalone: DocItem[] = []
+
+  filteredDocs.forEach((doc) => {
+    const pathParts = doc.filePath.split("/")
+    const isIndexFile = doc.filePath.endsWith("/index") ||
+      doc.filePath === "index" ||
+      (pathParts.length > 1 && doc.slug === pathParts.slice(0, -1).join("/"))
+
+    // Use the sidebar or group from frontmatter if provided
+    const customGroup = doc.sidebar || doc.group
+
+    if (customGroup) {
+      const groupName = customGroup.charAt(0).toUpperCase() + customGroup.slice(1)
+      if (!rootGroups[groupName]) {
+        rootGroups[groupName] = {
+          label: groupName,
+          path: customGroup,
+          items: [],
+          position: 999,
+          collapsible: doc.categoryCollapsible ?? true,
+          defaultCollapsed: doc.categoryCollapsed ?? false,
+          children: {}
+        }
+      }
+      if (isIndexFile) {
+        rootGroups[groupName].position = doc.sidebar_position ?? 999
+        rootGroups[groupName].icon = doc.categoryIcon
+      } else {
+        rootGroups[groupName].items.push(doc)
+      }
+      return
+    }
+
+    // Build nested structure based on folder path
+    if (pathParts.length > 1) {
+      const folderParts = pathParts.slice(0, -1) // All folders except the file
+
+      // Navigate/create the tree structure
+      let currentLevel = rootGroups
+      let currentPath = ""
+
+      for (let i = 0; i < folderParts.length; i++) {
+        const folder = folderParts[i]
+        currentPath = currentPath ? `${currentPath}/${folder}` : folder
+        const folderLabel = folder.split("-").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")
+
+        if (!currentLevel[folder]) {
+          currentLevel[folder] = {
+            label: doc.categoryLabel && i === folderParts.length - 1 ? doc.categoryLabel : folderLabel,
+            path: currentPath,
+            icon: doc.categoryIcon,
+            items: [],
+            position: doc.categoryPosition ?? 999,
+            collapsible: doc.categoryCollapsible ?? true,
+            defaultCollapsed: doc.categoryCollapsed ?? false,
+            children: {}
+          }
+        }
+
+        // If this is the deepest folder (where the file lives), add the doc
+        if (i === folderParts.length - 1) {
+          if (isIndexFile) {
+            currentLevel[folder].position = doc.categoryPosition ?? doc.sidebar_position ?? 999
+            // Update label and icon from category config if available
+            if (doc.categoryLabel) {
+              currentLevel[folder].label = doc.categoryLabel
+            }
+            if (doc.categoryIcon) {
+              currentLevel[folder].icon = doc.categoryIcon
+            }
+          } else {
+            currentLevel[folder].items.push(doc)
+          }
+        }
+
+        currentLevel = currentLevel[folder].children
+      }
+    } else {
+      if (!isIndexFile) {
+        standalone.push(doc)
+      }
+    }
+  })
+
+  const toggleSection = (section: string) => {
+    setCollapsed((prev) => ({ ...prev, [section]: !prev[section] }))
+  }
+
+  // Recursive component to render nested groups
+  const renderGroup = (groupKey: string, group: SidebarGroup, depth: number = 0) => {
+    const sortedItems = sortSidebarItems(group.items)
+    const sortedChildren = sortSidebarGroups(group.children)
+    const hasChildren = sortedChildren.length > 0
+    const hasItems = sortedItems.length > 0
+    const hasContent = hasChildren || hasItems
+
+    // Check if any item in this group (or nested children) is active
+    const isActiveInGroup = (g: SidebarGroup): boolean => {
+      const hasActiveItem = g.items.some((doc) => pathname === `/docs/${version}/${doc.slug}`)
+      if (hasActiveItem) return true
+      return Object.values(g.children).some(child => isActiveInGroup(child))
+    }
+
+    const hasActiveItem = isActiveInGroup(group)
+    const isGroupActive = pathname === `/docs/${version}/${group.path}`
+    const isCollapsed = hasActiveItem || isGroupActive ? false : (collapsed[groupKey] ?? group.defaultCollapsed)
+    const marginLeft = depth > 0 ? "ml-4" : ""
+    const groupHref = `/docs/${version}/${group.path}`
+
+    return (
+      <div key={`group-${groupKey}`} className={`space-y-1 ${marginLeft}`}>
+        {/* Group header: Docusaurus-style with clickable label and chevron toggle */}
+        <div className="flex items-center group">
+          {/* Icon + Label (clickable, navigates to index) */}
+          <Link
+            href={groupHref}
+            onClick={onLinkClick}
+            className={`flex items-center gap-2 flex-1 px-3 py-2 text-sm font-semibold rounded-l-xl transition-all ${isGroupActive
+                ? "bg-primary/10 text-primary"
+                : "text-foreground hover:bg-accent/50"
+              }`}
+          >
+            {group.icon ? (
+              <Icon icon={group.icon} size={16} className="shrink-0" />
+            ) : (
+              <FolderOpen size={16} className="shrink-0" />
+            )}
+            {group.label}
+          </Link>
+
+          {/* Chevron toggle (only if has content and is collapsible) */}
+          {hasContent && group.collapsible && config.navigation?.collapsibleSidebar && (
+            <button
+              onClick={(e) => {
+                e.preventDefault()
+                e.stopPropagation()
+                toggleSection(groupKey)
+              }}
+              className={`p-2 rounded-r-xl transition-all ${isGroupActive ? "hover:bg-primary/20" : "hover:bg-accent/50"}`}
+              aria-label={isCollapsed ? "Expand section" : "Collapse section"}
+            >
+              {isCollapsed ? (
+                <ChevronRight className={`h-4 w-4 ${isGroupActive ? "text-primary" : "text-muted-foreground"}`} />
+              ) : (
+                <ChevronDown className={`h-4 w-4 ${isGroupActive ? "text-primary" : "text-muted-foreground"}`} />
+              )}
+            </button>
+          )}
+        </div>
+
+        {/* Children (shown when not collapsed) */}
+        {!isCollapsed && hasContent && (
+          <div className="ml-4 space-y-1">
+            {/* Merge and sort both child groups and items by position */}
+            {(() => {
+              // Create a unified list with type indicators
+              const merged: Array<{type: 'group', key: string, group: SidebarGroup, position: number} | {type: 'item', doc: DocItem, position: number}> = [
+                ...sortedChildren.map(([childKey, childGroup]) => ({
+                  type: 'group' as const,
+                  key: childKey,
+                  group: childGroup,
+                  position: childGroup.position
+                })),
+                ...sortedItems.map((doc) => ({
+                  type: 'item' as const,
+                  doc,
+                  position: doc.sidebar_position ?? doc.meta?.sidebar_position ?? doc.meta?.order ?? 999
+                }))
+              ]
+
+              // Sort by position
+              merged.sort((a, b) => a.position - b.position)
+
+              // Render in sorted order
+              return merged.map((item) => {
+                if (item.type === 'group') {
+                  return renderGroup(`${groupKey}/${item.key}`, item.group, depth + 1)
+                } else {
+                  const href = `/docs/${version}/${item.doc.slug}`
+                  const isActive = pathname === href
+
+                  return (
+                    <Link
+                      key={`grouped-${item.doc.slug}`}
+                      href={href}
+                      onClick={onLinkClick}
+                      className={`flex items-center gap-2 px-3 py-2 text-sm rounded-xl transition-all ${isActive
+                        ? "bg-primary/10 text-primary font-medium"
+                        : "text-foreground hover:text-foreground hover:bg-accent/50"
+                        }`}
+                    >
+                      {item.doc.meta?.icon && <Icon icon={item.doc.meta.icon} size={16} className="shrink-0" />}
+                      {item.doc.title}
+                    </Link>
+                  )
+                }
+              })
+            })()}
+          </div>
+        )}
+      </div>
+    )
+  }
+
+  const sortedRootGroups = sortSidebarGroups(rootGroups)
+  const sortedStandalone = sortSidebarItems(standalone)
+
+  // Adjust top position based on whether tabs are present
+  const stickyTop = hasTabGroups ? "top-[7.5rem]" : "top-24"
+  const maxHeight = hasTabGroups ? "max-h-[calc(100vh-10rem)]" : "max-h-[calc(100vh-7rem)]"
+
+  return (
+    <aside className={`w-64 shrink-0 sticky ${stickyTop} self-start`}>
+      <div className={`${maxHeight} overflow-y-auto bg-muted/30 dark:bg-muted/10 rounded-2xl p-4 border border-border/50`}>
+        <h2 className="text-xs font-semibold text-muted-foreground uppercase tracking-wider mb-4 px-2">Documentation</h2>
+        <nav className="space-y-1">
+          {/* Standalone pages (not in folders) */}
+          {sortedStandalone.length > 0 && sortedStandalone.map((doc) => {
+            const href = `/docs/${version}/${doc.slug}`
+            const isActive = pathname === href
+
+            return (
+              <Link
+                key={`standalone-${doc.slug}`}
+                href={href}
+                onClick={onLinkClick}
+                className={`flex items-center gap-2 px-3 py-2 text-sm rounded-xl transition-all ${isActive
+                  ? "bg-primary/10 text-primary font-medium"
+                  : "text-foreground hover:text-foreground hover:bg-accent/50"
+                  }`}
+              >
+                {doc.meta?.icon && <Icon icon={doc.meta.icon} size={16} className="shrink-0" />}
+                {doc.title}
+              </Link>
+            )
+          })}
+
+          {/* Grouped pages (in folders) - now hierarchical */}
+          {sortedRootGroups.map(([groupKey, group]) => renderGroup(groupKey, group, 0))}
+        </nav>
+      </div>
+    </aside>
+  )
+}

package/src/components/docs/site-banner.tsx

@@ -0,0 +1,92 @@
+"use client"
+
+import { X, AlertCircle, CheckCircle, Info, XCircle } from "lucide-react"
+import { useState, useEffect } from "react"
+import type { SpecraConfig } from "@/lib/config"
+
+interface SiteBannerProps {
+  config: SpecraConfig
+}
+
+export function SiteBanner({ config }: SiteBannerProps) {
+  const [dismissed, setDismissed] = useState(false)
+  const [mounted, setMounted] = useState(false)
+  
+  const banner = config.banner
+  const storageKey = "site-banner-dismissed"
+  
+  useEffect(() => {
+    setMounted(true)
+    // Check if banner was previously dismissed
+    const isDismissed = localStorage.getItem(storageKey) === "true"
+    setDismissed(isDismissed)
+  }, [])
+  
+  const handleDismiss = () => {
+    setDismissed(true)
+    localStorage.setItem(storageKey, "true")
+  }
+  
+  // Don't render on server or if no banner configured or if dismissed
+  if (!mounted || !banner || !banner.enabled || dismissed) {
+    return null
+  }
+
+  const typeConfig = {
+    info: {
+      icon: Info,
+      bg: "bg-blue-500/10 dark:bg-blue-400/5",
+      border: "border-blue-500/30 dark:border-blue-500/20",
+      iconColor: "text-blue-600 dark:text-blue-400",
+      textColor: "text-blue-900 dark:text-blue-300",
+    },
+    success: {
+      icon: CheckCircle,
+      bg: "bg-green-500/10 dark:bg-green-400/5",
+      border: "border-green-500/30 dark:border-green-500/20",
+      iconColor: "text-green-600 dark:text-green-400",
+      textColor: "text-green-900 dark:text-green-300",
+    },
+    warning: {
+      icon: AlertCircle,
+      bg: "bg-yellow-500/10 dark:bg-yellow-400/5",
+      border: "border-yellow-500/30 dark:border-yellow-500/20",
+      iconColor: "text-yellow-600 dark:text-yellow-400",
+      textColor: "text-yellow-900 dark:text-yellow-300",
+    },
+    error: {
+      icon: XCircle,
+      bg: "bg-red-500/10 dark:bg-red-400/5",
+      border: "border-red-500/30 dark:border-red-500/20",
+      iconColor: "text-red-600 dark:text-red-400",
+      textColor: "text-red-900 dark:text-red-300",
+    },
+  }
+
+  const type = banner.type || "info"
+  const { icon: IconComponent, bg, border, iconColor, textColor } = typeConfig[type]
+
+  return (
+    <div className={`w-full border-b ${border} ${bg}`}>
+      <div className="container mx-auto px-6 py-3">
+        <div className="flex items-center gap-3">
+          <IconComponent className={`h-5 w-5 shrink-0 ${iconColor}`} />
+          <div className="flex-1 min-w-0">
+            <p className={`text-sm font-medium ${textColor}`}>
+              {banner.message}
+            </p>
+          </div>
+          {banner.dismissible && (
+            <button
+              onClick={handleDismiss}
+              className={`shrink-0 p-1 rounded-md hover:bg-black/5 dark:hover:bg-white/5 transition-colors ${iconColor}`}
+              aria-label="Dismiss banner"
+            >
+              <X className="h-4 w-4" />
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}