specra 0.1.0

package/src/components/ui/dialog.tsx

@@ -0,0 +1,143 @@
+"use client"
+
+import * as React from "react"
+import * as DialogPrimitive from "@radix-ui/react-dialog"
+import { XIcon } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+
+function Dialog({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Root>) {
+  return <DialogPrimitive.Root data-slot="dialog" {...props} />
+}
+
+function DialogTrigger({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Trigger>) {
+  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />
+}
+
+function DialogPortal({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Portal>) {
+  return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />
+}
+
+function DialogClose({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Close>) {
+  return <DialogPrimitive.Close data-slot="dialog-close" {...props} />
+}
+
+function DialogOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Overlay>) {
+  return (
+    <DialogPrimitive.Overlay
+      data-slot="dialog-overlay"
+      className={cn(
+        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50 dark:bg-black/70 backdrop-blur-md",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogContent({
+  className,
+  children,
+  showCloseButton = true,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Content> & {
+  showCloseButton?: boolean
+}) {
+  return (
+    <DialogPortal data-slot="dialog-portal">
+      <DialogOverlay />
+      <DialogPrimitive.Content
+        data-slot="dialog-content"
+        className={cn(
+          "bg-background data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border p-6 shadow-lg duration-200 outline-none sm:max-w-lg",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <DialogPrimitive.Close
+            data-slot="dialog-close"
+            className="ring-offset-background focus:ring-ring data-[state=open]:bg-accent data-[state=open]:text-muted-foreground absolute top-4 right-4 rounded-xs opacity-70 transition-opacity hover:opacity-100 focus:ring-2 focus:ring-offset-2 focus:outline-hidden disabled:pointer-events-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4"
+          >
+            <XIcon />
+            <span className="sr-only">Close</span>
+          </DialogPrimitive.Close>
+        )}
+      </DialogPrimitive.Content>
+    </DialogPortal>
+  )
+}
+
+function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="dialog-header"
+      className={cn("flex flex-col gap-2 text-center sm:text-left", className)}
+      {...props}
+    />
+  )
+}
+
+function DialogFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="dialog-footer"
+      className={cn(
+        "flex flex-col-reverse gap-2 sm:flex-row sm:justify-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Title>) {
+  return (
+    <DialogPrimitive.Title
+      data-slot="dialog-title"
+      className={cn("text-lg leading-none font-semibold", className)}
+      {...props}
+    />
+  )
+}
+
+function DialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Description>) {
+  return (
+    <DialogPrimitive.Description
+      data-slot="dialog-description"
+      className={cn("text-muted-foreground text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+}

package/src/components/ui/index.ts

@@ -0,0 +1,6 @@
+// UI primitive components
+export * from "./badge"
+export * from "./button"
+export * from "./dialog"
+export * from "./input"
+export * from "./textarea"

package/src/components/ui/input.tsx

@@ -0,0 +1,21 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground dark:bg-input/30 border-input h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]",
+        "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Input }

package/src/components/ui/textarea.tsx

@@ -0,0 +1,18 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
+  return (
+    <textarea
+      data-slot="textarea"
+      className={cn(
+        "border-input placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Textarea }

package/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Specra Documentation SDK
+ *
+ * A modern documentation framework for Next.js with:
+ * - MDX-based documentation
+ * - Versioning support
+ * - API reference generation (OpenAPI, Postman, Specra formats)
+ * - Full-text search integration (MeiliSearch)
+ * - Tab groups for organizing content
+ * - Dark mode and theming
+ * - SEO optimization
+ */
+
+// Core library functions
+export * from './lib'
+
+// React components
+export * from './components'
+
+// Next.js app exports (for re-exporting in user projects)
+export { default as RootLayout, generateMetadata as generateRootMetadata } from './app/layout'
+export {
+  default as DocsPage,
+  generateMetadata as generateDocsMetadata,
+  generateStaticParams as generateDocsStaticParams
+} from './app/docs-page'
+
+// Types
+export type { SpecraConfig, SiteConfig, NavigationConfig, ThemeConfig } from './lib/config.types'
+export type { Doc, DocMeta, TocItem } from './lib/mdx'
+export type {
+  ApiDocumentation,
+  ApiSpecConfig,
+  ParsedApiSpec,
+  RestEndpoint,
+  ApiParameter,
+  ApiResponse,
+  GraphQLSchema,
+  WebSocketConnection
+} from './lib/api.types'
+// Note: SpecraApiResponse is exported from './lib' as a renamed type to avoid conflicts

package/src/lib/api-parser.types.ts

@@ -0,0 +1,78 @@
+/**
+ * Simple API Documentation Format for Specra
+ * Easy to write, easy to parse
+ */
+
+export interface ApiParam {
+  name: string
+  type: string
+  required?: boolean
+  description?: string
+  default?: any
+  example?: any
+}
+
+export interface ApiHeader {
+  name: string
+  value: string
+  description?: string
+}
+
+export interface ApiResponse {
+  status: number
+  description?: string
+  example?: any
+  schema?: any
+}
+
+export interface ApiEndpointSpec {
+  title: string
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
+  path: string
+  description?: string
+
+  // Parameters
+  pathParams?: ApiParam[]
+  queryParams?: ApiParam[]
+  headers?: ApiHeader[]
+  body?: {
+    description?: string
+    example?: any
+    schema?: any
+  }
+
+  // Responses
+  successResponse?: ApiResponse
+  errorResponses?: ApiResponse[]
+
+  // Examples
+  examples?: {
+    title: string
+    language: string
+    code: string
+  }[]
+}
+
+export interface SpecraApiSpec {
+  version?: string
+  title?: string
+  description?: string
+  baseUrl: string
+
+  // Environment variables for interpolation
+  env?: Record<string, string>
+
+  // Global headers applied to all endpoints
+  globalHeaders?: ApiHeader[]
+
+  // Authentication
+  auth?: {
+    type: "bearer" | "apiKey" | "basic"
+    description?: string
+    headerName?: string
+    tokenPrefix?: string
+  }
+
+  // Endpoints
+  endpoints: ApiEndpointSpec[]
+}

package/src/lib/api.types.ts

@@ -0,0 +1,202 @@
+/**
+ * Specra API Documentation Schema
+ * Supports REST, GraphQL, and WebSocket APIs
+ */
+
+// ============================================================================
+// Common Types
+// ============================================================================
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS"
+
+export interface ApiParameter {
+  name: string
+  type: string
+  required?: boolean
+  description?: string
+  default?: any
+  example?: any
+  enum?: string[]
+}
+
+export interface ApiResponse {
+  status: number
+  description: string
+  schema?: any
+  example?: any
+  headers?: Record<string, string>
+}
+
+export interface ApiExample {
+  title: string
+  language: string
+  code: string
+}
+
+export interface ApiAuthentication {
+  type: "apiKey" | "bearer" | "basic" | "oauth2" | "none"
+  description?: string
+  location?: "header" | "query" | "cookie" // For apiKey
+  name?: string // Header/query parameter name
+  scheme?: string // Bearer scheme
+}
+
+// ============================================================================
+// REST API Types
+// ============================================================================
+
+export interface RestEndpoint {
+  type: "rest"
+  method: HttpMethod
+  path: string
+  summary: string
+  description?: string
+  operationId?: string
+  tags?: string[]
+  deprecated?: boolean
+
+  // Authentication
+  authentication?: ApiAuthentication
+
+  // Parameters
+  pathParams?: ApiParameter[]
+  queryParams?: ApiParameter[]
+  headers?: ApiParameter[]
+  body?: {
+    contentType: string
+    schema?: any
+    example?: any
+    description?: string
+  }
+
+  // Responses
+  responses: ApiResponse[]
+
+  // Code Examples
+  examples?: ApiExample[]
+}
+
+// ============================================================================
+// GraphQL API Types
+// ============================================================================
+
+export interface GraphQLField {
+  name: string
+  type: string
+  description?: string
+  args?: ApiParameter[]
+  deprecated?: boolean
+  deprecationReason?: string
+}
+
+export interface GraphQLType {
+  name: string
+  kind: "OBJECT" | "INPUT_OBJECT" | "ENUM" | "SCALAR" | "INTERFACE" | "UNION"
+  description?: string
+  fields?: GraphQLField[]
+  enumValues?: { name: string; description?: string }[]
+}
+
+export interface GraphQLQuery {
+  type: "graphql"
+  operationType: "query" | "mutation" | "subscription"
+  name: string
+  description?: string
+  args?: ApiParameter[]
+  returnType: string
+  example?: string
+  response?: any
+}
+
+export interface GraphQLSchema {
+  queries?: GraphQLQuery[]
+  mutations?: GraphQLQuery[]
+  subscriptions?: GraphQLQuery[]
+  types?: GraphQLType[]
+}
+
+// ============================================================================
+// WebSocket API Types
+// ============================================================================
+
+export interface WebSocketEvent {
+  type: "websocket"
+  event: string
+  direction: "client-to-server" | "server-to-client" | "bidirectional"
+  description?: string
+  payload?: {
+    schema?: any
+    example?: any
+  }
+  response?: {
+    schema?: any
+    example?: any
+  }
+}
+
+export interface WebSocketConnection {
+  url: string
+  authentication?: ApiAuthentication
+  description?: string
+  events: WebSocketEvent[]
+}
+
+// ============================================================================
+// Unified API Documentation
+// ============================================================================
+
+export interface ApiDocumentation {
+  version: string
+  title: string
+  description?: string
+  baseUrl?: string
+  servers?: Array<{
+    url: string
+    description?: string
+  }>
+
+  // REST endpoints
+  rest?: {
+    endpoints: RestEndpoint[]
+  }
+
+  // GraphQL schema
+  graphql?: GraphQLSchema
+
+  // WebSocket connections
+  websocket?: WebSocketConnection[]
+
+  // Global settings
+  authentication?: ApiAuthentication[]
+  headers?: Record<string, string>
+}
+
+// ============================================================================
+// API Spec Sources
+// ============================================================================
+
+export interface ApiSpecConfig {
+  // Source type
+  source: "openapi" | "postman" | "insomnia" | "specra" | "manual"
+
+  // File path (relative to public/api-specs/)
+  path?: string
+
+  // Inline spec (for Specra format)
+  spec?: ApiDocumentation
+
+  // Auto-generate pages
+  autoGenerate?: boolean
+
+  // Output directory for generated pages
+  outputDir?: string
+}
+
+// ============================================================================
+// Helper Types for Parsing
+// ============================================================================
+
+export interface ParsedApiSpec {
+  source: ApiSpecConfig["source"]
+  documentation: ApiDocumentation
+}

package/src/lib/category.ts

@@ -0,0 +1,71 @@
+import fs from "fs"
+import path from "path"
+
+export interface CategoryConfig {
+  label?: string
+  position?: number
+  sidebar_position?: number  // Alternative naming for position
+  link?: {
+    type: "generated-index" | "doc"
+    slug?: string
+  }
+  collapsed?: boolean
+  collapsible?: boolean
+  icon?: string  // Icon name for sidebar display (Lucide icon name)
+  tab_group?: string  // Tab group ID for organizing categories into tabs
+}
+
+const DOCS_DIR = path.join(process.cwd(), "docs")
+
+/**
+ * Read category.json from a folder
+ */
+export function getCategoryConfig(folderPath: string): CategoryConfig | null {
+  try {
+    const categoryPath = path.join(folderPath, "_category_.json")
+
+    if (!fs.existsSync(categoryPath)) {
+      return null
+    }
+
+    const content = fs.readFileSync(categoryPath, "utf8")
+    return JSON.parse(content) as CategoryConfig
+  } catch (error) {
+    console.error(`Error reading category config from ${folderPath}:`, error)
+    return null
+  }
+}
+
+/**
+ * Get all category configs for a version
+ */
+export function getAllCategoryConfigs(version: string): Map<string, CategoryConfig> {
+  const configs = new Map<string, CategoryConfig>()
+  const versionDir = path.join(DOCS_DIR, version)
+
+  if (!fs.existsSync(versionDir)) {
+    return configs
+  }
+
+  function scanDirectory(dir: string, relativePath: string = "") {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const fullPath = path.join(dir, entry.name)
+        const relPath = relativePath ? `${relativePath}/${entry.name}` : entry.name
+
+        const config = getCategoryConfig(fullPath)
+        if (config) {
+          configs.set(relPath, config)
+        }
+
+        // Recursively scan subdirectories
+        scanDirectory(fullPath, relPath)
+      }
+    }
+  }
+
+  scanDirectory(versionDir)
+  return configs
+}