@alliance-droid/svelte-docs-system 0.0.2 → 0.1.0

package/src/lib/config.ts

@@ -1,179 +0,0 @@
-/**
- * Configuration schema and types for the documentation system
- */
-
-export interface ThemeConfig {
-  /** Primary color (hex, rgb, or CSS color name) */
-  primary?: string;
-  /** Secondary color */
-  secondary?: string;
-  /** Text color for light mode */
-  textLight?: string;
-  /** Text color for dark mode */
-  textDark?: string;
-  /** Background color for light mode */
-  bgLight?: string;
-  /** Background color for dark mode */
-  bgDark?: string;
-  /** Font family for body text */
-  fontFamily?: string;
-  /** Font family for headings */
-  headingFont?: string;
-  /** Sidebar background color */
-  sidebarBg?: string;
-  /** Navbar background color */
-  navbarBg?: string;
-  /** Code block background color */
-  codeBg?: string;
-}
-
-export interface NavItem {
-  label: string;
-  href?: string;
-  children?: NavItem[];
-  icon?: string;
-}
-
-export interface NavSection {
-  title: string;
-  items: NavItem[];
-}
-
-export interface NavigationConfig {
-  title?: string;
-  logo?: string;
-  sections?: NavSection[];
-  /** Auto-generate navigation from folder structure */
-  autoGenerate?: boolean;
-  /** Exclude paths from auto-generation */
-  excludePaths?: string[];
-}
-
-export interface ConfigOptions {
-  /** Name of the documentation project */
-  name?: string;
-  /** Mount point for docs (e.g., /docs, /help, /guides) */
-  docsRoute?: string;
-  /** Path to docs folder relative to project root */
-  docsFolderPath?: string;
-  /** Base URL path for links */
-  basePath?: string;
-  /** Theme configuration */
-  theme?: ThemeConfig;
-  /** Navigation configuration */
-  navigation?: NavigationConfig;
-  /** Enable search functionality */
-  enableSearch?: boolean;
-  /** Custom CSS file path */
-  customCss?: string;
-  /** Layout template name (default, minimal, full-width) */
-  layout?: 'default' | 'minimal' | 'full-width';
-  /** Enable dark mode toggle */
-  darkMode?: boolean;
-  /** Default theme (light or dark) */
-  defaultTheme?: 'light' | 'dark';
-  /** Enable breadcrumbs */
-  breadcrumbs?: boolean;
-  /** Enable prev/next navigation */
-  prevNext?: boolean;
-  /** Site title for header */
-  siteTitle?: string;
-  /** Site description for meta tags */
-  siteDescription?: string;
-}
-
-/**
- * Default configuration values
- */
-export const DEFAULT_CONFIG: ConfigOptions = {
-  name: 'Documentation',
-  docsRoute: '/docs',
-  docsFolderPath: './docs',
-  basePath: '/docs',
-  enableSearch: true,
-  layout: 'default',
-  darkMode: true,
-  defaultTheme: 'light',
-  breadcrumbs: true,
-  prevNext: true,
-  theme: {
-    primary: '#0066cc',
-    secondary: '#ff6b6b',
-    fontFamily: 'system-ui, -apple-system, sans-serif',
-    headingFont: 'system-ui, -apple-system, sans-serif',
-  },
-  navigation: {
-    autoGenerate: true,
-  },
-};
-
-/**
- * Validates a configuration object
- */
-export function validateConfig(config: unknown): { valid: boolean; errors: string[] } {
-  const errors: string[] = [];
-
-  if (typeof config !== 'object' || config === null) {
-    errors.push('Configuration must be an object');
-    return { valid: false, errors };
-  }
-
-  const cfg = config as Record<string, unknown>;
-
-  // Validate docsRoute
-  if (cfg.docsRoute !== undefined) {
-    if (typeof cfg.docsRoute !== 'string') {
-      errors.push('docsRoute must be a string');
-    } else if (!cfg.docsRoute.startsWith('/')) {
-      errors.push('docsRoute must start with /');
-    }
-  }
-
-  // Validate layout
-  if (cfg.layout !== undefined) {
-    if (!['default', 'minimal', 'full-width'].includes(cfg.layout as string)) {
-      errors.push('layout must be one of: default, minimal, full-width');
-    }
-  }
-
-  // Validate defaultTheme
-  if (cfg.defaultTheme !== undefined) {
-    if (!['light', 'dark'].includes(cfg.defaultTheme as string)) {
-      errors.push('defaultTheme must be either light or dark');
-    }
-  }
-
-  // Validate theme config
-  if (cfg.theme !== undefined) {
-    if (typeof cfg.theme !== 'object' || cfg.theme === null) {
-      errors.push('theme must be an object');
-    }
-  }
-
-  // Validate navigation config
-  if (cfg.navigation !== undefined) {
-    if (typeof cfg.navigation !== 'object' || cfg.navigation === null) {
-      errors.push('navigation must be an object');
-    }
-  }
-
-  return { valid: errors.length === 0, errors };
-}
-
-/**
- * Merges user config with defaults
- */
-export function mergeConfig(userConfig: ConfigOptions, defaults: ConfigOptions = DEFAULT_CONFIG): ConfigOptions {
-  return {
-    ...defaults,
-    ...userConfig,
-    theme: {
-      ...defaults.theme,
-      ...(userConfig.theme || {}),
-    },
-    navigation: {
-      ...defaults.navigation,
-      ...(userConfig.navigation || {}),
-    },
-  };
-}

package/src/lib/configIntegration.test.ts

@@ -1,272 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { mergeConfig, validateConfig, DEFAULT_CONFIG } from './config';
-import { parseConfigFile } from './configParser';
-import { createRouteConfig, validateRoute, buildNavLink, isDocsRoute } from './routing';
-import { generateNavigationFromFiles } from './navigationBuilder';
-import { generateCSSVariables, validateTheme, getThemeTemplate } from './themeCustomization';
-
-describe('Configuration System Integration', () => {
-  describe('Full Config Workflow', () => {
-    it('should load and validate a complete configuration', () => {
-      const configContent = JSON.stringify({
-        name: 'My Documentation',
-        docsRoute: '/help',
-        theme: {
-          primary: '#0066cc',
-          secondary: '#ff6b6b',
-        },
-        navigation: {
-          title: 'Help Center',
-          autoGenerate: true,
-        },
-      });
-
-      const parseResult = parseConfigFile(configContent, 'config.json');
-      expect(parseResult.errors).toHaveLength(0);
-
-      const validation = validateConfig(parseResult.config);
-      expect(validation.valid).toBe(true);
-
-      const merged = mergeConfig(parseResult.config);
-      expect(merged.docsRoute).toBe('/help');
-      expect(merged.theme?.primary).toBe('#0066cc');
-    });
-
-    it('should handle config with custom route mount point', () => {
-      const config = mergeConfig({
-        docsRoute: '/guides',
-        docsFolderPath: './guides',
-        basePath: '/guides',
-      });
-
-      expect(config.docsRoute).toBe('/guides');
-      expect(config.basePath).toBe('/guides');
-
-      // Validate the route
-      expect(validateRoute(config.docsRoute!)).toBe(true);
-
-      // Create route config
-      const routeConfig = createRouteConfig(config);
-      expect(routeConfig.docsRoute).toBe('/guides');
-    });
-
-    it('should build correct navigation links with custom route', () => {
-      const config = mergeConfig({ docsRoute: '/help' });
-      const docsRoute = config.docsRoute || '/docs';
-
-      const link1 = buildNavLink('setup', docsRoute);
-      expect(link1).toBe('/help/setup');
-
-      const link2 = buildNavLink('api/overview', docsRoute);
-      expect(link2).toBe('/help/api/overview');
-
-      const link3 = buildNavLink('', docsRoute);
-      expect(link3).toBe('/help');
-    });
-
-    it('should verify routes with custom mount point', () => {
-      const config = mergeConfig({ docsRoute: '/documentation' });
-      const docsRoute = config.docsRoute || '/docs';
-
-      expect(isDocsRoute('/documentation', docsRoute)).toBe(true);
-      expect(isDocsRoute('/documentation/api', docsRoute)).toBe(true);
-      expect(isDocsRoute('/help', docsRoute)).toBe(false);
-    });
-  });
-
-  describe('Theme Configuration Integration', () => {
-    it('should apply theme configuration from config file', () => {
-      const themeConfig = getThemeTemplate('default');
-      const cssVars = generateCSSVariables(themeConfig);
-
-      expect(cssVars['--color-primary']).toBeDefined();
-      expect(cssVars['--color-secondary']).toBeDefined();
-      expect(cssVars['--font-family-body']).toBeDefined();
-    });
-
-    it('should validate custom theme config', () => {
-      const config = mergeConfig({
-        theme: {
-          primary: '#ff0000',
-          secondary: '#00ff00',
-          fontFamily: 'Arial, sans-serif',
-        },
-      });
-
-      const themeValidation = validateTheme(config.theme!);
-      expect(themeValidation.valid).toBe(true);
-    });
-
-    it('should override default theme with config', () => {
-      const config = mergeConfig({
-        theme: {
-          primary: '#custom-color',
-        },
-      });
-
-      expect(config.theme?.primary).toBe('#custom-color');
-      // Should still have default secondary
-      expect(config.theme?.secondary).toBe(DEFAULT_CONFIG.theme?.secondary);
-    });
-
-    it('should generate CSS for theme customization', () => {
-      const darkTheme = getThemeTemplate('dark');
-      const cssVars = generateCSSVariables(darkTheme);
-
-      const stylesheet = Object.entries(cssVars)
-        .map(([key, value]) => `  ${key}: ${value};`)
-        .join('\n');
-
-      expect(stylesheet).toContain('--color-primary');
-      expect(stylesheet).toContain('--font-family');
-    });
-  });
-
-  describe('Navigation Configuration Integration', () => {
-    it('should generate navigation from config', () => {
-      const files = [
-        { path: 'docs/index.md', name: 'index', title: 'Home', isIndex: true },
-        { path: 'docs/setup.md', name: 'setup', title: 'Setup', isIndex: false },
-        { path: 'docs/api/overview.md', name: 'overview', title: 'Overview', isIndex: false },
-        { path: 'docs/api/reference.md', name: 'reference', title: 'Reference', isIndex: false },
-      ];
-
-      const nav = generateNavigationFromFiles(files, '/docs');
-      expect(nav.length).toBeGreaterThan(0);
-
-      // Should have an API section
-      const apiSection = nav.find((s) => s.title.includes('api') || s.title.includes('API'));
-      if (apiSection) {
-        expect(apiSection.items.length).toBeGreaterThan(0);
-      }
-    });
-
-    it('should respect exclude patterns in navigation', () => {
-      const configContent = JSON.stringify({
-        navigation: {
-          excludePaths: ['draft', 'private'],
-          autoGenerate: true,
-        },
-      });
-
-      const parseResult = parseConfigFile(configContent, 'config.json');
-      expect(parseResult.errors).toHaveLength(0);
-      expect(parseResult.config.navigation?.excludePaths).toEqual(['draft', 'private']);
-    });
-  });
-
-  describe('Multi-Route Configuration', () => {
-    it('should support switching between different doc routes', () => {
-      // Project 1: /docs route
-      const config1 = mergeConfig({ docsRoute: '/docs' });
-      expect(config1.docsRoute).toBe('/docs');
-      expect(isDocsRoute('/docs/setup', config1.docsRoute!)).toBe(true);
-      expect(isDocsRoute('/help/setup', config1.docsRoute!)).toBe(false);
-
-      // Project 2: /help route
-      const config2 = mergeConfig({ docsRoute: '/help' });
-      expect(config2.docsRoute).toBe('/help');
-      expect(isDocsRoute('/help/setup', config2.docsRoute!)).toBe(true);
-      expect(isDocsRoute('/docs/setup', config2.docsRoute!)).toBe(false);
-
-      // Project 3: /guides route
-      const config3 = mergeConfig({ docsRoute: '/guides' });
-      expect(config3.docsRoute).toBe('/guides');
-      expect(isDocsRoute('/guides/tutorial', config3.docsRoute!)).toBe(true);
-    });
-  });
-
-  describe('End-to-End Configuration Scenario', () => {
-    it('should handle a complete doc system setup', () => {
-      // Simulate loading a config file
-      const configJSON = JSON.stringify({
-        name: 'API Documentation',
-        docsRoute: '/api-docs',
-        docsFolderPath: './docs/api',
-        enableSearch: true,
-        layout: 'full-width',
-        theme: {
-          primary: '#2563eb',
-          secondary: '#dc2626',
-          fontFamily: 'Inter, sans-serif',
-          headingFont: 'Poppins, sans-serif',
-        },
-        navigation: {
-          title: 'API Reference',
-          autoGenerate: true,
-          excludePaths: ['examples', 'draft'],
-        },
-      });
-
-      // Parse the config
-      const parseResult = parseConfigFile(configJSON, 'config.json');
-      expect(parseResult.errors).toHaveLength(0);
-
-      // Validate it
-      const validation = validateConfig(parseResult.config);
-      expect(validation.valid).toBe(true);
-
-      // Merge with defaults
-      const finalConfig = mergeConfig(parseResult.config);
-
-      // Verify all parts work together
-      expect(finalConfig.name).toBe('API Documentation');
-      expect(finalConfig.docsRoute).toBe('/api-docs');
-      expect(finalConfig.enableSearch).toBe(true);
-      expect(finalConfig.layout).toBe('full-width');
-
-      // Verify theme
-      const themeValidation = validateTheme(finalConfig.theme!);
-      expect(themeValidation.valid).toBe(true);
-
-      const cssVars = generateCSSVariables(finalConfig.theme!);
-      expect(cssVars['--color-primary']).toBe('#2563eb');
-      expect(cssVars['--font-family-body']).toBe('Inter, sans-serif');
-
-      // Verify routing
-      const routeConfig = createRouteConfig(finalConfig);
-      expect(validateRoute(routeConfig.docsRoute)).toBe(true);
-
-      // Verify navigation config
-      expect(finalConfig.navigation?.title).toBe('API Reference');
-      expect(finalConfig.navigation?.excludePaths).toEqual(['examples', 'draft']);
-
-      // Verify navigation with custom route
-      const testLink = buildNavLink('endpoints/users', routeConfig.docsRoute);
-      expect(testLink).toBe('/api-docs/endpoints/users');
-
-      // Verify route detection
-      expect(isDocsRoute('/api-docs', routeConfig.docsRoute)).toBe(true);
-      expect(isDocsRoute('/api-docs/endpoints', routeConfig.docsRoute)).toBe(true);
-      expect(isDocsRoute('/docs', routeConfig.docsRoute)).toBe(false);
-    });
-  });
-
-  describe('Configuration Validation Scenarios', () => {
-    it('should reject invalid configurations', () => {
-      const invalidConfigs = [
-        { docsRoute: 123 }, // Not a string
-        { layout: 'invalid-layout' },
-        { defaultTheme: 'blue' }, // Invalid theme value
-        { theme: 'not-an-object' }, // Theme must be object
-      ];
-
-      invalidConfigs.forEach((config) => {
-        const validation = validateConfig(config);
-        expect(validation.valid).toBe(false);
-        expect(validation.errors.length).toBeGreaterThan(0);
-      });
-    });
-
-    it('should provide helpful error messages', () => {
-      const invalidConfig = {
-        layout: 'unknown',
-        defaultTheme: 'invalid',
-      };
-
-      const validation = validateConfig(invalidConfig);
-      expect(validation.errors.length).toBeGreaterThan(0);
-      expect(validation.errors.some((e) => e.includes('layout') || e.includes('defaultTheme'))).toBe(true);
-    });
-  });
-});

package/src/lib/configLoader.ts

@@ -1,231 +0,0 @@
-/**
- * Configuration loader and manager
- * Loads, validates, and manages the docs system configuration
- */
-
-import type { ConfigOptions } from './config';
-import { DEFAULT_CONFIG, mergeConfig, validateConfig } from './config';
-import { parseConfigFile, loadConfigFile, parseFrontmatter } from './configParser';
-import { createRouteConfig, validateRoute } from './routing';
-import { validateTheme } from './themeCustomization';
-import { validateNavigation } from './navigationBuilder';
-
-export interface ConfigLoadResult {
-  success: boolean;
-  config: ConfigOptions;
-  errors: string[];
-  warnings: string[];
-  source: 'default' | 'loaded' | 'merged';
-}
-
-/**
- * Load configuration from a file
- */
-export async function loadConfiguration(
-  configPath: string = '/docs/_config.json'
-): Promise<ConfigLoadResult> {
-  const errors: string[] = [];
-  const warnings: string[] = [];
-  let userConfig: ConfigOptions = {};
-
-  // Try to load the config file
-  const result = await loadConfigFile(configPath);
-
-  if (result.errors.length > 0 && !configPath.includes('_config')) {
-    // If it's not a standard config file, it might not exist - that's ok
-    errors.push(...result.errors);
-  } else if (result.errors.length > 0) {
-    // For standard config file, log errors but continue with defaults
-    warnings.push(...result.errors);
-  } else {
-    userConfig = result.config;
-  }
-
-  // Validate the loaded config
-  const validation = validateConfig(userConfig);
-  if (!validation.valid) {
-    warnings.push(...validation.errors);
-  }
-
-  // Validate sub-configs
-  if (userConfig.theme) {
-    const themeValidation = validateTheme(userConfig.theme);
-    if (!themeValidation.valid) {
-      warnings.push(`Theme validation errors: ${themeValidation.errors.join(', ')}`);
-    }
-  }
-
-  if (userConfig.navigation) {
-    const navValidation = validateNavigation(userConfig.navigation);
-    if (!navValidation.valid) {
-      warnings.push(`Navigation validation errors: ${navValidation.errors.join(', ')}`);
-    }
-  }
-
-  // Validate route
-  if (userConfig.docsRoute && !validateRoute(userConfig.docsRoute)) {
-    errors.push(`Invalid docsRoute: ${userConfig.docsRoute}`);
-  }
-
-  // Merge with defaults
-  const finalConfig = mergeConfig(userConfig, DEFAULT_CONFIG);
-
-  // Validate final config
-  const finalValidation = validateConfig(finalConfig);
-  if (!finalValidation.valid) {
-    errors.push(...finalValidation.errors);
-  }
-
-  const success = errors.length === 0;
-
-  return {
-    success,
-    config: finalConfig,
-    errors,
-    warnings,
-    source: success ? 'loaded' : warnings.length > 0 ? 'merged' : 'default',
-  };
-}
-
-/**
- * Load and cache configuration (for browser environment)
- */
-let cachedConfig: ConfigOptions | null = null;
-let configLoadPromise: Promise<ConfigLoadResult> | null = null;
-
-export async function getConfiguration(configPath: string = '/docs/_config.json'): Promise<ConfigOptions> {
-  if (cachedConfig) {
-    return cachedConfig;
-  }
-
-  if (!configLoadPromise) {
-    configLoadPromise = loadConfiguration(configPath);
-  }
-
-  const result = await configLoadPromise;
-  cachedConfig = result.config;
-  return result.config;
-}
-
-/**
- * Clear configuration cache (useful for testing or reloading)
- */
-export function clearConfigCache(): void {
-  cachedConfig = null;
-  configLoadPromise = null;
-}
-
-/**
- * Parse frontmatter from markdown content and merge with config
- */
-export function parseMarkdownFrontmatter(content: string): {
-  frontmatter: Record<string, unknown>;
-  body: string;
-  errors: string[];
-} {
-  const result = parseFrontmatter(content);
-
-  if (result.error) {
-    return {
-      frontmatter: {},
-      body: result.body,
-      errors: [result.error],
-    };
-  }
-
-  return {
-    frontmatter: result.frontmatter || {},
-    body: result.body,
-    errors: [],
-  };
-}
-
-/**
- * Validate a custom config object
- */
-export function validateCustomConfig(config: unknown): { valid: boolean; errors: string[] } {
-  const validation = validateConfig(config);
-
-  if (!validation.valid) {
-    return validation;
-  }
-
-  const cfg = config as ConfigOptions;
-  const errors: string[] = [];
-
-  // Additional validations
-  if (cfg.theme) {
-    const themeValidation = validateTheme(cfg.theme);
-    if (!themeValidation.valid) {
-      errors.push(`Theme: ${themeValidation.errors.join(', ')}`);
-    }
-  }
-
-  if (cfg.navigation) {
-    const navValidation = validateNavigation(cfg.navigation);
-    if (!navValidation.valid) {
-      errors.push(`Navigation: ${navValidation.errors.join(', ')}`);
-    }
-  }
-
-  if (cfg.docsRoute && !validateRoute(cfg.docsRoute)) {
-    errors.push(`Invalid docsRoute: ${cfg.docsRoute}`);
-  }
-
-  return { valid: errors.length === 0, errors };
-}
-
-/**
- * Create a configuration from minimal user input
- */
-export function createMinimalConfig(options: Partial<ConfigOptions> = {}): ConfigOptions {
-  return mergeConfig(options, DEFAULT_CONFIG);
-}
-
-/**
- * Export configuration as JSON
- */
-export function exportConfigAsJSON(config: ConfigOptions): string {
-  return JSON.stringify(config, null, 2);
-}
-
-/**
- * Export configuration as YAML
- */
-export function exportConfigAsYAML(config: ConfigOptions): string {
-  const lines: string[] = [];
-
-  function addValue(key: string, value: unknown, indent: number = 0): void {
-    const indentStr = '  '.repeat(indent);
-
-    if (value === null || value === undefined) {
-      return;
-    }
-
-    if (typeof value === 'string') {
-      lines.push(`${indentStr}${key}: ${value}`);
-    } else if (typeof value === 'boolean' || typeof value === 'number') {
-      lines.push(`${indentStr}${key}: ${value}`);
-    } else if (Array.isArray(value)) {
-      lines.push(`${indentStr}${key}:`);
-      value.forEach((item, idx) => {
-        if (typeof item === 'object') {
-          addValue(`- `, item, indent + 1);
-        } else {
-          lines.push(`${indentStr}  - ${item}`);
-        }
-      });
-    } else if (typeof value === 'object') {
-      lines.push(`${indentStr}${key}:`);
-      Object.entries(value).forEach(([k, v]) => {
-        addValue(k, v, indent + 1);
-      });
-    }
-  }
-
-  Object.entries(config).forEach(([key, value]) => {
-    addValue(key, value);
-  });
-
-  return lines.join('\n');
-}