@alliance-droid/svelte-docs-system 0.0.1

package/src/lib/navigationBuilder.test.ts

@@ -0,0 +1,338 @@
+import { describe, it, expect } from 'vitest';
+import {
+  formatFileName,
+  parseFileInfo,
+  generateNavigationFromFiles,
+  validateNavigation,
+  filterFiles,
+  findNavItem,
+  getPrevNext,
+} from './navigationBuilder';
+
+describe('Navigation Builder', () => {
+  describe('formatFileName', () => {
+    it('should format file names to titles', () => {
+      expect(formatFileName('setup')).toBe('Setup');
+      expect(formatFileName('getting-started')).toBe('Getting Started');
+      expect(formatFileName('api_reference')).toBe('Api Reference');
+      expect(formatFileName('README')).toMatch(/readme/i);
+    });
+
+    it('should handle multiple word separators', () => {
+      expect(formatFileName('getting-started-guide')).toBe('Getting Started Guide');
+      expect(formatFileName('api_v2_reference')).toBe('Api V2 Reference');
+    });
+  });
+
+  describe('parseFileInfo', () => {
+    it('should parse file info from path', () => {
+      const info = parseFileInfo('docs/setup.md');
+      expect(info.path).toBe('docs/setup.md');
+      expect(info.name).toBe('setup');
+      expect(info.title).toBe('Setup');
+      expect(info.isIndex).toBe(false);
+    });
+
+    it('should detect index files', () => {
+      const info = parseFileInfo('docs/index.md');
+      expect(info.name).toBe('index');
+      expect(info.isIndex).toBe(true);
+    });
+
+    it('should handle nested paths', () => {
+      const info = parseFileInfo('docs/api/overview.md');
+      expect(info.name).toBe('overview');
+      expect(info.path).toBe('docs/api/overview.md');
+    });
+
+    it('should use frontmatter title if provided', () => {
+      const info = parseFileInfo('docs/setup.md', {
+        title: 'Custom Title',
+      });
+      expect(info.title).toBe('Custom Title');
+    });
+
+    it('should use frontmatter order if provided', () => {
+      const info = parseFileInfo('docs/setup.md', {
+        order: 5,
+      });
+      expect(info.order).toBe(5);
+    });
+  });
+
+  describe('generateNavigationFromFiles', () => {
+    it('should generate navigation from files', () => {
+      const files = [
+        parseFileInfo('docs/index.md'),
+        parseFileInfo('docs/setup.md'),
+        parseFileInfo('docs/api/overview.md'),
+      ];
+
+      const nav = generateNavigationFromFiles(files, '/docs');
+      expect(nav.length).toBeGreaterThan(0);
+      expect(nav[0].title).toBeDefined();
+    });
+
+    it('should create sections for directories', () => {
+      const files = [
+        parseFileInfo('docs/setup.md'),
+        parseFileInfo('docs/api/overview.md'),
+        parseFileInfo('docs/api/methods.md'),
+      ];
+
+      const nav = generateNavigationFromFiles(files, '/docs');
+      // Should have at least a root section and an api section
+      expect(nav.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it('should handle custom base route', () => {
+      const files = [parseFileInfo('docs/setup.md')];
+      const nav = generateNavigationFromFiles(files, '/help');
+
+      const items = nav.flatMap((s) => s.items);
+      const setupItem = items.find((i) => i.label === 'Setup');
+      expect(setupItem?.href).toContain('/help');
+    });
+
+    it('should sort files with index first', () => {
+      const files = [
+        parseFileInfo('docs/setup.md'),
+        parseFileInfo('docs/index.md'),
+        parseFileInfo('docs/guide.md'),
+      ];
+
+      const nav = generateNavigationFromFiles(files, '/docs');
+      const section = nav.find((s) => s.title === 'Documentation');
+      if (section) {
+        // Index should not appear in the items list as it's handled specially
+        expect(section.items.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('should respect order property', () => {
+      const files = [
+        parseFileInfo('docs/a.md', { order: 3 }),
+        parseFileInfo('docs/b.md', { order: 1 }),
+        parseFileInfo('docs/c.md', { order: 2 }),
+      ];
+
+      const nav = generateNavigationFromFiles(files, '/docs');
+      const section = nav.find((s) => s.title === 'Documentation');
+      if (section) {
+        expect(section.items[0].label).toContain('B'); // order 1
+        expect(section.items[1].label).toContain('C'); // order 2
+        expect(section.items[2].label).toContain('A'); // order 3
+      }
+    });
+  });
+
+  describe('validateNavigation', () => {
+    it('should validate valid navigation', () => {
+      const nav = {
+        title: 'My Docs',
+        sections: [
+          {
+            title: 'Getting Started',
+            items: [{ label: 'Setup', href: '/docs/setup' }],
+          },
+        ],
+      };
+
+      const result = validateNavigation(nav);
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('should reject non-object navigation', () => {
+      const result = validateNavigation('not-object' as any);
+      expect(result.valid).toBe(false);
+    });
+
+    it('should validate section structure', () => {
+      const nav = {
+        sections: [
+          {
+            title: 'Section',
+            items: [{ label: 'Item' }], // Missing href, but that's ok
+          },
+        ],
+      };
+
+      const result = validateNavigation(nav);
+      expect(result.valid).toBe(true);
+    });
+
+    it('should reject invalid section structure', () => {
+      const nav = {
+        sections: [
+          {
+            // Missing title
+            items: [],
+            title: undefined as any,
+          },
+        ],
+      } as any;
+
+      const result = validateNavigation(nav);
+      expect(result.valid).toBe(false);
+      expect(result.errors.length).toBeGreaterThan(0);
+    });
+
+    it('should validate exclude paths is array', () => {
+      const nav = {
+        excludePaths: 'not-array' as any,
+      };
+
+      const result = validateNavigation(nav);
+      expect(result.valid).toBe(false);
+    });
+  });
+
+  describe('filterFiles', () => {
+    it('should filter files by exclude patterns', () => {
+      const files = [
+        parseFileInfo('docs/setup.md'),
+        parseFileInfo('docs/draft.md'),
+        parseFileInfo('docs/api/overview.md'),
+      ];
+
+      const filtered = filterFiles(files, ['draft']);
+      expect(filtered.length).toBe(2);
+      expect(filtered.some((f) => f.name === 'draft')).toBe(false);
+    });
+
+    it('should exclude multiple patterns', () => {
+      const files = [
+        parseFileInfo('docs/setup.md'),
+        parseFileInfo('docs/draft.md'),
+        parseFileInfo('docs/private.md'),
+      ];
+
+      const filtered = filterFiles(files, ['draft', 'private']);
+      expect(filtered.length).toBe(1);
+      expect(filtered[0].name).toBe('setup');
+    });
+
+    it('should handle empty exclude list', () => {
+      const files = [parseFileInfo('docs/setup.md')];
+      const filtered = filterFiles(files, []);
+      expect(filtered).toEqual(files);
+    });
+  });
+
+  describe('findNavItem', () => {
+    it('should find nav item by href', () => {
+      const sections = [
+        {
+          title: 'Getting Started',
+          items: [{ label: 'Setup', href: '/docs/setup' }],
+        },
+      ];
+
+      const item = findNavItem(sections, '/docs/setup');
+      expect(item?.label).toBe('Setup');
+    });
+
+    it('should return null if not found', () => {
+      const sections = [
+        {
+          title: 'Getting Started',
+          items: [{ label: 'Setup', href: '/docs/setup' }],
+        },
+      ];
+
+      const item = findNavItem(sections, '/docs/missing');
+      expect(item).toBeNull();
+    });
+
+    it('should find items in nested children', () => {
+      const sections = [
+        {
+          title: 'Docs',
+          items: [
+            {
+              label: 'API',
+              children: [{ label: 'Reference', href: '/docs/api/reference' }],
+            },
+          ],
+        },
+      ];
+
+      const item = findNavItem(sections, '/docs/api/reference');
+      expect(item?.label).toBe('Reference');
+    });
+  });
+
+  describe('getPrevNext', () => {
+    it('should get previous and next items', () => {
+      const sections = [
+        {
+          title: 'Docs',
+          items: [
+            { label: 'First', href: '/docs/1' },
+            { label: 'Second', href: '/docs/2' },
+            { label: 'Third', href: '/docs/3' },
+          ],
+        },
+      ];
+
+      const result = getPrevNext(sections, '/docs/2');
+      expect(result.prev?.label).toBe('First');
+      expect(result.next?.label).toBe('Third');
+    });
+
+    it('should handle first item', () => {
+      const sections = [
+        {
+          title: 'Docs',
+          items: [
+            { label: 'First', href: '/docs/1' },
+            { label: 'Second', href: '/docs/2' },
+          ],
+        },
+      ];
+
+      const result = getPrevNext(sections, '/docs/1');
+      expect(result.prev).toBeNull();
+      expect(result.next?.label).toBe('Second');
+    });
+
+    it('should handle last item', () => {
+      const sections = [
+        {
+          title: 'Docs',
+          items: [
+            { label: 'First', href: '/docs/1' },
+            { label: 'Last', href: '/docs/2' },
+          ],
+        },
+      ];
+
+      const result = getPrevNext(sections, '/docs/2');
+      expect(result.prev?.label).toBe('First');
+      expect(result.next).toBeNull();
+    });
+
+    it('should work with nested items', () => {
+      const sections = [
+        {
+          title: 'Docs',
+          items: [
+            { label: 'First', href: '/docs/1' },
+            {
+              label: 'Group',
+              children: [
+                { label: 'Nested', href: '/docs/nested' },
+                { label: 'Nested2', href: '/docs/nested2' },
+              ],
+            },
+            { label: 'Last', href: '/docs/last' },
+          ],
+        },
+      ];
+
+      const result = getPrevNext(sections, '/docs/nested2');
+      expect(result.next?.label).toBe('Last');
+    });
+  });
+});

package/src/lib/navigationBuilder.ts

@@ -0,0 +1,268 @@
+/**
+ * Navigation builder for generating navigation from folder structure or config
+ */
+
+import type { NavItem, NavSection, NavigationConfig } from './config';
+
+export interface FileInfo {
+  /** Full file path (e.g., docs/api/overview.md) */
+  path: string;
+  /** File name without extension (e.g., overview) */
+  name: string;
+  /** File title (from frontmatter or derived from name) */
+  title?: string;
+  /** File order (from frontmatter) */
+  order?: number;
+  /** Is this the index file? */
+  isIndex: boolean;
+}
+
+/**
+ * Convert a file name to a display title
+ * Example: "api-reference" -> "API Reference"
+ */
+export function formatFileName(name: string): string {
+  return name
+    .replace(/[-_]/g, ' ') // Replace hyphens and underscores with spaces
+    .replace(/\b\w/g, (char) => char.toUpperCase()); // Capitalize first letter of each word
+}
+
+/**
+ * Parse file information from path
+ * Example: "docs/api/reference.md" -> { path: "docs/api/reference.md", name: "reference", isIndex: false }
+ */
+export function parseFileInfo(filePath: string, fileMetadata?: { title?: string; order?: number }): FileInfo {
+  const cleanPath = filePath.replace(/^\.\//, ''); // Remove leading ./
+  const lastSlash = cleanPath.lastIndexOf('/');
+  const fileName = cleanPath.substring(lastSlash + 1);
+  const name = fileName.replace(/\.md$/, '');
+
+  return {
+    path: cleanPath,
+    name,
+    title: fileMetadata?.title || formatFileName(name),
+    order: fileMetadata?.order,
+    isIndex: name === 'index',
+  };
+}
+
+/**
+ * Group files by directory
+ */
+function groupFilesByDirectory(files: FileInfo[]): Map<string, FileInfo[]> {
+  const groups = new Map<string, FileInfo[]>();
+
+  files.forEach((file) => {
+    const match = file.path.match(/^docs\/(.+)\/[^/]+\.md$/);
+    const dir = match ? match[1] : 'root';
+
+    if (!groups.has(dir)) {
+      groups.set(dir, []);
+    }
+    groups.get(dir)!.push(file);
+  });
+
+  return groups;
+}
+
+/**
+ * Sort files by order, then alphabetically
+ */
+function sortFiles(files: FileInfo[]): FileInfo[] {
+  return [...files].sort((a, b) => {
+    // Priority to index files at the top
+    if (a.isIndex && !b.isIndex) return -1;
+    if (!a.isIndex && b.isIndex) return 1;
+
+    // Then sort by order if specified
+    if (a.order !== undefined && b.order !== undefined) {
+      return a.order - b.order;
+    }
+    if (a.order !== undefined) return -1;
+    if (b.order !== undefined) return 1;
+
+    // Finally alphabetically
+    return a.name.localeCompare(b.name);
+  });
+}
+
+/**
+ * Generate navigation from a list of files
+ * Useful for auto-generating sidebar from folder structure
+ */
+export function generateNavigationFromFiles(files: FileInfo[], baseRoute: string = '/docs'): NavSection[] {
+  const groups = groupFilesByDirectory(files);
+  const sections: NavSection[] = [];
+
+  // Process files in natural order
+  const sortedDirs = Array.from(groups.keys()).sort((a, b) => {
+    if (a === 'root') return -1;
+    if (b === 'root') return 1;
+    return a.localeCompare(b);
+  });
+
+  sortedDirs.forEach((dir) => {
+    const dirFiles = sortFiles(groups.get(dir)!);
+
+    if (dir === 'root') {
+      // Root files go to main section
+      dirFiles.forEach((file) => {
+        if (!file.isIndex) {
+          if (!sections[0]) {
+            sections.push({ title: 'Documentation', items: [] });
+          }
+          sections[0].items.push({
+            label: file.title || file.name,
+            href: `${baseRoute}/${file.name}`,
+          });
+        }
+      });
+    } else {
+      // Directory files go to their own section
+      const sectionTitle = formatFileName(dir);
+      const items: NavItem[] = dirFiles.map((file) => ({
+        label: file.title || file.name,
+        href: `${baseRoute}/${dir}/${file.name}`,
+      }));
+
+      sections.push({ title: sectionTitle, items });
+    }
+  });
+
+  return sections;
+}
+
+/**
+ * Flatten navigation sections to a single array of NavItems
+ */
+export function flattenNavigation(sections: NavSection[]): NavItem[] {
+  const items: NavItem[] = [];
+
+  sections.forEach((section) => {
+    items.push({
+      label: section.title,
+      children: section.items,
+    });
+  });
+
+  return items;
+}
+
+/**
+ * Validate navigation configuration
+ */
+export function validateNavigation(nav: NavigationConfig): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (!nav || typeof nav !== 'object') {
+    return { valid: false, errors: ['Navigation must be an object'] };
+  }
+
+  if (nav.sections !== undefined) {
+    if (!Array.isArray(nav.sections)) {
+      errors.push('sections must be an array');
+    } else {
+      nav.sections.forEach((section, idx) => {
+        if (!section.title) {
+          errors.push(`Section ${idx}: missing title`);
+        }
+        if (!Array.isArray(section.items)) {
+          errors.push(`Section ${idx}: items must be an array`);
+        } else {
+          section.items.forEach((item, itemIdx) => {
+            if (!item.label) {
+              errors.push(`Section ${idx}, item ${itemIdx}: missing label`);
+            }
+          });
+        }
+      });
+    }
+  }
+
+  if (nav.excludePaths !== undefined && !Array.isArray(nav.excludePaths)) {
+    errors.push('excludePaths must be an array');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Filter files based on exclude patterns
+ */
+export function filterFiles(files: FileInfo[], excludePatterns: string[] = []): FileInfo[] {
+  return files.filter((file) => {
+    return !excludePatterns.some((pattern) => {
+      // Simple pattern matching (could be extended to regex)
+      return file.path.includes(pattern);
+    });
+  });
+}
+
+/**
+ * Build navigation from a config object
+ */
+export function buildNavigationFromConfig(
+  config: NavigationConfig,
+  files?: FileInfo[],
+  baseRoute: string = '/docs'
+): NavSection[] {
+  // If explicit sections are provided, use them
+  if (config.sections && config.sections.length > 0) {
+    return config.sections;
+  }
+
+  // Otherwise auto-generate from files
+  if (files && files.length > 0) {
+    const filtered = filterFiles(files, config.excludePaths);
+    return generateNavigationFromFiles(filtered, baseRoute);
+  }
+
+  // Return empty navigation
+  return [];
+}
+
+/**
+ * Find a navigation item by href
+ */
+export function findNavItem(sections: NavSection[], href: string): NavItem | null {
+  for (const section of sections) {
+    for (const item of section.items) {
+      if (item.href === href) {
+        return item;
+      }
+      if (item.children) {
+        const found = item.children.find((child) => child.href === href);
+        if (found) return found;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Get previous and next navigation items in order
+ */
+export function getPrevNext(
+  sections: NavSection[],
+  currentHref: string
+): { prev: NavItem | null; next: NavItem | null } {
+  const allItems: NavItem[] = [];
+
+  sections.forEach((section) => {
+    section.items.forEach((item) => {
+      if (item.href) allItems.push(item);
+      if (item.children) {
+        item.children.forEach((child) => {
+          if (child.href) allItems.push(child);
+        });
+      }
+    });
+  });
+
+  const currentIndex = allItems.findIndex((item) => item.href === currentHref);
+
+  return {
+    prev: currentIndex > 0 ? allItems[currentIndex - 1] : null,
+    next: currentIndex < allItems.length - 1 ? allItems[currentIndex + 1] : null,
+  };
+}