specra 0.1.0

package/src/lib/sidebar-utils.ts

@@ -0,0 +1,188 @@
+/**
+ * Unified sidebar sorting and structure building utilities
+ * This module provides consistent sidebar logic across the application
+ * to ensure ordering is handled the same way everywhere.
+ */
+
+export interface SidebarGroup {
+  label: string
+  path: string
+  icon?: string
+  items: any[]
+  position: number
+  collapsible: boolean
+  defaultCollapsed: boolean
+  children: Record<string, SidebarGroup>
+}
+
+/**
+ * Sort sidebar items by their position.
+ * Items with explicit sidebar_position come first (sorted numerically),
+ * followed by items without position (sorted by their original order).
+ *
+ * @param items - Array of items with optional sidebar_position
+ * @returns Sorted array of items
+ */
+export function sortSidebarItems<T extends { sidebar_position?: number; meta?: any }>(items: T[]): T[] {
+  return [...items].sort((a, b) => {
+    const posA = a.sidebar_position ?? a.meta?.sidebar_position ?? a.meta?.order ?? 999
+    const posB = b.sidebar_position ?? b.meta?.sidebar_position ?? b.meta?.order ?? 999
+    return posA - posB
+  })
+}
+
+/**
+ * Sort sidebar groups by their position.
+ * Groups with explicit position come first (sorted numerically),
+ * followed by groups without position at the end (sorted by their original order).
+ *
+ * @param groups - Record of group key to group object with position
+ * @returns Sorted array of [key, group] tuples
+ */
+export function sortSidebarGroups<T extends { position: number }>(
+  groups: Record<string, T>
+): [string, T][] {
+  return Object.entries(groups).sort(([, a], [, b]) => {
+    const posA = a.position ?? 999
+    const posB = b.position ?? 999
+    return posA - posB
+  })
+}
+
+/**
+ * Build hierarchical sidebar structure from flat list of documents
+ * This is the single source of truth for sidebar structure used by both
+ * the sidebar component and navigation (prev/next) links.
+ *
+ * @param docs - Array of documents with metadata
+ * @returns Object containing root groups and standalone items
+ */
+export function buildSidebarStructure<T extends {
+  filePath: string
+  slug: string
+  categoryLabel?: string
+  categoryPosition?: number
+  categoryIcon?: string
+  categoryCollapsible?: boolean
+  categoryCollapsed?: boolean
+  meta: any
+}>(docs: T[]): {
+  rootGroups: Record<string, SidebarGroup>
+  standalone: T[]
+} {
+  const rootGroups: Record<string, SidebarGroup> = {}
+  const standalone: T[] = []
+
+  // First pass: collect category metadata from all docs to build complete folder structure
+  const categoryMetadata = new Map<string, {
+    label?: string
+    position?: number
+    icon?: string
+    collapsible?: boolean
+    collapsed?: boolean
+  }>()
+
+  docs.forEach((doc) => {
+    const pathParts = doc.filePath.split("/")
+    const folderPath = pathParts.length > 1 ? pathParts.slice(0, -1).join("/") : ""
+
+    if (folderPath && doc.categoryLabel) {
+      categoryMetadata.set(folderPath, {
+        label: doc.categoryLabel,
+        position: doc.categoryPosition,
+        icon: doc.categoryIcon,
+        collapsible: doc.categoryCollapsible,
+        collapsed: doc.categoryCollapsed
+      })
+    }
+  })
+
+  docs.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("/"))
+
+    const customGroup = doc.meta.sidebar || doc.meta.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) {
+        // Use categoryPosition if available (from _category_.json), otherwise sidebar_position from frontmatter
+        rootGroups[groupName].position = doc.categoryPosition ?? doc.meta.sidebar_position ?? 999
+        rootGroups[groupName].icon = doc.categoryIcon
+      } else {
+        rootGroups[groupName].items.push(doc)
+      }
+      return
+    }
+
+    if (pathParts.length > 1) {
+      const folderParts = pathParts.slice(0, -1)
+      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(" ")
+
+        // Get metadata for this specific folder path
+        const metadata = categoryMetadata.get(currentPath)
+
+        if (!currentLevel[folder]) {
+          currentLevel[folder] = {
+            label: metadata?.label ?? folderLabel,
+            path: currentPath,
+            icon: metadata?.icon,
+            items: [],
+            position: metadata?.position ?? 999,
+            collapsible: metadata?.collapsible ?? true,
+            defaultCollapsed: metadata?.collapsed ?? false,
+            children: {}
+          }
+        }
+
+        if (i === folderParts.length - 1) {
+          if (isIndexFile) {
+            // Update position, label, and icon if this is the index file for this folder
+            currentLevel[folder].position = doc.categoryPosition ?? doc.meta.sidebar_position ?? currentLevel[folder].position
+            if (doc.categoryLabel) {
+              currentLevel[folder].label = doc.categoryLabel
+            }
+            if (doc.categoryIcon) {
+              currentLevel[folder].icon = doc.categoryIcon
+            }
+            if (doc.categoryCollapsible !== undefined) {
+              currentLevel[folder].collapsible = doc.categoryCollapsible
+            }
+            if (doc.categoryCollapsed !== undefined) {
+              currentLevel[folder].defaultCollapsed = doc.categoryCollapsed
+            }
+          } else {
+            currentLevel[folder].items.push(doc)
+          }
+        }
+
+        currentLevel = currentLevel[folder].children
+      }
+    } else {
+      if (!isIndexFile) {
+        standalone.push(doc)
+      }
+    }
+  })
+
+  return { rootGroups, standalone }
+}

package/src/lib/toc.ts

@@ -0,0 +1,24 @@
+export interface TOCItem {
+  id: string
+  title: string
+  level: number
+}
+
+/**
+ * Extract headings from HTML string for table of contents
+ */
+export function extractHeadings(html: string): TOCItem[] {
+  const headingRegex = /<h([2-3])[^>]*id="([^"]*)"[^>]*>(.*?)<\/h\1>/g
+  const toc: TOCItem[] = []
+  let match
+
+  while ((match = headingRegex.exec(html)) !== null) {
+    const level = Number.parseInt(match[1])
+    const id = match[2]
+    const title = match[3].replace(/<[^>]*>/g, "") // Strip HTML tags
+
+    toc.push({ id, title, level })
+  }
+
+  return toc
+}

package/src/lib/utils.ts

@@ -0,0 +1,36 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+
+
+/**
+ * Get the correct asset path based on deployment configuration
+ * Handles different deployment scenarios:
+ * - Vercel/Node.js hosting (standalone build): No basePath needed
+ * - GitHub Pages without custom domain: Uses basePath from config
+ * - Static hosting with custom domain: No basePath needed
+ *
+ * @param path - The asset path (can start with or without '/')
+ * @returns The properly formatted asset path
+ */
+export function getAssetPath(path: string): string {
+  // Get basePath from Next.js config (set during build for static exports)
+  const basePath = process.env.NEXT_PUBLIC_BASE_PATH || process.env.__NEXT_ROUTER_BASEPATH || ''
+
+  // Normalize the input path: ensure it starts with '/'
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`
+
+  // If we have a basePath (GitHub Pages without custom domain), prepend it
+  if (basePath) {
+    // Normalize basePath: remove trailing slash, ensure leading slash
+    const normalizedBase = basePath.startsWith('/') ? basePath : `/${basePath}`
+    const cleanBase = normalizedBase.replace(/\/$/, '')
+    return `${cleanBase}${normalizedPath}`
+  }
+
+  // Default: return the normalized path (works for Vercel, custom domains, and dev)
+  return normalizedPath
+}

package/src/specra.config.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "./lib/config.types.ts",
+  "site": {
+    "title": "Documentation Library",
+    "description": "Comprehensive documentation for your project",
+    "url": "https://vercel.com/dalmasontos-projects/v0-documentation-library",
+    "baseUrl": "/",
+    "language": "en",
+    "organizationName": "Your Organization",
+    "projectName": "v0-documentation-library",
+    "activeVersion": "v1.0.0",
+    "favicon": "/icon-light-32x32.png"
+  },
+  "theme": {
+    "defaultMode": "system",
+    "respectPrefersColorScheme": true
+  },
+  "navigation": {
+    "showSidebar": true,
+    "collapsibleSidebar": true,
+    "showBreadcrumbs": true,
+    "showTableOfContents": true,
+    "tocPosition": "right",
+    "tocMaxDepth": 3,
+    "tabGroups": [
+      {
+        "id": "guides",
+        "label": "Guides",
+        "icon": "book-open"
+      },
+      {
+        "id": "api",
+        "label": "API Reference",
+        "icon": "zap"
+      },
+      {
+        "id": "components",
+        "label": "Components",
+        "icon": "layers"
+      }
+    ]
+  },
+  "social": {
+    "github": "https://github.com/dalmasonto",
+    "twitter": "https://twitter.com/dalmasonto",
+    "discord": "https://discord.com/invite/dalmasonto",
+    "custom": [
+      {
+        "label": "Website",
+        "href": "https://craftfolio.com/dalmasonto"
+      }
+    ]
+  },
+  "search": {
+    "enabled": true,
+    "placeholder": "Search documentation...",
+    "provider": "meilisearch",
+    "meilisearch": {
+      "host": "http://localhost:7700",
+      "apiKey": "aSampleMasterKey",
+      "indexName": "docs"
+    }
+  },
+  "analytics": {
+    "googleAnalytics": "",
+    "plausible": ""
+  },
+  "footer": {
+    "copyright": "Copyright © 2024 Dalmasonto. All rights reserved.",
+    "links": [
+      {
+        "title": "Documentation",
+        "items": [
+          {
+            "label": "Getting Started",
+            "href": "/docs/v1.0.0/getting-started"
+          },
+          {
+            "label": "API Reference",
+            "href": "/docs/v1.0.0/api"
+          }
+        ]
+      },
+      {
+        "title": "Community",
+        "items": [
+          {
+            "label": "GitHub",
+            "href": "https://github.com/yourusername/your-repo"
+          },
+          {
+            "label": "Discord",
+            "href": "#"
+          }
+        ]
+      }
+    ]
+  },
+  "banner": {
+    "enabled": true,
+    "message": "🎉 This is a development version. Some features may not work as expected.",
+    "type": "error",
+    "dismissible": true
+  },
+  "features": {
+    "editUrl": "https://github.com/yourusername/your-repo/edit/main/docs",
+    "showLastUpdated": true,
+    "showReadingTime": true,
+    "showAuthors": false,
+    "showTags": true,
+    "versioning": true,
+    "i18n": false
+  },
+  "env": {
+    "API_BASE_URL": "https://api.example.com",
+    "API_VERSION": "v1",
+    "CDN_URL": "https://cdn.example.com"
+  },
+  "deployment": {
+    "target": "vercel",
+    "basePath": "",
+    "customDomain": false
+  }
+}