specra 0.1.0

package/LICENSE.MD

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dalmasonto, arthur-kamau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# Specra
+
+A modern documentation library for Next.js that makes it easy to create beautiful, feature-rich documentation sites.
+
+## Features
+
+- 📝 **MDX Support** - Write documentation in Markdown with React components
+- 📚 **Multi-Version Docs** - Support multiple documentation versions seamlessly
+- 🔌 **API Reference Generation** - Auto-generate API docs from OpenAPI, Postman, or Specra formats
+- 🔍 **Full-Text Search** - Integrated MeiliSearch support for fast search
+- 🎯 **Tab Groups** - Organize content into multiple navigation tabs
+- 🌓 **Dark Mode** - Built-in theme switching with system preference detection
+- 🎨 **Customizable** - Highly configurable with Tailwind CSS
+- ⚡ **Fast** - Built on Next.js with optimized performance
+- 📱 **Responsive** - Mobile-friendly design out of the box
+- 🔥 **Hot Reload** - Instant updates during development
+
+## Installation
+
+```bash
+npm install specra
+# or
+yarn add specra
+# or
+pnpm add specra
+```
+
+## Quick Start
+
+### 1. Create a new Next.js app (if you don't have one)
+
+```bash
+npx create-next-app@latest my-docs
+cd my-docs
+```
+
+### 2. Install Specra
+
+```bash
+npm install specra
+```
+
+### 3. Set up your app structure
+
+```
+my-docs/
+├── app/
+│   ├── layout.tsx          # Re-export from Specra
+│   ├── page.tsx            # Your landing page
+│   └── docs/
+│       └── [version]/
+│           └── [...slug]/
+│               └── page.tsx  # Re-export from Specra
+├── docs/                   # Your MDX content
+│   └── v1.0.0/
+│       └── getting-started.mdx
+├── public/
+│   └── logo.png
+└── specra.config.json      # Specra configuration
+```
+
+### 4. Configure app/layout.tsx
+
+```typescript
+// app/layout.tsx
+export { default } from 'specra/app/layout'
+export { generateMetadata } from 'specra/app/layout'
+```
+
+### 5. Configure app/docs/[version]/[...slug]/page.tsx
+
+```typescript
+// app/docs/[version]/[...slug]/page.tsx
+export { default } from 'specra/app/docs-page'
+export {
+  generateStaticParams,
+  generateMetadata
+} from 'specra/app/docs-page'
+```
+
+### 6. Create specra.config.json
+
+```json
+{
+  "site": {
+    "title": "My Documentation",
+    "description": "Awesome docs built with Specra",
+    "url": "https://docs.example.com",
+    "logo": "/logo.png"
+  },
+  "theme": {
+    "defaultMode": "system",
+    "primaryColor": "#0070f3"
+  },
+  "navigation": {
+    "sidebar": true,
+    "breadcrumbs": true
+  }
+}
+```
+
+### 7. Create your first doc
+
+```mdx
+---
+title: Getting Started
+description: Learn how to get started with our platform
+---
+
+# Getting Started
+
+Welcome to the documentation!
+```
+
+### 8. Import globals.css
+
+Add to your `app/globals.css`:
+
+```css
+@import 'specra/styles';
+
+/* Your custom styles */
+```
+
+### 9. Run development server
+
+```bash
+npm run dev
+```
+
+Visit `http://localhost:3000/docs/v1.0.0/getting-started` to see your docs!
+
+## Configuration
+
+See [Configuration Guide](https://docs.specra.dev/configuration) for full documentation.
+
+## Upgrading
+
+Simply update the package to get latest features and bug fixes:
+
+```bash
+npm update specra
+```
+
+Your content and configuration stay the same - only the SDK updates!
+
+## Why Specra?
+
+Specra is designed to be the easiest way to create documentation for your projects. It handles all the complex parts (versioning, search, API references) while letting you focus on writing great content.
+
+## License
+
+MIT
+
+## Authors
+
+dalmasonto, arthur-kamau

package/dist/app/api/mdx-watch/route.d.mts

@@ -0,0 +1,12 @@
+import { NextRequest } from 'next/server';
+
+declare const dynamic = "force-dynamic";
+declare const runtime = "nodejs";
+/**
+ * API route for watching MDX file changes in development
+ * Provides Server-Sent Events (SSE) stream for hot reloading
+ * Only available in development mode
+ */
+declare function GET(request: NextRequest): Promise<Response>;
+
+export { GET, dynamic, runtime };

package/dist/app/api/mdx-watch/route.d.ts

@@ -0,0 +1,12 @@
+import { NextRequest } from 'next/server';
+
+declare const dynamic = "force-dynamic";
+declare const runtime = "nodejs";
+/**
+ * API route for watching MDX file changes in development
+ * Provides Server-Sent Events (SSE) stream for hot reloading
+ * Only available in development mode
+ */
+declare function GET(request: NextRequest): Promise<Response>;
+
+export { GET, dynamic, runtime };

package/dist/app/api/mdx-watch/route.js

@@ -0,0 +1,98 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/app/api/mdx-watch/route.ts
+var route_exports = {};
+__export(route_exports, {
+  GET: () => GET,
+  dynamic: () => dynamic,
+  runtime: () => runtime
+});
+module.exports = __toCommonJS(route_exports);
+var import_fs = require("fs");
+var import_path = require("path");
+var dynamic = "force-dynamic";
+var runtime = "nodejs";
+async function GET(request) {
+  if (process.env.NODE_ENV !== "development") {
+    return new Response("Not available in production", { status: 404 });
+  }
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    start(controller) {
+      const connectMsg = `data: ${JSON.stringify({ type: "connected" })}
+
+`;
+      controller.enqueue(encoder.encode(connectMsg));
+      const docsPath = (0, import_path.join)(process.cwd(), "docs");
+      const watcher = (0, import_fs.watch)(
+        docsPath,
+        { recursive: true },
+        (eventType, filename) => {
+          if (!filename) return;
+          if (filename.endsWith(".mdx") || filename.endsWith(".json")) {
+            console.log(`[MDX Watch] ${eventType}: ${filename}`);
+            const message = `data: ${JSON.stringify({
+              type: "change",
+              file: filename,
+              eventType
+            })}
+
+`;
+            try {
+              controller.enqueue(encoder.encode(message));
+            } catch (error) {
+              console.error("[MDX Watch] Error sending message:", error);
+            }
+          }
+        }
+      );
+      request.signal.addEventListener("abort", () => {
+        console.log("[MDX Watch] Client disconnected");
+        watcher.close();
+        try {
+          controller.close();
+        } catch (error) {
+        }
+      });
+      watcher.on("error", (error) => {
+        console.error("[MDX Watch] Watcher error:", error);
+        watcher.close();
+        try {
+          controller.close();
+        } catch (e) {
+        }
+      });
+    }
+  });
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      "Connection": "keep-alive"
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GET,
+  dynamic,
+  runtime
+});
+//# sourceMappingURL=route.js.map

package/dist/app/api/mdx-watch/route.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/app/api/mdx-watch/route.ts"],"sourcesContent":["import { NextRequest } from 'next/server'\nimport { watch } from 'fs'\nimport { join } from 'path'\n\nexport const dynamic = 'force-dynamic'\nexport const runtime = 'nodejs'\n\n/**\n * API route for watching MDX file changes in development\n * Provides Server-Sent Events (SSE) stream for hot reloading\n * Only available in development mode\n */\nexport async function GET(request: NextRequest) {\n  // Only allow in development mode\n  if (process.env.NODE_ENV !== 'development') {\n    return new Response('Not available in production', { status: 404 })\n  }\n\n  const encoder = new TextEncoder()\n\n  const stream = new ReadableStream({\n    start(controller) {\n      // Send initial connection message\n      const connectMsg = `data: ${JSON.stringify({ type: 'connected' })}\\n\\n`\n      controller.enqueue(encoder.encode(connectMsg))\n\n      const docsPath = join(process.cwd(), 'docs')\n\n      // Watch the docs directory recursively\n      const watcher = watch(\n        docsPath,\n        { recursive: true },\n        (eventType, filename) => {\n          if (!filename) return\n\n          // Only watch for .mdx and .json files (MDX files and category configs)\n          if (filename.endsWith('.mdx') || filename.endsWith('.json')) {\n            console.log(`[MDX Watch] ${eventType}: ${filename}`)\n\n            const message = `data: ${JSON.stringify({\n              type: 'change',\n              file: filename,\n              eventType\n            })}\\n\\n`\n\n            try {\n              controller.enqueue(encoder.encode(message))\n            } catch (error) {\n              console.error('[MDX Watch] Error sending message:', error)\n            }\n          }\n        }\n      )\n\n      // Handle client disconnect\n      request.signal.addEventListener('abort', () => {\n        console.log('[MDX Watch] Client disconnected')\n        watcher.close()\n        try {\n          controller.close()\n        } catch (error) {\n          // Controller might already be closed\n        }\n      })\n\n      // Handle errors\n      watcher.on('error', (error) => {\n        console.error('[MDX Watch] Watcher error:', error)\n        watcher.close()\n        try {\n          controller.close()\n        } catch (e) {\n          // Controller might already be closed\n        }\n      })\n    }\n  })\n\n  return new Response(stream, {\n    headers: {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache, no-transform',\n      'Connection': 'keep-alive',\n    },\n  })\n}"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,gBAAsB;AACtB,kBAAqB;AAEd,IAAM,UAAU;AAChB,IAAM,UAAU;AAOvB,eAAsB,IAAI,SAAsB;AAE9C,MAAI,QAAQ,IAAI,aAAa,eAAe;AAC1C,WAAO,IAAI,SAAS,+BAA+B,EAAE,QAAQ,IAAI,CAAC;AAAA,EACpE;AAEA,QAAM,UAAU,IAAI,YAAY;AAEhC,QAAM,SAAS,IAAI,eAAe;AAAA,IAChC,MAAM,YAAY;AAEhB,YAAM,aAAa,SAAS,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC,CAAC;AAAA;AAAA;AACjE,iBAAW,QAAQ,QAAQ,OAAO,UAAU,CAAC;AAE7C,YAAM,eAAW,kBAAK,QAAQ,IAAI,GAAG,MAAM;AAG3C,YAAM,cAAU;AAAA,QACd;AAAA,QACA,EAAE,WAAW,KAAK;AAAA,QAClB,CAAC,WAAW,aAAa;AACvB,cAAI,CAAC,SAAU;AAGf,cAAI,SAAS,SAAS,MAAM,KAAK,SAAS,SAAS,OAAO,GAAG;AAC3D,oBAAQ,IAAI,eAAe,SAAS,KAAK,QAAQ,EAAE;AAEnD,kBAAM,UAAU,SAAS,KAAK,UAAU;AAAA,cACtC,MAAM;AAAA,cACN,MAAM;AAAA,cACN;AAAA,YACF,CAAC,CAAC;AAAA;AAAA;AAEF,gBAAI;AACF,yBAAW,QAAQ,QAAQ,OAAO,OAAO,CAAC;AAAA,YAC5C,SAAS,OAAO;AACd,sBAAQ,MAAM,sCAAsC,KAAK;AAAA,YAC3D;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAGA,cAAQ,OAAO,iBAAiB,SAAS,MAAM;AAC7C,gBAAQ,IAAI,iCAAiC;AAC7C,gBAAQ,MAAM;AACd,YAAI;AACF,qBAAW,MAAM;AAAA,QACnB,SAAS,OAAO;AAAA,QAEhB;AAAA,MACF,CAAC;AAGD,cAAQ,GAAG,SAAS,CAAC,UAAU;AAC7B,gBAAQ,MAAM,8BAA8B,KAAK;AACjD,gBAAQ,MAAM;AACd,YAAI;AACF,qBAAW,MAAM;AAAA,QACnB,SAAS,GAAG;AAAA,QAEZ;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF,CAAC;AAED,SAAO,IAAI,SAAS,QAAQ;AAAA,IAC1B,SAAS;AAAA,MACP,gBAAgB;AAAA,MAChB,iBAAiB;AAAA,MACjB,cAAc;AAAA,IAChB;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/app/api/mdx-watch/route.mjs

@@ -0,0 +1,71 @@
+// src/app/api/mdx-watch/route.ts
+import { watch } from "fs";
+import { join } from "path";
+var dynamic = "force-dynamic";
+var runtime = "nodejs";
+async function GET(request) {
+  if (process.env.NODE_ENV !== "development") {
+    return new Response("Not available in production", { status: 404 });
+  }
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    start(controller) {
+      const connectMsg = `data: ${JSON.stringify({ type: "connected" })}
+
+`;
+      controller.enqueue(encoder.encode(connectMsg));
+      const docsPath = join(process.cwd(), "docs");
+      const watcher = watch(
+        docsPath,
+        { recursive: true },
+        (eventType, filename) => {
+          if (!filename) return;
+          if (filename.endsWith(".mdx") || filename.endsWith(".json")) {
+            console.log(`[MDX Watch] ${eventType}: ${filename}`);
+            const message = `data: ${JSON.stringify({
+              type: "change",
+              file: filename,
+              eventType
+            })}
+
+`;
+            try {
+              controller.enqueue(encoder.encode(message));
+            } catch (error) {
+              console.error("[MDX Watch] Error sending message:", error);
+            }
+          }
+        }
+      );
+      request.signal.addEventListener("abort", () => {
+        console.log("[MDX Watch] Client disconnected");
+        watcher.close();
+        try {
+          controller.close();
+        } catch (error) {
+        }
+      });
+      watcher.on("error", (error) => {
+        console.error("[MDX Watch] Watcher error:", error);
+        watcher.close();
+        try {
+          controller.close();
+        } catch (e) {
+        }
+      });
+    }
+  });
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      "Connection": "keep-alive"
+    }
+  });
+}
+export {
+  GET,
+  dynamic,
+  runtime
+};
+//# sourceMappingURL=route.mjs.map

package/dist/app/api/mdx-watch/route.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/app/api/mdx-watch/route.ts"],"sourcesContent":["import { NextRequest } from 'next/server'\nimport { watch } from 'fs'\nimport { join } from 'path'\n\nexport const dynamic = 'force-dynamic'\nexport const runtime = 'nodejs'\n\n/**\n * API route for watching MDX file changes in development\n * Provides Server-Sent Events (SSE) stream for hot reloading\n * Only available in development mode\n */\nexport async function GET(request: NextRequest) {\n  // Only allow in development mode\n  if (process.env.NODE_ENV !== 'development') {\n    return new Response('Not available in production', { status: 404 })\n  }\n\n  const encoder = new TextEncoder()\n\n  const stream = new ReadableStream({\n    start(controller) {\n      // Send initial connection message\n      const connectMsg = `data: ${JSON.stringify({ type: 'connected' })}\\n\\n`\n      controller.enqueue(encoder.encode(connectMsg))\n\n      const docsPath = join(process.cwd(), 'docs')\n\n      // Watch the docs directory recursively\n      const watcher = watch(\n        docsPath,\n        { recursive: true },\n        (eventType, filename) => {\n          if (!filename) return\n\n          // Only watch for .mdx and .json files (MDX files and category configs)\n          if (filename.endsWith('.mdx') || filename.endsWith('.json')) {\n            console.log(`[MDX Watch] ${eventType}: ${filename}`)\n\n            const message = `data: ${JSON.stringify({\n              type: 'change',\n              file: filename,\n              eventType\n            })}\\n\\n`\n\n            try {\n              controller.enqueue(encoder.encode(message))\n            } catch (error) {\n              console.error('[MDX Watch] Error sending message:', error)\n            }\n          }\n        }\n      )\n\n      // Handle client disconnect\n      request.signal.addEventListener('abort', () => {\n        console.log('[MDX Watch] Client disconnected')\n        watcher.close()\n        try {\n          controller.close()\n        } catch (error) {\n          // Controller might already be closed\n        }\n      })\n\n      // Handle errors\n      watcher.on('error', (error) => {\n        console.error('[MDX Watch] Watcher error:', error)\n        watcher.close()\n        try {\n          controller.close()\n        } catch (e) {\n          // Controller might already be closed\n        }\n      })\n    }\n  })\n\n  return new Response(stream, {\n    headers: {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache, no-transform',\n      'Connection': 'keep-alive',\n    },\n  })\n}"],"mappings":";AACA,SAAS,aAAa;AACtB,SAAS,YAAY;AAEd,IAAM,UAAU;AAChB,IAAM,UAAU;AAOvB,eAAsB,IAAI,SAAsB;AAE9C,MAAI,QAAQ,IAAI,aAAa,eAAe;AAC1C,WAAO,IAAI,SAAS,+BAA+B,EAAE,QAAQ,IAAI,CAAC;AAAA,EACpE;AAEA,QAAM,UAAU,IAAI,YAAY;AAEhC,QAAM,SAAS,IAAI,eAAe;AAAA,IAChC,MAAM,YAAY;AAEhB,YAAM,aAAa,SAAS,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC,CAAC;AAAA;AAAA;AACjE,iBAAW,QAAQ,QAAQ,OAAO,UAAU,CAAC;AAE7C,YAAM,WAAW,KAAK,QAAQ,IAAI,GAAG,MAAM;AAG3C,YAAM,UAAU;AAAA,QACd;AAAA,QACA,EAAE,WAAW,KAAK;AAAA,QAClB,CAAC,WAAW,aAAa;AACvB,cAAI,CAAC,SAAU;AAGf,cAAI,SAAS,SAAS,MAAM,KAAK,SAAS,SAAS,OAAO,GAAG;AAC3D,oBAAQ,IAAI,eAAe,SAAS,KAAK,QAAQ,EAAE;AAEnD,kBAAM,UAAU,SAAS,KAAK,UAAU;AAAA,cACtC,MAAM;AAAA,cACN,MAAM;AAAA,cACN;AAAA,YACF,CAAC,CAAC;AAAA;AAAA;AAEF,gBAAI;AACF,yBAAW,QAAQ,QAAQ,OAAO,OAAO,CAAC;AAAA,YAC5C,SAAS,OAAO;AACd,sBAAQ,MAAM,sCAAsC,KAAK;AAAA,YAC3D;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAGA,cAAQ,OAAO,iBAAiB,SAAS,MAAM;AAC7C,gBAAQ,IAAI,iCAAiC;AAC7C,gBAAQ,MAAM;AACd,YAAI;AACF,qBAAW,MAAM;AAAA,QACnB,SAAS,OAAO;AAAA,QAEhB;AAAA,MACF,CAAC;AAGD,cAAQ,GAAG,SAAS,CAAC,UAAU;AAC7B,gBAAQ,MAAM,8BAA8B,KAAK;AACjD,gBAAQ,MAAM;AACd,YAAI;AACF,qBAAW,MAAM;AAAA,QACnB,SAAS,GAAG;AAAA,QAEZ;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF,CAAC;AAED,SAAO,IAAI,SAAS,QAAQ;AAAA,IAC1B,SAAS;AAAA,MACP,gBAAgB;AAAA,MAChB,iBAAiB;AAAA,MACjB,cAAc;AAAA,IAChB;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/app/docs-page.d.mts

@@ -0,0 +1,32 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Metadata } from 'next';
+
+interface PageProps {
+    params: Promise<{
+        version: string;
+        slug: string[];
+    }>;
+}
+/**
+ * Generate metadata for documentation pages
+ * This is exported so users can re-export it from their page.tsx
+ */
+declare function generateMetadata({ params }: PageProps): Promise<Metadata>;
+/**
+ * Generate static params for all documentation pages
+ * This enables static generation at build time
+ */
+declare function generateStaticParams(): Promise<{
+    version: string;
+    slug: string[];
+}[]>;
+/**
+ * Documentation page component
+ * Handles:
+ * - Regular documentation pages
+ * - Category index pages (with or without content)
+ * - 404 pages (when doc not found)
+ */
+declare function DocPage({ params }: PageProps): Promise<react_jsx_runtime.JSX.Element>;
+
+export { DocPage as default, generateMetadata, generateStaticParams };

package/dist/app/docs-page.d.ts

@@ -0,0 +1,32 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Metadata } from 'next';
+
+interface PageProps {
+    params: Promise<{
+        version: string;
+        slug: string[];
+    }>;
+}
+/**
+ * Generate metadata for documentation pages
+ * This is exported so users can re-export it from their page.tsx
+ */
+declare function generateMetadata({ params }: PageProps): Promise<Metadata>;
+/**
+ * Generate static params for all documentation pages
+ * This enables static generation at build time
+ */
+declare function generateStaticParams(): Promise<{
+    version: string;
+    slug: string[];
+}[]>;
+/**
+ * Documentation page component
+ * Handles:
+ * - Regular documentation pages
+ * - Category index pages (with or without content)
+ * - 404 pages (when doc not found)
+ */
+declare function DocPage({ params }: PageProps): Promise<react_jsx_runtime.JSX.Element>;
+
+export { DocPage as default, generateMetadata, generateStaticParams };