@alliance-droid/svelte-docs-system 0.0.1

package/src/lib/stores/version.ts

@@ -0,0 +1,111 @@
+import { writable } from 'svelte/store';
+
+export interface VersionMetadata {
+  version: string;
+  label: string;
+  isLatest: boolean;
+  releaseDate?: string;
+  status?: 'stable' | 'beta' | 'deprecated';
+}
+
+export interface VersionConfig {
+  current: string;
+  availableVersions: VersionMetadata[];
+}
+
+function createVersionStore() {
+  // Default version configuration
+  const defaultConfig: VersionConfig = {
+    current: '2.0',
+    availableVersions: [
+      {
+        version: '2.0',
+        label: 'v2.0 (Latest)',
+        isLatest: true,
+        releaseDate: '2026-02-04',
+        status: 'stable',
+      },
+      {
+        version: '1.5',
+        label: 'v1.5',
+        isLatest: false,
+        releaseDate: '2025-12-01',
+        status: 'stable',
+      },
+      {
+        version: '1.0',
+        label: 'v1.0 (Archive)',
+        isLatest: false,
+        releaseDate: '2025-10-01',
+        status: 'deprecated',
+      },
+    ],
+  };
+
+  const getInitialVersion = (): string => {
+    if (typeof window === 'undefined') {
+      return defaultConfig.current;
+    }
+
+    try {
+      // Check localStorage for stored version preference
+      const stored = localStorage?.getItem?.('docs-version');
+      if (stored) {
+        return stored;
+      }
+    } catch (e) {
+      // localStorage may not be available in some environments
+    }
+
+    return defaultConfig.current;
+  };
+
+  const { subscribe, set, update } = writable<VersionConfig>({
+    ...defaultConfig,
+    current: getInitialVersion(),
+  });
+
+  return {
+    subscribe,
+    setVersion: (version: string) => {
+      update((config) => {
+        if (config.availableVersions.some((v) => v.version === version)) {
+          if (typeof window !== 'undefined') {
+            try {
+              localStorage?.setItem?.('docs-version', version);
+            } catch (e) {
+              // localStorage may not be available
+            }
+          }
+          return { ...config, current: version };
+        }
+        return config;
+      });
+    },
+    addVersion: (metadata: VersionMetadata) => {
+      update((config) => ({
+        ...config,
+        availableVersions: [
+          ...config.availableVersions.filter((v) => v.version !== metadata.version),
+          metadata,
+        ],
+      }));
+    },
+    removeVersion: (version: string) => {
+      update((config) => ({
+        ...config,
+        availableVersions: config.availableVersions.filter((v) => v.version !== version),
+      }));
+    },
+    getVersionMetadata: (version: string): VersionMetadata | undefined => {
+      let metadata: VersionMetadata | undefined;
+      const unsubscribe = subscribe((config) => {
+        metadata = config.availableVersions.find((v) => v.version === version);
+      });
+      unsubscribe();
+      return metadata;
+    },
+  };
+}
+
+export const version = createVersionStore();

package/src/lib/themeCustomization.test.ts

@@ -0,0 +1,223 @@
+import { describe, it, expect } from 'vitest';
+import {
+  generateCSSVariables,
+  createCSSVariablesStylesheet,
+  parseColor,
+  validateTheme,
+  mergeThemes,
+  getThemeTemplate,
+} from './themeCustomization';
+
+describe('Theme Customization', () => {
+  describe('generateCSSVariables', () => {
+    it('should generate CSS variables from theme config', () => {
+      const theme = {
+        primary: '#ff0000',
+        secondary: '#00ff00',
+        fontFamily: 'Arial',
+      };
+
+      const vars = generateCSSVariables(theme);
+      expect(vars['--color-primary']).toBe('#ff0000');
+      expect(vars['--color-secondary']).toBe('#00ff00');
+      expect(vars['--font-family-body']).toBe('Arial');
+    });
+
+    it('should skip undefined values', () => {
+      const theme = { primary: '#ff0000' };
+      const vars = generateCSSVariables(theme);
+
+      expect(Object.keys(vars)).toContain('--color-primary');
+      expect(Object.keys(vars)).not.toContain('--color-secondary');
+    });
+
+    it('should handle all color properties', () => {
+      const theme = {
+        primary: '#1',
+        secondary: '#2',
+        textLight: '#3',
+        textDark: '#4',
+        bgLight: '#5',
+        bgDark: '#6',
+        sidebarBg: '#7',
+        navbarBg: '#8',
+        codeBg: '#9',
+      };
+
+      const vars = generateCSSVariables(theme);
+      expect(Object.keys(vars)).toHaveLength(9);
+    });
+
+    it('should handle all font properties', () => {
+      const theme = {
+        fontFamily: 'sans-serif',
+        headingFont: 'serif',
+      };
+
+      const vars = generateCSSVariables(theme);
+      expect(vars['--font-family-body']).toBe('sans-serif');
+      expect(vars['--font-family-heading']).toBe('serif');
+    });
+  });
+
+  describe('createCSSVariablesStylesheet', () => {
+    it('should create valid CSS string', () => {
+      const vars = { '--color-primary': '#ff0000' };
+      const css = createCSSVariablesStylesheet(vars);
+
+      expect(css).toContain(':root');
+      expect(css).toContain('--color-primary: #ff0000');
+    });
+
+    it('should include multiple variables', () => {
+      const vars = {
+        '--color-primary': '#ff0000',
+        '--color-secondary': '#00ff00',
+      };
+
+      const css = createCSSVariablesStylesheet(vars);
+      expect(css).toContain('--color-primary');
+      expect(css).toContain('--color-secondary');
+    });
+  });
+
+  describe('parseColor', () => {
+    it('should parse hex colors', () => {
+      expect(parseColor('#ff0000').valid).toBe(true);
+      expect(parseColor('#f00').valid).toBe(true);
+      expect(parseColor('#ff0000aa').valid).toBe(true);
+    });
+
+    it('should parse RGB colors', () => {
+      expect(parseColor('rgb(255, 0, 0)').valid).toBe(true);
+      expect(parseColor('rgba(255, 0, 0, 0.5)').valid).toBe(true);
+    });
+
+    it('should parse named colors', () => {
+      expect(parseColor('red').valid).toBe(true);
+      expect(parseColor('blue').valid).toBe(true);
+      expect(parseColor('transparent').valid).toBe(true);
+    });
+
+    it('should parse CSS variables', () => {
+      expect(parseColor('var(--color-primary)').valid).toBe(true);
+    });
+
+    it('should reject invalid colors', () => {
+      expect(parseColor('invalid').valid).toBe(false);
+      expect(parseColor('#').valid).toBe(false);
+      expect(parseColor('').valid).toBe(false);
+    });
+
+    it('should return error message for invalid colors', () => {
+      const result = parseColor('not-a-color');
+      expect(result.valid).toBe(false);
+      expect(result.error).toBeDefined();
+    });
+  });
+
+  describe('validateTheme', () => {
+    it('should validate valid theme', () => {
+      const theme = {
+        primary: '#ff0000',
+        secondary: 'blue',
+        fontFamily: 'Arial',
+      };
+
+      const result = validateTheme(theme);
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('should reject non-object theme', () => {
+      const result = validateTheme('not-object' as any);
+      expect(result.valid).toBe(false);
+      expect(result.errors.length).toBeGreaterThan(0);
+    });
+
+    it('should validate all color fields', () => {
+      const theme = {
+        primary: 'invalid-color',
+      };
+
+      const result = validateTheme(theme);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.includes('primary'))).toBe(true);
+    });
+
+    it('should validate font fields are strings', () => {
+      const theme = {
+        fontFamily: 123 as any,
+      };
+
+      const result = validateTheme(theme);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.includes('fontFamily'))).toBe(true);
+    });
+  });
+
+  describe('mergeThemes', () => {
+    it('should merge two themes with priority to first', () => {
+      const primary = { primary: '#ff0000' };
+      const secondary = { primary: '#00ff00', secondary: '#0000ff' };
+
+      const merged = mergeThemes(primary, secondary);
+      expect(merged.primary).toBe('#ff0000');
+      expect(merged.secondary).toBe('#0000ff');
+    });
+
+    it('should handle undefined values', () => {
+      const primary = { primary: '#ff0000' };
+      const secondary = { secondary: '#00ff00' };
+
+      const merged = mergeThemes(primary, secondary);
+      expect(merged.primary).toBe('#ff0000');
+      expect(merged.secondary).toBe('#00ff00');
+    });
+  });
+
+  describe('getThemeTemplate', () => {
+    it('should return default theme', () => {
+      const theme = getThemeTemplate('default');
+      expect(theme.primary).toBeDefined();
+      expect(theme.fontFamily).toBeDefined();
+    });
+
+    it('should return dark theme', () => {
+      const theme = getThemeTemplate('dark');
+      expect(theme.primary).toBeDefined();
+      // Dark theme might have different colors
+      expect(theme.bgDark).toBeDefined();
+    });
+
+    it('should return minimal theme', () => {
+      const theme = getThemeTemplate('minimal');
+      expect(theme.primary).toBe('#000000');
+    });
+
+    it('should return colorful theme', () => {
+      const theme = getThemeTemplate('colorful');
+      expect(theme.primary).toBe('#ff006e');
+    });
+
+    it('should default to default theme if invalid', () => {
+      const theme = getThemeTemplate('invalid' as any);
+      expect(theme).toEqual(getThemeTemplate('default'));
+    });
+
+    it('should return default if not specified', () => {
+      const theme = getThemeTemplate();
+      expect(theme).toEqual(getThemeTemplate('default'));
+    });
+
+    it('all theme templates should be valid', () => {
+      const templates = ['default', 'dark', 'minimal', 'colorful'] as const;
+
+      templates.forEach((templateName) => {
+        const theme = getThemeTemplate(templateName);
+        const result = validateTheme(theme);
+        expect(result.valid).toBe(true);
+      });
+    });
+  });
+});

package/src/lib/themeCustomization.ts

@@ -0,0 +1,212 @@
+/**
+ * Theme customization system
+ * Generates CSS variables from theme configuration
+ */
+
+import type { ThemeConfig } from './config';
+
+export interface CSSVariables {
+  [key: string]: string;
+}
+
+/**
+ * Generate CSS custom properties (variables) from theme config
+ * These can be injected into the document or stylesheet
+ */
+export function generateCSSVariables(theme: ThemeConfig): CSSVariables {
+  const vars: CSSVariables = {};
+
+  // Color variables
+  if (theme.primary) vars['--color-primary'] = theme.primary;
+  if (theme.secondary) vars['--color-secondary'] = theme.secondary;
+  if (theme.textLight) vars['--color-text-light'] = theme.textLight;
+  if (theme.textDark) vars['--color-text-dark'] = theme.textDark;
+  if (theme.bgLight) vars['--color-bg-light'] = theme.bgLight;
+  if (theme.bgDark) vars['--color-bg-dark'] = theme.bgDark;
+  if (theme.sidebarBg) vars['--color-sidebar-bg'] = theme.sidebarBg;
+  if (theme.navbarBg) vars['--color-navbar-bg'] = theme.navbarBg;
+  if (theme.codeBg) vars['--color-code-bg'] = theme.codeBg;
+
+  // Font variables
+  if (theme.fontFamily) vars['--font-family-body'] = theme.fontFamily;
+  if (theme.headingFont) vars['--font-family-heading'] = theme.headingFont;
+
+  return vars;
+}
+
+/**
+ * Apply CSS variables to the document root
+ */
+export function applyCSSVariables(vars: CSSVariables): void {
+  if (typeof window === 'undefined') {
+    return; // Skip in SSR
+  }
+
+  const root = document.documentElement;
+  Object.entries(vars).forEach(([key, value]) => {
+    root.style.setProperty(key, value);
+  });
+}
+
+/**
+ * Create a stylesheet string from CSS variables
+ * Useful for injecting into <style> tags
+ */
+export function createCSSVariablesStylesheet(vars: CSSVariables): string {
+  const entries = Object.entries(vars)
+    .map(([key, value]) => `  ${key}: ${value};`)
+    .join('\n');
+
+  return `:root {\n${entries}\n}`;
+}
+
+/**
+ * Parse a color value and validate it
+ */
+export function parseColor(color: string): { valid: boolean; value?: string; error?: string } {
+  if (!color || typeof color !== 'string') {
+    return { valid: false, error: 'Color must be a non-empty string' };
+  }
+
+  const trimmed = color.trim();
+
+  // Hex colors
+  if (/^#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?([0-9a-fA-F]{2})?$/.test(trimmed)) {
+    return { valid: true, value: trimmed };
+  }
+
+  // RGB/RGBA
+  if (/^rgba?\s*\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}(\s*,\s*[\d.]+)?\s*\)$/.test(trimmed)) {
+    return { valid: true, value: trimmed };
+  }
+
+  // Named colors (basic list)
+  const namedColors = [
+    'red',
+    'blue',
+    'green',
+    'white',
+    'black',
+    'gray',
+    'grey',
+    'transparent',
+    'currentColor',
+  ];
+  if (namedColors.includes(trimmed.toLowerCase())) {
+    return { valid: true, value: trimmed };
+  }
+
+  // CSS custom property
+  if (/^var\s*\(\s*--[a-zA-Z0-9-]+\s*\)$/.test(trimmed)) {
+    return { valid: true, value: trimmed };
+  }
+
+  return { valid: false, error: `Invalid color format: ${color}` };
+}
+
+/**
+ * Validate theme configuration
+ */
+export function validateTheme(theme: ThemeConfig): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (!theme || typeof theme !== 'object') {
+    return { valid: false, errors: ['Theme must be an object'] };
+  }
+
+  // Validate colors
+  const colorFields = ['primary', 'secondary', 'textLight', 'textDark', 'bgLight', 'bgDark', 'sidebarBg', 'navbarBg', 'codeBg'] as const;
+  colorFields.forEach((field) => {
+    if (theme[field] !== undefined) {
+      const validation = parseColor(theme[field]!);
+      if (!validation.valid) {
+        errors.push(`${field}: ${validation.error}`);
+      }
+    }
+  });
+
+  // Validate fonts
+  if (theme.fontFamily !== undefined && typeof theme.fontFamily !== 'string') {
+    errors.push('fontFamily must be a string');
+  }
+
+  if (theme.headingFont !== undefined && typeof theme.headingFont !== 'string') {
+    errors.push('headingFont must be a string');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Merge theme configs, with priority to the first argument
+ */
+export function mergeThemes(primary: ThemeConfig, secondary: ThemeConfig): ThemeConfig {
+  return {
+    ...secondary,
+    ...primary,
+  };
+}
+
+/**
+ * Get a predefined theme template
+ */
+export type ThemeTemplate = 'default' | 'dark' | 'minimal' | 'colorful';
+
+export function getThemeTemplate(template: ThemeTemplate = 'default'): ThemeConfig {
+  const templates: Record<ThemeTemplate, ThemeConfig> = {
+    default: {
+      primary: '#0066cc',
+      secondary: '#ff6b6b',
+      textLight: '#333333',
+      textDark: '#f0f0f0',
+      bgLight: '#ffffff',
+      bgDark: '#1a1a1a',
+      sidebarBg: '#f5f5f5',
+      navbarBg: '#ffffff',
+      codeBg: '#f4f4f4',
+      fontFamily: 'system-ui, -apple-system, sans-serif',
+      headingFont: 'system-ui, -apple-system, sans-serif',
+    },
+    dark: {
+      primary: '#4da6ff',
+      secondary: '#ff9999',
+      textLight: '#e0e0e0',
+      textDark: '#1a1a1a',
+      bgLight: '#1a1a1a',
+      bgDark: '#0d0d0d',
+      sidebarBg: '#262626',
+      navbarBg: '#1a1a1a',
+      codeBg: '#2d2d2d',
+      fontFamily: 'system-ui, -apple-system, sans-serif',
+      headingFont: 'system-ui, -apple-system, sans-serif',
+    },
+    minimal: {
+      primary: '#000000',
+      secondary: '#666666',
+      textLight: '#333333',
+      textDark: '#cccccc',
+      bgLight: '#ffffff',
+      bgDark: '#181818',
+      sidebarBg: '#fafafa',
+      navbarBg: '#ffffff',
+      codeBg: '#eeeeee',
+      fontFamily: 'Georgia, serif',
+      headingFont: 'Georgia, serif',
+    },
+    colorful: {
+      primary: '#ff006e',
+      secondary: '#00d9ff',
+      textLight: '#2d3142',
+      textDark: '#e0e0e0',
+      bgLight: '#fafafa',
+      bgDark: '#0d1b2a',
+      sidebarBg: '#f0f3ff',
+      navbarBg: '#ffffff',
+      codeBg: '#f5f5f5',
+      fontFamily: 'system-ui, -apple-system, sans-serif',
+      headingFont: '"Segoe UI", Tahoma, sans-serif',
+    },
+  };
+
+  return templates[template] || templates.default;
+}

package/src/lib/utils/highlight.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest';
+import { highlightSearchTerms, truncateText, extractExcerpt } from './highlight';
+
+describe('Highlight Utilities', () => {
+	describe('highlightSearchTerms', () => {
+		it('should highlight single search term', () => {
+			const text = 'This is a test sentence';
+			const result = highlightSearchTerms(text, 'test');
+			expect(result).toContain('<mark>test</mark>');
+		});
+
+		it('should highlight multiple occurrences', () => {
+			const text = 'test case with test words';
+			const result = highlightSearchTerms(text, 'test');
+			const matches = (result.match(/<mark>test<\/mark>/g) || []).length;
+			expect(matches).toBe(2);
+		});
+
+		it('should handle multiple search terms', () => {
+			const text = 'This is a test case';
+			const result = highlightSearchTerms(text, 'test case');
+			expect(result).toContain('<mark>test</mark>');
+			expect(result).toContain('<mark>case</mark>');
+		});
+
+		it('should be case insensitive', () => {
+			const text = 'TEST and Test and test';
+			const result = highlightSearchTerms(text, 'test');
+			const matches = (result.match(/<mark>/g) || []).length;
+			expect(matches).toBe(3);
+		});
+
+		it('should handle special regex characters', () => {
+			const text = 'This (test) has [special] {chars}';
+			const result = highlightSearchTerms(text, 'test');
+			expect(result).toContain('<mark>test</mark>');
+			expect(result).not.toThrow;
+		});
+
+		it('should return original text if search query is empty', () => {
+			const text = 'This is a test';
+			const result = highlightSearchTerms(text, '');
+			expect(result).toBe(text);
+		});
+
+		it('should return empty string if text is empty', () => {
+			const result = highlightSearchTerms('', 'test');
+			expect(result).toBe('');
+		});
+
+		it('should use word boundaries', () => {
+			const text = 'testing test';
+			const result = highlightSearchTerms(text, 'test');
+			// Should highlight 'test' in 'testing' as part of word, and 'test' as standalone
+			// Actually, \b word boundary means 'test' won't match in 'testing'
+			const matches = (result.match(/<mark>test<\/mark>/g) || []).length;
+			expect(matches).toBe(1); // Only the standalone 'test'
+		});
+	});
+
+	describe('truncateText', () => {
+		it('should not truncate short text', () => {
+			const text = 'Short text';
+			const result = truncateText(text, 50);
+			expect(result).toBe(text);
+		});
+
+		it('should truncate long text with ellipsis', () => {
+			const text = 'This is a very long text that should be truncated';
+			const result = truncateText(text, 20);
+			expect(result).toContain('...');
+			expect(result.length).toBeLessThan(text.length);
+		});
+
+		it('should truncate at word boundary if possible', () => {
+			const text = 'This is a test sentence for truncation';
+			const result = truncateText(text, 15);
+			expect(result.endsWith('...')).toBe(true);
+			// Result should have ellipsis and be shorter
+			expect(result.length).toBeLessThan(text.length);
+		});
+
+		it('should use default max length', () => {
+			const longText = 'a'.repeat(200);
+			const result = truncateText(longText);
+			expect(result).toContain('...');
+			expect(result.length).toBeLessThan(longText.length);
+		});
+	});
+
+	describe('extractExcerpt', () => {
+		it('should extract text around search term', () => {
+			const text = 'The quick brown fox jumps over the lazy dog';
+			const result = extractExcerpt(text, 'brown', 20);
+			expect(result).toContain('brown');
+		});
+
+		it('should return truncated text if no search query', () => {
+			const text = 'a'.repeat(300);
+			const result = extractExcerpt(text, '', 50);
+			expect(result).toContain('...');
+		});
+
+		it('should handle short excerpts', () => {
+			const text = 'The quick brown fox jumps';
+			const result = extractExcerpt(text, 'brown', 30);
+			expect(result).toContain('brown');
+		});
+
+		it('should handle longer text with excerpt', () => {
+			const text = 'The quick brown fox jumps over lazy dog';
+			const result = extractExcerpt(text, 'brown', 50);
+			expect(result).toContain('brown');
+		});
+
+		it('should handle search term at start', () => {
+			const text = 'brown fox jumps';
+			const result = extractExcerpt(text, 'brown', 50);
+			expect(result).toContain('brown');
+			expect(result.startsWith('...')).toBe(false);
+		});
+
+		it('should handle search term at end', () => {
+			const text = 'the quick brown';
+			const result = extractExcerpt(text, 'brown', 50);
+			expect(result).toContain('brown');
+			expect(result.endsWith('...')).toBe(false);
+		});
+
+		it('should be case insensitive', () => {
+			const text = 'The Brown fox';
+			const result = extractExcerpt(text, 'brown', 50);
+			expect(result.toLowerCase()).toContain('brown');
+		});
+	});
+});