@knowcode/doc-builder 1.1.12 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to @knowcode/doc-builder will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2025-07-19
+
+### Added (MAJOR FEATURE RELEASE)
+- **Complete feature parity** with original JUNO documentation system
+- **Preview banner** with dismissible functionality and localStorage
+- **Breadcrumb navigation** automatically generated from URL structure
+- **Advanced sidebar** with filter/search functionality
+- **Hierarchical navigation** with collapsible folders and proper icons
+- **Rich tooltip system** with folder descriptions and hover information
+- **Resize handle** for adjustable sidebar width
+- **Icon mapping** for different content types and folders
+- **Folder descriptions** for better UX and navigation
+- **Logical folder ordering** (strategic content first, technical content later)
+
+### Enhanced Navigation Features
+- **Smart folder detection** and hierarchical structuring
+- **Active section auto-expansion** for current page context
+- **Collapsible navigation sections** with smooth animations
+- **File type icons** (documents, folders, special content types)
+- **Improved file naming** and title generation
+- **README.md as folder overviews** with proper linking
+- **Filter/search** through navigation items
+
+### Layout Improvements
+- **Complete layout restructure** matching original design
+- **Fixed positioning** for banner, breadcrumbs, and sidebar
+- **Responsive design** with mobile-friendly collapsible layout
+- **Proper content area** with max-width and centered layout
+- **Smooth transitions** and hover effects throughout
+- **Dark mode support** for all new components
+
+### Technical Enhancements
+- **Rich HTML structure** with semantic navigation
+- **CSS Grid and Flexbox** layout system
+- **Modern CSS variables** and consistent spacing
+- **Optimized mobile experience** with adaptive layouts
+- **Performance optimized** animations and transitions
+
 ## [1.1.12] - 2025-07-19
 
 ### Fixed (MAJOR)

package/assets/css/notion-style.css

@@ -372,32 +372,194 @@ pre code {
   font-size: var(--text-sm);
 }
 
-/* Layout Container */
-.container {
+/* Preview Banner */
+.preview-banner {
+  background: var(--color-accent-yellow-bg);
+  border-bottom: 1px solid var(--color-accent-yellow);
+  color: var(--color-text-primary);
+  padding: var(--space-2) 0;
+  position: fixed;
+  top: var(--header-height);
+  left: 0;
+  right: 0;
+  z-index: 1000;
+  transition: transform var(--duration-normal);
+}
+
+.preview-banner.hidden {
+  transform: translateY(-100%);
+}
+
+.banner-content {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-2);
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 0 var(--space-4);
+}
+
+.banner-icon {
+  color: var(--color-accent-yellow);
+  font-size: var(--text-sm);
+}
+
+.banner-text {
+  font-size: var(--text-sm);
+  font-weight: var(--font-medium);
+}
+
+.banner-dismiss {
+  background: none;
+  border: none;
+  color: var(--color-text-secondary);
+  cursor: pointer;
+  padding: var(--space-1);
+  margin-left: auto;
+  border-radius: var(--radius-sm);
+  transition: all var(--duration-fast);
+}
+
+.banner-dismiss:hover {
+  background: var(--color-bg-hover);
+  color: var(--color-text-primary);
+}
+
+/* Breadcrumbs */
+.breadcrumbs {
+  background: var(--color-bg-default);
+  border-bottom: 1px solid var(--color-border-default);
+  padding: var(--space-2) 0;
+  position: fixed;
+  top: calc(var(--header-height) + 3.5rem);
+  left: 0;
+  right: 0;
+  z-index: 900;
+  transition: top var(--duration-normal);
+}
+
+.breadcrumbs.banner-visible {
+  top: calc(var(--header-height) + 3.5rem);
+}
+
+.breadcrumbs:not(.banner-visible) {
+  top: var(--header-height);
+}
+
+.breadcrumb-item {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  color: var(--color-text-secondary);
+  text-decoration: none;
+  font-size: var(--text-sm);
+  padding: var(--space-1) var(--space-2);
+  border-radius: var(--radius-sm);
+  transition: all var(--duration-fast);
+}
+
+.breadcrumb-item:hover {
+  background: var(--color-bg-hover);
+  color: var(--color-text-primary);
+}
+
+.breadcrumb-item.current {
+  color: var(--color-text-primary);
+  font-weight: var(--font-medium);
+}
+
+.breadcrumb-separator {
+  color: var(--color-text-tertiary);
+  font-size: var(--text-xs);
+  margin: 0 var(--space-1);
+}
+
+/* Main Wrapper */
+.main-wrapper {
   display: flex;
-  height: calc(100vh - var(--header-height));
+  height: calc(100vh - var(--header-height) - var(--breadcrumb-height));
+  margin-top: calc(var(--header-height) + var(--breadcrumb-height));
   overflow: hidden;
 }
 
-/* Navigation */
-.navigation {
+.main-wrapper.banner-visible {
+  height: calc(100vh - var(--header-height) - var(--breadcrumb-height) - 3.5rem);
+  margin-top: calc(var(--header-height) + var(--breadcrumb-height) + 3.5rem);
+}
+
+/* Sidebar */
+.sidebar {
   width: var(--sidebar-width);
   background: var(--color-bg-secondary);
   border-right: 1px solid var(--color-border-default);
+  display: flex;
+  flex-direction: column;
+  position: relative;
+}
+
+.sidebar-header {
+  padding: var(--space-3);
+  border-bottom: 1px solid var(--color-border-default);
+}
+
+.filter-box {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+
+.filter-input {
+  width: 100%;
+  padding: var(--space-2) var(--space-8) var(--space-2) var(--space-3);
+  border: 1px solid var(--color-border-default);
+  border-radius: var(--radius-md);
+  background: var(--color-bg-default);
+  color: var(--color-text-primary);
+  font-size: var(--text-sm);
+  transition: all var(--duration-fast);
+}
+
+.filter-input:focus {
+  outline: none;
+  border-color: var(--color-border-focus);
+  box-shadow: 0 0 0 2px var(--color-accent-blue-bg);
+}
+
+.filter-icon {
+  position: absolute;
+  right: var(--space-3);
+  color: var(--color-text-tertiary);
+  pointer-events: none;
+}
+
+/* Navigation */
+.navigation {
+  flex: 1;
   padding: var(--space-2);
   overflow-y: auto;
   overflow-x: visible;
-  position: fixed;
-  top: var(--header-height);
-  left: 0;
-  height: calc(100vh - var(--header-height));
-  z-index: 100;
   
   /* Scrollbar styling */
   scrollbar-width: thin;
   scrollbar-color: var(--color-border-default) transparent;
 }
 
+.resize-handle {
+  width: 4px;
+  background: transparent;
+  cursor: col-resize;
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  transition: background var(--duration-fast);
+}
+
+.resize-handle:hover {
+  background: var(--color-border-focus);
+}
+
 .navigation::-webkit-scrollbar {
   width: 6px;
 }
@@ -543,15 +705,14 @@ pre code {
 
 .content {
   flex: 1;
-  margin-left: var(--sidebar-width);
   padding: var(--space-6) var(--space-8);
   overflow-y: auto;
-  height: calc(100vh - var(--header-height));
-  max-width: none;
+  background: var(--color-bg-default);
 }
 
 .content-inner {
   max-width: 65rem;
+  margin: 0 auto;
 }
 
 /* Tables */
@@ -1474,70 +1635,124 @@ tr:hover {
     display: none;
   }
   
-  .container {
+  .main-wrapper {
     flex-direction: column;
+    height: auto;
+    min-height: calc(100vh - var(--header-height) - var(--breadcrumb-height));
   }
   
-  .navigation {
-    position: relative;
+  .sidebar {
     width: 100%;
-    height: auto;
-    max-height: 200px;
-    top: 0;
-    left: 0;
+    max-height: 250px;
     border-right: none;
     border-bottom: 1px solid var(--color-border-default);
   }
   
   .content {
-    margin-left: 0;
-    height: auto;
-    min-height: calc(100vh - var(--header-height) - 200px);
+    padding: var(--space-4);
+  }
+  
+  .content-inner {
+    max-width: none;
+  }
+  
+  .preview-banner {
+    position: relative;
+    top: 0;
+  }
+  
+  .breadcrumbs {
+    position: relative;
+    top: 0;
   }
 }
 
-/* Navigation: Enhanced for all structures */
-.nav-item {
-  margin-bottom: var(--space-0-5);
+/* Navigation Sections */
+.nav-section {
+  margin-bottom: var(--space-1);
 }
 
-.nav-item .nav-link {
-  display: block;
-  padding: var(--space-1) var(--space-2);
-  color: var(--color-text-secondary);
+.nav-title {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-2);
+  color: var(--color-text-primary);
   text-decoration: none;
-  border-radius: var(--border-radius-md);
-  transition: all 0.2s ease;
   font-size: var(--text-sm);
-  font-weight: 400;
+  font-weight: var(--font-medium);
+  border-radius: var(--radius-md);
+  transition: all var(--duration-fast);
+  cursor: pointer;
 }
 
-.nav-item .nav-link:hover {
+.nav-title:hover {
   background: var(--color-bg-hover);
-  color: var(--color-text-primary);
 }
 
-.nav-item.active .nav-link,
-.nav-item .nav-link.active {
-  background: var(--color-accent-blue-bg);
-  color: var(--color-accent-blue);
-  font-weight: 500;
+.nav-title.collapsible {
+  position: relative;
 }
 
-/* Ensure nav sections are visible and functional */
-.nav-section {
-  margin-bottom: var(--space-1);
+.nav-title .collapse-icon {
+  transition: transform var(--duration-fast);
+  color: var(--color-text-tertiary);
+  font-size: var(--text-xs);
+}
+
+.nav-title.expanded .collapse-icon {
+  transform: rotate(90deg);
 }
 
 .nav-content {
-  padding-left: var(--space-2);
+  padding-left: var(--space-4);
+  overflow: hidden;
+  transition: max-height var(--duration-normal), opacity var(--duration-normal);
 }
 
-/* Override any conflicting styles */
-.navigation .nav-section .nav-content {
-  display: block;
+.nav-content.collapsed {
+  max-height: 0;
+  opacity: 0;
+  pointer-events: none;
 }
 
-.navigation .nav-section .nav-content.collapsed {
-  display: none;
+.nav-content:not(.collapsed) {
+  max-height: 1000px;
+  opacity: 1;
+}
+
+/* Navigation Items */
+.nav-item {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-1-5) var(--space-2);
+  color: var(--color-text-secondary);
+  text-decoration: none;
+  font-size: var(--text-sm);
+  border-radius: var(--radius-md);
+  transition: all var(--duration-fast);
+  margin-bottom: var(--space-0-5);
+}
+
+.nav-item:hover {
+  background: var(--color-bg-hover);
+  color: var(--color-text-primary);
+}
+
+.nav-item.active {
+  background: var(--color-accent-blue-bg);
+  color: var(--color-accent-blue);
+  font-weight: var(--font-medium);
+}
+
+.nav-item i {
+  color: var(--color-text-tertiary);
+  font-size: var(--text-xs);
+  width: 12px;
+  text-align: center;
+}
+
+.nav-item.active i {
+  color: var(--color-accent-blue);
 }

package/lib/core-builder.js

@@ -123,18 +123,43 @@ function generateHTML(title, content, navigation, currentPath = '', config = {})
         </div>
     </header>
     
-    <div class="container">
-        <!-- Navigation -->
-        <nav id="navigation" class="navigation">
-            <div class="nav-header">
-                <h3>${siteName}</h3>
+    <!-- Preview Banner -->
+    <div id="preview-banner" class="preview-banner">
+        <div class="banner-content">
+            <i class="fas fa-exclamation-triangle banner-icon"></i>
+            <span class="banner-text">This documentation is a preview version - some content may be incomplete</span>
+            <button id="dismiss-banner" class="banner-dismiss" aria-label="Dismiss banner">
+                <i class="fas fa-times"></i>
+            </button>
+        </div>
+    </div>
+    
+    <!-- Breadcrumbs -->
+    <nav class="breadcrumbs" id="breadcrumbs">
+        <!-- Breadcrumbs will be generated by JavaScript -->
+    </nav>
+    
+    <!-- Main Content -->
+    <div class="main-wrapper">
+        <!-- Sidebar -->
+        <aside class="sidebar">
+            <div class="sidebar-header">
+                <div class="filter-box">
+                    <input type="text" placeholder="Filter items..." class="filter-input" id="nav-filter">
+                    <i class="fas fa-search filter-icon"></i>
+                </div>
             </div>
-            ${navigation}
-        </nav>
+            <nav class="navigation">
+                ${navigation}
+            </nav>
+            <div class="resize-handle"></div>
+        </aside>
         
-        <!-- Main Content -->
+        <!-- Content Area -->
         <main class="content">
-            ${content}
+            <div class="content-inner">
+                ${content}
+            </div>
         </main>
     </div>
     
@@ -145,7 +170,28 @@ function generateHTML(title, content, navigation, currentPath = '', config = {})
 </html>`;
 }
 
-// Build navigation structure
+// Define folder descriptions for tooltips
+const folderDescriptions = {
+  'product-roadmap': 'Strategic vision, timeline, and feature planning',
+  'product-requirements': 'Detailed product specifications, requirements documents, and feature definitions',
+  'architecture': 'System design, data flows, and technical infrastructure documentation',
+  'system-analysis': 'Comprehensive system analysis, functional requirements, and cross-component documentation',
+  'bubble': 'Core application platform - business logic, UI/UX, and user workflows',
+  'quickbase': 'Database schema, data management, and backend operations',
+  'activecampaign': 'Marketing automation integration and lead management system',
+  'juno-signer': 'Document signing service for digital signatures and PDF generation',
+  'juno-api-deprecated': 'Legacy API documentation (deprecated, for reference only)',
+  'postman': 'API testing tools, collections, and test automation',
+  'mcp': 'Model Context Protocol integration and configuration',
+  'team': 'Team structure, roles, and responsibilities',
+  'thought-leadership': 'Strategic insights and industry perspectives',
+  'middleware': 'Integration layers and data transformation services',
+  'paths': 'User journey flows and process workflows',
+  'testing': 'Test strategies, scenarios, and quality assurance processes',
+  'juno-api': 'API documentation and integration guides'
+};
+
+// Build navigation structure with rich functionality
 function buildNavigationStructure(files, currentFile) {
   const tree = { files: [], folders: {} };
   
@@ -166,71 +212,176 @@ function buildNavigationStructure(files, currentFile) {
     current.files.push(file);
   });
   
-  // Check if this is a flat structure
-  const hasFolders = Object.keys(tree.folders).length > 0;
+  // Helper function to check if a node has active child
+  const checkActiveChild = (node, currentFile) => {
+    // Check files
+    if (node.files.some(f => f.urlPath === currentFile)) return true;
+    
+    // Check folders recursively
+    return Object.values(node.folders).some(folder => checkActiveChild(folder, currentFile));
+  };
   
-  if (!hasFolders) {
-    // Generate simple flat navigation that matches what JavaScript expects
-    let html = '<div class="nav-section">';
-    html += '<div class="nav-content">';
-    
-    tree.files.forEach(file => {
-      const isActive = file.urlPath === currentFile;
-      const href = file.urlPath.replace(/\\/g, '/');
-      html += `<div class="nav-item ${isActive ? 'active' : ''}">
-        <a href="${href}" class="nav-link ${isActive ? 'active' : ''}">
-          <span class="nav-text">${file.displayName}</span>
+  // Helper function to generate file title
+  const generateFileTitle = (file, parentDisplayName, level) => {
+    let title = file.displayName;
+    
+    if (file.displayName === 'README') {
+      return level === 0 ? 'Overview' : `${parentDisplayName} Overview`;
+    }
+    
+    // Clean up title by removing common prefixes and improving formatting
+    title = title
+      .replace(/^(bubble|system|quickbase|middleware|product-roadmap)-?/, '')
+      .replace(/-/g, ' ')
+      .replace(/\b\w/g, l => l.toUpperCase());
+    
+    return title;
+  };
+  
+  // Helper function to render a section
+  const renderSection = (folderName, folderData, level = 0, parentPath = '') => {
+    const icons = {
+      'root': 'fas fa-home',
+      'product-roadmap': 'fas fa-road',
+      'product-requirements': 'fas fa-clipboard-list',
+      'architecture': 'fas fa-sitemap',
+      'system-analysis': 'fas fa-chart-line',
+      'system': 'fas fa-cogs',
+      'bubble': 'fas fa-circle',
+      'quickbase': 'fas fa-database',
+      'activecampaign': 'fas fa-envelope',
+      'juno-signer': 'fas fa-signature',
+      'juno-api-deprecated': 'fas fa-archive',
+      'postman': 'fas fa-flask',
+      'mcp': 'fas fa-puzzle-piece',
+      'team': 'fas fa-users',
+      'thought-leadership': 'fas fa-lightbulb',
+      'middleware': 'fas fa-layer-group',
+      'paths': 'fas fa-route',
+      'testing': 'fas fa-vial',
+      'juno-api': 'fas fa-plug',
+      'documentation-tool': 'fas fa-tools'
+    };
+    
+    const displayName = folderName === 'root' ? 'Documentation' : 
+                       folderName.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase());
+    const icon = icons[folderName] || 'fas fa-folder';
+    
+    if (!folderData.files.length && !Object.keys(folderData.folders).length) {
+      return '';
+    }
+    
+    // Include parent path in section ID to make it unique
+    const pathParts = parentPath ? [parentPath, folderName].join('-') : folderName;
+    const sectionId = `nav-${pathParts}-${level}`;
+    const isCollapsible = level > 0 || folderName !== 'root';
+    const collapseIcon = isCollapsible ? '<i class="fas fa-chevron-right collapse-icon"></i>' : '';
+    
+    // Check if this folder has a README.md file to link to
+    const readmeFile = folderData.files.find(f => f.displayName === 'README');
+    const folderLink = readmeFile ? `href="/${readmeFile.urlPath}"` : 'href="#"';
+    
+    // Get folder description for tooltip
+    const folderDescription = folderDescriptions[folderName] || '';
+    const tooltipAttr = folderDescription ? `data-tooltip="${escapeHtml(folderDescription)}"` : '';
+    
+    // Start all sections collapsed by default (JavaScript will expand sections containing active items)
+    const hasActiveChild = checkActiveChild(folderData, currentFile);
+    
+    let html = `
+      <div class="nav-section" data-level="${level}">
+        <a class="nav-title${isCollapsible ? ' collapsible' : ''}${hasActiveChild ? ' expanded' : ''}" ${folderLink} ${isCollapsible ? `data-target="${sectionId}"` : ''} ${tooltipAttr}>
+          ${collapseIcon}<i class="${icon}"></i> ${displayName}
         </a>
-      </div>`;
+        <div class="nav-content${isCollapsible ? (hasActiveChild ? '' : ' collapsed') : ''}" ${isCollapsible ? `id="${sectionId}"` : ''}>`;
+    
+    // Sort and render files
+    const sortedFiles = [...folderData.files].sort((a, b) => {
+      if (a.displayName === 'README') return -1;
+      if (b.displayName === 'README') return 1;
+      return a.displayName.localeCompare(b.displayName);
     });
     
-    html += '</div></div>';
-    return html;
-  } else {
-    // Generate collapsible navigation for folder structures
-    const generateNavHTML = (node, path = '', level = 0) => {
-      let html = '';
+    sortedFiles.forEach(file => {
+      const title = generateFileTitle(file, displayName, level);
       
-      // Add folders as sections
-      Object.entries(node.folders).forEach(([folderName, folderNode]) => {
-        const folderPath = path ? `${path}/${folderName}` : folderName;
-        const hasActiveChild = checkActiveChild(folderNode, currentFile);
-        const sectionId = `nav-${folderPath.replace(/\//g, '-')}`;
-        
-        html += `<div class="nav-section ${hasActiveChild ? 'expanded' : ''}">
-          <div class="nav-title collapsible ${hasActiveChild ? 'expanded' : ''}" data-target="${sectionId}">
-            <i class="fas fa-chevron-${hasActiveChild ? 'down' : 'right'}"></i>
-            <span class="nav-text">${folderName}</span>
-          </div>
-          <div class="nav-content ${hasActiveChild ? '' : 'collapsed'}" id="${sectionId}">
-            ${generateNavHTML(folderNode, folderPath, level + 1)}
-          </div>
-        </div>`;
-      });
+      // Check if this file is active
+      let isActive = '';
+      if (currentFile === file.urlPath) {
+        isActive = ' active';
+      } else if (currentFile === 'index.html' && file.displayName === 'README' && folderName === 'root') {
+        // Mark root README as active when viewing index.html
+        isActive = ' active';
+      }
       
-      // Add files
-      node.files.forEach(file => {
-        const isActive = file.urlPath === currentFile;
-        const href = file.urlPath.replace(/\\/g, '/');
-        html += `<div class="nav-item ${isActive ? 'active' : ''}">
-          <a href="${href}" class="nav-link ${isActive ? 'active' : ''}">
-            <span class="nav-text">${file.displayName}</span>
-          </a>
-        </div>`;
-      });
+      const linkPath = '/' + file.urlPath;
       
-      return html;
-    };
+      html += `
+        <a href="${linkPath}" class="nav-item${isActive}"><i class="fas fa-file-alt"></i> ${title}</a>`;
+    });
     
-    const checkActiveChild = (node, currentFile) => {
-      // Check files
-      if (node.files.some(f => f.urlPath === currentFile)) return true;
-      
-      // Check folders recursively
-      return Object.values(node.folders).some(folder => checkActiveChild(folder, currentFile));
-    };
+    html += `</div></div>`;
+    
+    // Render subfolders AFTER closing the parent section
+    Object.keys(folderData.folders)
+      .sort()
+      .forEach(subFolder => {
+        // Build the path for the subfolder including current folder
+        const currentPath = parentPath ? `${parentPath}-${folderName}` : folderName;
+        html += renderSection(subFolder, folderData.folders[subFolder], level + 1, currentPath);
+      });
+    
+    return html;
+  };
+  
+  // Check if this is a flat structure
+  const hasFolders = Object.keys(tree.folders).length > 0;
+  
+  if (!hasFolders) {
+    // Generate simple flat navigation for all files in root
+    return renderSection('root', { files: tree.files, folders: {} }, 0);
+  } else {
+    // Generate hierarchical navigation
+    let nav = '';
+    
+    // Render root files first
+    if (tree.files.length > 0) {
+      nav += renderSection('root', { files: tree.files, folders: {} }, 0);
+    }
+    
+    // Add other top-level folders in logical order
+    const folderOrder = [
+      'product-roadmap',
+      'product-requirements', 
+      'architecture',
+      'system-analysis',
+      'bubble',
+      'quickbase',
+      'activecampaign',
+      'juno-signer',
+      'juno-api-deprecated',
+      'postman',
+      'mcp',
+      'team',
+      'thought-leadership',
+      'documentation-tool'
+    ];
+    
+    folderOrder.forEach(folderName => {
+      if (tree.folders[folderName]) {
+        nav += renderSection(folderName, tree.folders[folderName], 1);
+        delete tree.folders[folderName]; // Remove so we don't render it again
+      }
+    });
+    
+    // Render any remaining folders not in the predefined order
+    Object.keys(tree.folders)
+      .sort()
+      .forEach(folderName => {
+        nav += renderSection(folderName, tree.folders[folderName], 1);
+      });
     
-    return generateNavHTML(tree);
+    return nav;
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowcode/doc-builder",
-  "version": "1.1.12",
+  "version": "1.2.0",
   "description": "Reusable documentation builder for markdown-based sites with Vercel deployment support",
   "main": "index.js",
   "bin": {