tractatus/public/js/docs-app.js
TheFlow d8e5061873 fix(mobile): implement navigation toggle for document viewer
Add mobile-specific navigation pattern to resolve catch-22 UX issue where
users couldn't see documents without scrolling but didn't know to scroll.

Changes:
- Add mobile CSS to toggle between sidebar and document viewer
- Add back button to return to document list on mobile
- Add document-active body class to manage navigation state
- Update GitHub repository links to correct URL

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-19 12:41:48 +13:00

625 lines
22 KiB
JavaScript

let documents = [];
let currentDocument = null;
let documentCards = null;
// Initialize card-based viewer
if (typeof DocumentCards !== 'undefined') {
documentCards = new DocumentCards('document-content');
}
// Document categorization - Granular categories for better organization
const CATEGORIES = {
'getting-started': {
label: '🚀 Getting Started',
icon: '🚀',
description: 'Introduction, core concepts, and quick start guides',
order: 1,
color: 'blue',
bgColor: 'bg-blue-50',
borderColor: 'border-l-4 border-blue-500',
textColor: 'text-blue-700',
collapsed: false
},
'technical-reference': {
label: '🔌 Technical Reference',
icon: '🔌',
description: 'API docs, implementation guides, code examples',
order: 2,
color: 'green',
bgColor: 'bg-green-50',
borderColor: 'border-l-4 border-green-500',
textColor: 'text-green-700',
collapsed: true
},
'research-theory': {
label: '🔬 Theory & Research',
icon: '🔬',
description: 'Research papers, theoretical foundations, academic content',
order: 3,
color: 'purple',
bgColor: 'bg-purple-50',
borderColor: 'border-l-4 border-purple-500',
textColor: 'text-purple-700',
collapsed: true
},
'advanced-topics': {
label: '🎓 Advanced Topics',
icon: '🎓',
description: 'Value pluralism, deep dives, comparative analysis',
order: 4,
color: 'teal',
bgColor: 'bg-teal-50',
borderColor: 'border-l-4 border-teal-500',
textColor: 'text-teal-700',
collapsed: true
},
'case-studies': {
label: '📊 Case Studies',
icon: '📊',
description: 'Real-world examples, failure modes, success stories',
order: 5,
color: 'amber',
bgColor: 'bg-amber-50',
borderColor: 'border-l-4 border-amber-500',
textColor: 'text-amber-700',
collapsed: true
},
'business-leadership': {
label: '💼 Business & Leadership',
icon: '💼',
description: 'Business cases, executive briefs, ROI analysis',
order: 6,
color: 'pink',
bgColor: 'bg-pink-50',
borderColor: 'border-l-4 border-pink-500',
textColor: 'text-pink-700',
collapsed: true
}
};
// Documents to hide (internal/confidential)
const HIDDEN_DOCS = [
'security-audit-report',
'koha-production-deployment',
'koha-stripe-payment',
'appendix-e-contact',
'cover-letter'
];
// Categorize a document using database category field
// New granular category system for better document organization
function categorizeDocument(doc) {
const slug = doc.slug.toLowerCase();
// Skip hidden documents
if (HIDDEN_DOCS.some(hidden => slug.includes(hidden))) {
return null;
}
// Use category from database
const category = doc.category || 'downloads-resources';
// Validate category exists in CATEGORIES constant
if (CATEGORIES[category]) {
return category;
}
// Fallback to downloads-resources for uncategorized
console.warn(`Document "${doc.title}" has invalid category "${category}", using fallback`);
return 'downloads-resources';
}
// Group documents by category
function groupDocuments(docs) {
const grouped = {};
// Initialize all categories
Object.keys(CATEGORIES).forEach(key => {
grouped[key] = [];
});
// Categorize each document (already sorted by order from API)
docs.forEach(doc => {
const category = categorizeDocument(doc);
if (category && grouped[category]) {
grouped[category].push(doc);
}
});
return grouped;
}
// Render document link with download button
function renderDocLink(doc, isHighlighted = false) {
const highlightClass = isHighlighted ? 'text-blue-700 bg-blue-50 border border-blue-200' : '';
// Determine if PDF download is available and get PDF path
// First check if document has explicit download_formats.pdf
let pdfPath = null;
let hasPDF = false;
if (doc.download_formats && doc.download_formats.pdf) {
pdfPath = doc.download_formats.pdf;
hasPDF = true;
} else if (!doc.slug.includes('api-reference-complete') &&
!doc.slug.includes('openapi-specification') &&
!doc.slug.includes('api-javascript-examples') &&
!doc.slug.includes('api-python-examples') &&
!doc.slug.includes('technical-architecture-diagram')) {
// Fallback to default /downloads/ path for documents that typically have PDFs
pdfPath = `/downloads/${doc.slug}.pdf`;
hasPDF = true;
}
// Add download button styling
const paddingClass = hasPDF ? 'pr-10' : 'pr-3';
return `
<div class="relative mb-1">
<button class="doc-link w-full text-left px-3 py-2 ${paddingClass} rounded text-sm hover:bg-blue-50 transition ${highlightClass}"
data-slug="${doc.slug}">
<div class="font-medium text-gray-900">${doc.title}</div>
</button>
${hasPDF ? `
<a href="${pdfPath}"
target="_blank"
rel="noopener noreferrer"
class="doc-download-link"
title="Download PDF (opens in new tab)">
<svg fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 10v6m0 0l-3-3m3 3l3-3m2 8H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"/>
</svg>
</a>
` : ''}
</div>
`;
}
// Load document list
async function loadDocuments() {
try {
// Fetch public documents
const response = await fetch('/api/documents');
const data = await response.json();
documents = data.documents || [];
// Fetch archived documents
const archivedResponse = await fetch('/api/documents/archived');
const archivedData = await archivedResponse.json();
const archivedDocuments = archivedData.documents || [];
const listEl = document.getElementById('document-list');
if (documents.length === 0 && archivedDocuments.length === 0) {
listEl.innerHTML = '<div class="text-sm text-gray-500">No documents available</div>';
return;
}
// Group documents by category
const grouped = groupDocuments(documents);
let html = '';
// Render categories in order
const sortedCategories = Object.entries(CATEGORIES)
.sort((a, b) => a[1].order - b[1].order);
sortedCategories.forEach(([categoryId, category]) => {
const docs = grouped[categoryId] || [];
if (docs.length === 0) return;
const isCollapsed = category.collapsed || false;
// Category header
html += `
<div class="category-section mb-4" data-category="${categoryId}">
<button class="category-toggle w-full flex items-center justify-between px-3 py-3 text-sm font-bold ${category.textColor} ${category.bgColor} ${category.borderColor} rounded-r hover:shadow-md transition-all"
data-category="${categoryId}"
data-collapsed="${isCollapsed}">
<span class="flex items-center gap-2">
<span class="category-icon">${category.icon}</span>
<span>${category.label.replace(category.icon, '').trim()}</span>
</span>
<svg class="category-arrow w-5 h-5 transition-transform" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"/>
</svg>
</button>
<div class="category-docs mt-2 pl-2" data-category="${categoryId}" data-collapsed="${isCollapsed}">
`;
// Render documents in category
docs.forEach(doc => {
// Highlight the first document in Getting Started category
const isHighlighted = categoryId === 'getting-started' && doc.order === 1;
html += renderDocLink(doc, isHighlighted);
});
html += `
</div>
</div>
`;
});
// Add Archives section if there are archived documents
if (archivedDocuments.length > 0) {
html += `
<div class="category-section mb-4 mt-8" data-category="archives">
<button class="category-toggle w-full flex items-center justify-between px-3 py-3 text-sm font-bold text-gray-600 bg-gray-50 border-l-4 border-gray-400 rounded-r hover:shadow-md transition-all"
data-category="archives"
data-collapsed="true">
<span class="flex items-center gap-2">
<span class="category-icon">📦</span>
<span>Archives</span>
<span class="text-xs font-normal text-gray-500">(${archivedDocuments.length} documents)</span>
</span>
<svg class="category-arrow w-5 h-5 transition-transform" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"/>
</svg>
</button>
<div class="category-docs mt-2 pl-2" data-category="archives" data-collapsed="true">
`;
// Render archived documents
archivedDocuments.forEach(doc => {
html += renderDocLink(doc, false);
// Add archive note if available
if (doc.archiveNote) {
html += `<div class="text-xs text-gray-500 italic pl-6 mb-2">${doc.archiveNote}</div>`;
}
});
html += `
</div>
</div>
`;
}
listEl.innerHTML = html;
// Apply collapsed state to categories (CSP-compliant - no inline styles)
listEl.querySelectorAll('.category-docs[data-collapsed="true"]').forEach(docsEl => {
docsEl.style.display = 'none';
});
listEl.querySelectorAll('.category-toggle[data-collapsed="true"] .category-arrow').forEach(arrowEl => {
arrowEl.style.transform = 'rotate(-90deg)';
});
// Add event delegation for document links
listEl.addEventListener('click', function(e) {
// Check for download link first (prevent document load when clicking download)
const downloadLink = e.target.closest('.doc-download-link');
if (downloadLink) {
e.stopPropagation();
return;
}
const button = e.target.closest('.doc-link');
if (button && button.dataset.slug) {
e.preventDefault();
loadDocument(button.dataset.slug);
return;
}
// Category toggle
const toggle = e.target.closest('.category-toggle');
if (toggle) {
const categoryId = toggle.dataset.category;
const docsEl = listEl.querySelector(`.category-docs[data-category="${categoryId}"]`);
const arrowEl = toggle.querySelector('.category-arrow');
if (docsEl.style.display === 'none') {
docsEl.style.display = 'block';
arrowEl.style.transform = 'rotate(0deg)';
} else {
docsEl.style.display = 'none';
arrowEl.style.transform = 'rotate(-90deg)';
}
}
});
// Check for URL parameter to auto-load document or category
const urlParams = new URLSearchParams(window.location.search);
const docParam = urlParams.get('doc');
const categoryParam = urlParams.get('category');
// Priority 1: Load specific document by slug if provided
if (docParam) {
const doc = documents.find(d => d.slug === docParam);
if (doc) {
// Find and expand the category containing this document
const docCategory = categorizeDocument(doc);
if (docCategory) {
const categoryDocsEl = listEl.querySelector(`.category-docs[data-category="${docCategory}"]`);
const categoryArrowEl = listEl.querySelector(`.category-toggle[data-category="${docCategory}"] .category-arrow`);
if (categoryDocsEl) {
categoryDocsEl.style.display = 'block';
if (categoryArrowEl) {
categoryArrowEl.style.transform = 'rotate(0deg)';
}
}
}
// Load the requested document
loadDocument(docParam);
} else {
console.warn(`Document with slug "${docParam}" not found`);
}
}
// Priority 2: Load category if provided but no specific document
else if (categoryParam && grouped[categoryParam] && grouped[categoryParam].length > 0) {
// Expand the specified category
const categoryDocsEl = listEl.querySelector(`.category-docs[data-category="${categoryParam}"]`);
const categoryArrowEl = listEl.querySelector(`.category-toggle[data-category="${categoryParam}"] .category-arrow`);
if (categoryDocsEl) {
categoryDocsEl.style.display = 'block';
if (categoryArrowEl) {
categoryArrowEl.style.transform = 'rotate(0deg)';
}
}
// Load first document in the category
const firstDoc = grouped[categoryParam][0];
if (firstDoc) {
loadDocument(firstDoc.slug);
}
}
// Priority 3: Default behavior
else {
// Default: Auto-load first document in "Getting Started" category (order: 1)
const gettingStartedDocs = grouped['getting-started'] || [];
if (gettingStartedDocs.length > 0) {
// Load the first document (order: 1) if available
const firstDoc = gettingStartedDocs.find(d => d.order === 1);
if (firstDoc) {
loadDocument(firstDoc.slug);
} else {
loadDocument(gettingStartedDocs[0].slug);
}
} else if (documents.length > 0) {
// Fallback to first available document in any category
const firstCategory = sortedCategories.find(([catId]) => grouped[catId] && grouped[catId].length > 0);
if (firstCategory) {
loadDocument(grouped[firstCategory[0]][0].slug);
}
}
}
} catch (error) {
console.error('Error loading documents:', error);
document.getElementById('document-list').innerHTML =
'<div class="text-sm text-red-600">Error loading documents</div>';
}
}
// Load specific document
let isLoading = false;
async function loadDocument(slug) {
// Prevent multiple simultaneous loads
if (isLoading) return;
try {
isLoading = true;
// Show loading state
const contentEl = document.getElementById('document-content');
contentEl.innerHTML = `
<div class="text-center py-12">
<svg class="animate-spin h-8 w-8 text-blue-600 mx-auto mb-4" fill="none" viewBox="0 0 24 24">
<circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
<path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
</svg>
<p class="text-gray-600">Loading document...</p>
</div>
`;
const response = await fetch(`/api/documents/${slug}`);
const data = await response.json();
if (!data.success) {
throw new Error(data.error || 'Failed to load document');
}
currentDocument = data.document;
// Update active state
document.querySelectorAll('.doc-link').forEach(el => {
if (el.dataset.slug === slug) {
el.classList.add('bg-blue-100', 'text-blue-900');
} else {
el.classList.remove('bg-blue-100', 'text-blue-900');
}
});
// Render with card-based viewer if available and document has sections
if (documentCards && currentDocument.sections && currentDocument.sections.length > 0) {
documentCards.render(currentDocument);
} else {
// Fallback to traditional view with header
const hasToC = currentDocument.toc && currentDocument.toc.length > 0;
// Check if PDF is available and get PDF path
let pdfPath = null;
let hasPDF = false;
if (currentDocument.download_formats && currentDocument.download_formats.pdf) {
pdfPath = currentDocument.download_formats.pdf;
hasPDF = true;
} else if (!currentDocument.slug.includes('api-reference-complete') &&
!currentDocument.slug.includes('openapi-specification') &&
!currentDocument.slug.includes('api-javascript-examples') &&
!currentDocument.slug.includes('api-python-examples') &&
!currentDocument.slug.includes('technical-architecture-diagram')) {
pdfPath = `/downloads/${currentDocument.slug}.pdf`;
hasPDF = true;
}
let headerHTML = `
<div class="flex items-center justify-between mb-6 pb-4 border-b border-gray-200">
<h1 class="text-3xl font-bold text-gray-900">${currentDocument.title}</h1>
<div class="flex items-center gap-2">
${hasToC ? `
<button id="toc-button"
class="p-2 text-gray-600 hover:text-blue-600 hover:bg-blue-50 rounded transition"
title="Table of Contents"
aria-label="Show table of contents">
<svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h7"/>
</svg>
</button>
` : ''}
${hasPDF ? `
<a href="${pdfPath}"
target="_blank"
rel="noopener noreferrer"
class="p-2 text-gray-600 hover:text-blue-600 hover:bg-blue-50 rounded transition"
title="Download PDF"
aria-label="Download PDF">
<svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 10v6m0 0l-3-3m3 3l3-3m2 8H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"/>
</svg>
</a>
` : ''}
</div>
</div>
`;
// Remove duplicate title H1 from content (it's already in header)
let contentHtml = currentDocument.content_html;
const firstH1Match = contentHtml.match(/<h1[^>]*>.*?<\/h1>/);
if (firstH1Match) {
contentHtml = contentHtml.replace(firstH1Match[0], '');
}
contentEl.innerHTML = headerHTML + `
<div class="prose max-w-none">
${contentHtml}
</div>
`;
}
// Add ToC button event listener (works for both card and traditional views)
setTimeout(() => {
const tocButton = document.getElementById('toc-button');
if (tocButton) {
tocButton.addEventListener('click', () => openToCModal());
}
}, 100);
// Mobile navigation: Add document-active class to show document view
document.body.classList.add('document-active');
// Scroll to top
window.scrollTo({ top: 0, behavior: 'smooth' });
} catch (error) {
console.error('Error loading document:', error);
document.getElementById('document-content').innerHTML = `
<div class="text-center py-12">
<svg class="h-12 w-12 text-red-400 mx-auto mb-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"/>
</svg>
<h3 class="text-lg font-medium text-gray-900 mb-2">Error loading document</h3>
<p class="text-sm text-gray-600">${error.message}</p>
</div>
`;
} finally {
isLoading = false;
}
}
// Open ToC modal
function openToCModal() {
if (!currentDocument || !currentDocument.toc || currentDocument.toc.length === 0) {
return;
}
const modal = document.getElementById('toc-modal');
if (!modal) return;
// Render ToC content
const tocContent = document.getElementById('toc-modal-content');
const tocHTML = currentDocument.toc
.filter(item => item.level <= 3) // Only show H1, H2, H3
.map(item => {
return `
<a href="#${item.slug}"
class="block py-2 px-3 text-gray-700 hover:bg-blue-50 hover:text-blue-700 rounded transition toc-link toc-indent-${item.level}"
data-slug="${item.slug}">
${item.title}
</a>
`;
}).join('');
tocContent.innerHTML = tocHTML;
// Show modal
modal.classList.add('show');
// Prevent body scroll and reset modal content scroll
document.body.style.overflow = 'hidden';
tocContent.scrollTop = 0;
// Add event listeners to ToC links
tocContent.querySelectorAll('.toc-link').forEach(link => {
link.addEventListener('click', (e) => {
e.preventDefault();
const targetId = link.getAttribute('href').substring(1);
const targetEl = document.getElementById(targetId);
if (targetEl) {
closeToCModal();
setTimeout(() => {
targetEl.scrollIntoView({ behavior: 'smooth', block: 'start' });
}, 200);
}
});
});
}
// Close ToC modal
function closeToCModal() {
const modal = document.getElementById('toc-modal');
if (modal) {
modal.classList.remove('show');
document.body.style.overflow = '';
}
}
// Initialize
loadDocuments();
// Add ESC key listener for closing modal
document.addEventListener('keydown', (e) => {
if (e.key === 'Escape') {
closeToCModal();
}
});
// Add close button listener for ToC modal (script loads after DOM, so elements exist)
const closeButton = document.getElementById('toc-close-button');
if (closeButton) {
closeButton.addEventListener('click', closeToCModal);
}
// Click outside modal to close
const modal = document.getElementById('toc-modal');
if (modal) {
modal.addEventListener('click', function(e) {
if (e.target === this) {
closeToCModal();
}
});
}
// Mobile navigation: Back to documents button
const backButton = document.getElementById('back-to-docs-btn');
if (backButton) {
backButton.addEventListener('click', function() {
// Remove document-active class to show sidebar
document.body.classList.remove('document-active');
// Scroll to top
window.scrollTo({ top: 0, behavior: 'smooth' });
});
}