specra 0.1.14 → 0.2.1

package/dist/config.schema.json

@@ -0,0 +1,471 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Specra Configuration",
+  "description": "Configuration schema for Specra documentation system",
+  "type": "object",
+  "required": ["site"],
+  "properties": {
+    "site": {
+      "type": "object",
+      "description": "Site metadata and branding",
+      "required": ["title"],
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "The title of the documentation site"
+        },
+        "description": {
+          "type": "string",
+          "description": "Short description of the documentation"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL where the documentation is hosted"
+        },
+        "baseUrl": {
+          "type": "string",
+          "description": "Base URL path for the documentation (e.g., '/docs')"
+        },
+        "logo": {
+          "description": "Path to the site logo - can be a string or an object with light/dark variants",
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "light": {
+                  "type": "string"
+                },
+                "dark": {
+                  "type": "string"
+                }
+              },
+              "required": ["light", "dark"]
+            }
+          ]
+        },
+        "favicon": {
+          "type": "string",
+          "description": "Path to the favicon"
+        },
+        "language": {
+          "type": "string",
+          "description": "Default language for the documentation"
+        },
+        "organizationName": {
+          "type": "string",
+          "description": "Organization or author name"
+        },
+        "projectName": {
+          "type": "string",
+          "description": "Project name"
+        },
+        "activeVersion": {
+          "type": "string",
+          "description": "Active/default version for the documentation"
+        },
+        "hideTitle": {
+          "type": "boolean",
+          "description": "Whether to hide the site title in the header"
+        },
+        "hideLogo": {
+          "type": "boolean",
+          "description": "Whether to hide the site logo in the header"
+        }
+      }
+    },
+    "theme": {
+      "type": "object",
+      "description": "Theme and appearance settings",
+      "properties": {
+        "primaryColor": {
+          "type": "string",
+          "description": "Primary color for the theme"
+        },
+        "defaultMode": {
+          "type": "string",
+          "enum": ["light", "dark", "system"],
+          "description": "Default theme mode"
+        },
+        "respectPrefersColorScheme": {
+          "type": "boolean",
+          "description": "Whether to respect system preferences"
+        },
+        "customCss": {
+          "type": "string",
+          "description": "Custom CSS file path"
+        }
+      }
+    },
+    "navigation": {
+      "type": "object",
+      "description": "Navigation and sidebar configuration",
+      "properties": {
+        "showSidebar": {
+          "type": "boolean",
+          "description": "Whether to show the sidebar by default"
+        },
+        "collapsibleSidebar": {
+          "type": "boolean",
+          "description": "Whether the sidebar is collapsible"
+        },
+        "showBreadcrumbs": {
+          "type": "boolean",
+          "description": "Whether to show breadcrumbs"
+        },
+        "showTableOfContents": {
+          "type": "boolean",
+          "description": "Whether to show table of contents"
+        },
+        "tocPosition": {
+          "type": "string",
+          "enum": ["left", "right"],
+          "description": "Position of table of contents"
+        },
+        "tocMaxDepth": {
+          "type": "number",
+          "description": "Maximum depth for table of contents"
+        },
+        "tabGroups": {
+          "type": "array",
+          "description": "Tab groups for organizing documentation sections",
+          "items": {
+            "type": "object",
+            "required": ["id", "label"],
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Unique identifier for the tab group"
+              },
+              "label": {
+                "type": "string",
+                "description": "Display label for the tab"
+              },
+              "icon": {
+                "type": "string",
+                "description": "Optional icon name (lucide-react icon)"
+              }
+            }
+          }
+        }
+      }
+    },
+    "social": {
+      "type": "object",
+      "description": "Social and external links",
+      "properties": {
+        "github": {
+          "type": "string",
+          "format": "uri",
+          "description": "GitHub repository URL"
+        },
+        "twitter": {
+          "type": "string",
+          "description": "Twitter/X handle or URL"
+        },
+        "discord": {
+          "type": "string",
+          "format": "uri",
+          "description": "Discord invite URL"
+        },
+        "linkedin": {
+          "type": "string",
+          "format": "uri",
+          "description": "LinkedIn profile or company page"
+        },
+        "youtube": {
+          "type": "string",
+          "format": "uri",
+          "description": "YouTube channel URL"
+        },
+        "custom": {
+          "type": "array",
+          "description": "Custom social links",
+          "items": {
+            "type": "object",
+            "required": ["label", "href"],
+            "properties": {
+              "label": {
+                "type": "string"
+              },
+              "href": {
+                "type": "string",
+                "format": "uri"
+              },
+              "icon": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "search": {
+      "type": "object",
+      "description": "Search configuration",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable/disable search functionality"
+        },
+        "placeholder": {
+          "type": "string",
+          "description": "Placeholder text for search input"
+        },
+        "provider": {
+          "type": "string",
+          "enum": ["meilisearch", "algolia", "local"],
+          "description": "Search provider type"
+        },
+        "meilisearch": {
+          "type": "object",
+          "description": "Meilisearch configuration",
+          "required": ["host", "indexName"],
+          "properties": {
+            "host": {
+              "type": "string",
+              "format": "uri",
+              "description": "Meilisearch server URL"
+            },
+            "apiKey": {
+              "type": "string",
+              "description": "API key for Meilisearch"
+            },
+            "indexName": {
+              "type": "string",
+              "description": "Index name"
+            }
+          }
+        }
+      }
+    },
+    "analytics": {
+      "type": "object",
+      "description": "Analytics configuration",
+      "properties": {
+        "googleAnalytics": {
+          "type": "string",
+          "description": "Google Analytics tracking ID"
+        },
+        "googleTagManager": {
+          "type": "string",
+          "description": "Google Tag Manager ID"
+        },
+        "plausible": {
+          "type": "string",
+          "description": "Plausible Analytics domain"
+        },
+        "custom": {
+          "type": "array",
+          "description": "Custom analytics scripts",
+          "items": {
+            "type": "object",
+            "required": ["src"],
+            "properties": {
+              "src": {
+                "type": "string",
+                "format": "uri"
+              },
+              "async": {
+                "type": "boolean"
+              },
+              "defer": {
+                "type": "boolean"
+              }
+            }
+          }
+        }
+      }
+    },
+    "footer": {
+      "type": "object",
+      "description": "Footer configuration",
+      "properties": {
+        "copyright": {
+          "type": "string",
+          "description": "Copyright text"
+        },
+        "links": {
+          "type": "array",
+          "description": "Footer links organized by columns",
+          "items": {
+            "type": "object",
+            "required": ["title", "items"],
+            "properties": {
+              "title": {
+                "type": "string"
+              },
+              "items": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["label", "href"],
+                  "properties": {
+                    "label": {
+                      "type": "string"
+                    },
+                    "href": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "customContent": {
+          "type": "string",
+          "description": "Custom footer content"
+        },
+        "branding": {
+          "type": "object",
+          "description": "Branding configuration for 'Powered by' section",
+          "properties": {
+            "showBranding": {
+              "type": "boolean",
+              "description": "Whether to show the branding"
+            },
+            "logo": {
+              "description": "Logo for the branding - can be a string or an object with light/dark variants",
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "light": {
+                      "type": "string"
+                    },
+                    "dark": {
+                      "type": "string"
+                    }
+                  },
+                  "required": ["light", "dark"]
+                }
+              ]
+            },
+            "title": {
+              "type": "string",
+              "description": "Title text for the branding"
+            },
+            "url": {
+              "type": "string",
+              "format": "uri",
+              "description": "URL to link to when branding is clicked"
+            }
+          }
+        }
+      }
+    },
+    "banner": {
+      "type": "object",
+      "description": "Site-wide banner configuration",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether the banner is enabled"
+        },
+        "message": {
+          "type": "string",
+          "description": "Banner message"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["info", "warning", "success", "error"],
+          "description": "Banner type"
+        },
+        "dismissible": {
+          "type": "boolean",
+          "description": "Whether the banner can be dismissed"
+        }
+      }
+    },
+    "features": {
+      "type": "object",
+      "description": "Documentation features",
+      "properties": {
+        "editUrl": {
+          "description": "Enable/disable edit this page links",
+          "oneOf": [
+            {
+              "type": "string",
+              "format": "uri"
+            },
+            {
+              "type": "boolean",
+              "enum": [false]
+            }
+          ]
+        },
+        "showLastUpdated": {
+          "type": "boolean",
+          "description": "Show last updated timestamp"
+        },
+        "showReadingTime": {
+          "type": "boolean",
+          "description": "Show reading time estimate"
+        },
+        "showAuthors": {
+          "type": "boolean",
+          "description": "Show author information"
+        },
+        "showTags": {
+          "type": "boolean",
+          "description": "Show tags"
+        },
+        "versioning": {
+          "type": "boolean",
+          "description": "Enable version dropdown"
+        },
+        "i18n": {
+          "type": "boolean",
+          "description": "Enable i18n (internationalization)"
+        }
+      }
+    },
+    "env": {
+      "type": "object",
+      "description": "Environment variables that can be used in documentation",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "properties": {
+        "API_BASE_URL": {
+          "type": "string",
+          "description": "API base URL"
+        },
+        "API_VERSION": {
+          "type": "string",
+          "description": "API version"
+        },
+        "CDN_URL": {
+          "type": "string",
+          "description": "CDN URL"
+        }
+      }
+    },
+    "deployment": {
+      "type": "object",
+      "description": "Deployment configuration for different hosting scenarios",
+      "properties": {
+        "target": {
+          "type": "string",
+          "enum": ["vercel", "github-pages", "static", "custom-domain-static"],
+          "description": "Deployment target"
+        },
+        "basePath": {
+          "type": "string",
+          "description": "Base path for assets when deploying to GitHub Pages without custom domain"
+        },
+        "customDomain": {
+          "type": "boolean",
+          "description": "Whether a custom domain is configured"
+        }
+      }
+    }
+  }
+}

package/dist/config.server.d.ts

@@ -0,0 +1,46 @@
+import type { SpecraConfig } from "./config.types";
+/**
+ * Load and parse the Specra configuration file
+ * Falls back to default configuration if file doesn't exist or is invalid
+ */
+export declare function loadConfig(userConfig: Partial<SpecraConfig>): SpecraConfig;
+/**
+ * Get a specific configuration value by path (SERVER ONLY)
+ * Example: getConfigValue('site.title') or getConfigValue('theme.defaultMode')
+ */
+export declare function getConfigValue<T = any>(path: string, config?: SpecraConfig): T | undefined;
+/**
+ * Replace environment variables in a string (SERVER ONLY)
+ * Supports ${ENV_VAR} and {{ENV_VAR}} syntax
+ */
+export declare function replaceEnvVariables(text: string, config?: SpecraConfig): string;
+/**
+ * Process content and replace all environment variables (SERVER ONLY)
+ */
+export declare function processContentWithEnv(content: string, config?: SpecraConfig): string;
+/**
+ * Validate configuration (basic validation) (SERVER ONLY)
+ */
+export declare function validateConfig(config: SpecraConfig): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Initialize the Specra configuration
+ * Can be called multiple times - subsequent calls will update the config
+ * @param userConfig - Partial configuration to merge with defaults
+ * @returns The initialized configuration
+ */
+export declare function initConfig(userConfig: Partial<SpecraConfig>): SpecraConfig;
+/**
+ * Get the configuration instance (cached) (SERVER ONLY)
+ * If not initialized, returns default config
+ */
+export declare function getConfig(): SpecraConfig;
+/**
+ * Reload the configuration (useful for development) (SERVER ONLY)
+ */
+export declare function reloadConfig(userConfig: Partial<SpecraConfig>): SpecraConfig;
+/**
+ * Export the loaded config as default (SERVER ONLY)
+ */

package/dist/config.server.js

@@ -0,0 +1,149 @@
+import { defaultConfig } from "./config.types";
+/**
+ * Deep merge two objects
+ */
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+        const sourceValue = source[key];
+        const targetValue = result[key];
+        if (sourceValue && typeof sourceValue === "object" && !Array.isArray(sourceValue)) {
+            result[key] = deepMerge(targetValue && typeof targetValue === "object" ? targetValue : {}, sourceValue);
+        }
+        else if (sourceValue !== undefined) {
+            result[key] = sourceValue;
+        }
+    }
+    return result;
+}
+/**
+ * Load and parse the Specra configuration file
+ * Falls back to default configuration if file doesn't exist or is invalid
+ */
+export function loadConfig(userConfig) {
+    try {
+        // const userConfig = specraConfigJson as unknown as Partial<SpecraConfig>
+        // Merge user config with defaults  
+        const config = deepMerge(defaultConfig, userConfig);
+        return config;
+    }
+    catch (error) {
+        console.error(`❌ Error loading configuration:`, error);
+        console.warn("Using default configuration.");
+        return defaultConfig;
+    }
+}
+/**
+ * Get a specific configuration value by path (SERVER ONLY)
+ * Example: getConfigValue('site.title') or getConfigValue('theme.defaultMode')
+ */
+export function getConfigValue(path, config) {
+    const cfg = config || loadConfig({});
+    const keys = path.split(".");
+    let value = cfg;
+    for (const key of keys) {
+        if (value && typeof value === "object" && key in value) {
+            value = value[key];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return value;
+}
+/**
+ * Replace environment variables in a string (SERVER ONLY)
+ * Supports ${ENV_VAR} and {{ENV_VAR}} syntax
+ */
+export function replaceEnvVariables(text, config) {
+    const cfg = config || loadConfig({});
+    const envVars = cfg.env || {};
+    let result = text;
+    // Replace ${VAR} syntax
+    result = result.replace(/\$\{([^}]+)\}/g, (match, varName) => {
+        return envVars[varName] || match;
+    });
+    // Replace {{VAR}} syntax
+    result = result.replace(/\{\{([^}]+)\}\}/g, (match, varName) => {
+        return envVars[varName] || match;
+    });
+    return result;
+}
+/**
+ * Process content and replace all environment variables (SERVER ONLY)
+ */
+export function processContentWithEnv(content, config) {
+    return replaceEnvVariables(content, config);
+}
+/**
+ * Validate configuration (basic validation) (SERVER ONLY)
+ */
+export function validateConfig(config) {
+    const errors = [];
+    // Required fields
+    if (!config.site?.title) {
+        errors.push("site.title is required");
+    }
+    // URL validation
+    if (config.site?.url) {
+        try {
+            new URL(config.site.url);
+        }
+        catch {
+            errors.push("site.url must be a valid URL");
+        }
+    }
+    // Social links validation
+    if (config.social) {
+        const socialKeys = ["github", "twitter", "discord", "linkedin", "youtube"];
+        for (const key of socialKeys) {
+            const url = config.social[key];
+            if (url) {
+                try {
+                    new URL(url);
+                }
+                catch {
+                    errors.push(`social.${key} must be a valid URL`);
+                }
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+// Singleton instance
+let configInstance = null;
+/**
+ * Initialize the Specra configuration
+ * Can be called multiple times - subsequent calls will update the config
+ * @param userConfig - Partial configuration to merge with defaults
+ * @returns The initialized configuration
+ */
+export function initConfig(userConfig) {
+    configInstance = loadConfig(userConfig);
+    return configInstance;
+}
+/**
+ * Get the configuration instance (cached) (SERVER ONLY)
+ * If not initialized, returns default config
+ */
+export function getConfig() {
+    if (!configInstance) {
+        // Auto-initialize with defaults if not already initialized
+        configInstance = loadConfig({});
+    }
+    return configInstance;
+}
+/**
+ * Reload the configuration (useful for development) (SERVER ONLY)
+ */
+export function reloadConfig(userConfig) {
+    configInstance = loadConfig(userConfig);
+    return configInstance;
+}
+/**
+ * Export the loaded config as default (SERVER ONLY)
+ */
+// export default getConfig()