tegwick
b963940144
Some checks failed
Test Suite / security-scan (push) Has been cancelled
Test Suite / test-summary (push) Has been cancelled
Test Suite / unit-tests (3.11) (push) Has been cancelled
Test Suite / unit-tests (3.12) (push) Has been cancelled
Test Suite / integration-tests (push) Has been cancelled
Test Suite / e2e-tests (push) Has been cancelled
Test Suite / performance-tests (push) Has been cancelled
Test Suite / code-quality (push) Has been cancelled
- Add comprehensive widget plugin infrastructure documentation and workplan - Include complete DocumentNavigator integration documentation - Add TDD test suite with 15 comprehensive test cases for DocumentNavigator - Include widget base classes (Widget, UIWidget) for future development - Add DocumentNavigator plugin definition following planned architecture - Include test runner and demo pages for development validation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
342 lines
15 KiB
HTML
342 lines
15 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>DocumentNavigator Live Demo</title>
|
||
<style>
|
||
body {
|
||
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
|
||
line-height: 1.6;
|
||
max-width: 800px;
|
||
margin: 0 auto;
|
||
padding: 2rem;
|
||
color: #333;
|
||
}
|
||
|
||
.demo-header {
|
||
text-align: center;
|
||
background: #f8f9fa;
|
||
padding: 2rem;
|
||
border-radius: 8px;
|
||
margin-bottom: 2rem;
|
||
}
|
||
|
||
.demo-content {
|
||
margin-top: 3rem;
|
||
}
|
||
|
||
h1, h2, h3 {
|
||
scroll-margin-top: 100px; /* Account for navigator */
|
||
}
|
||
|
||
h1 {
|
||
color: #2c3e50;
|
||
border-bottom: 3px solid #3498db;
|
||
padding-bottom: 0.5rem;
|
||
}
|
||
|
||
h2 {
|
||
color: #34495e;
|
||
margin-top: 3rem;
|
||
}
|
||
|
||
h3 {
|
||
color: #7f8c8d;
|
||
margin-top: 2rem;
|
||
}
|
||
|
||
.content-section {
|
||
margin-bottom: 3rem;
|
||
}
|
||
|
||
.highlight {
|
||
background: #fff3cd;
|
||
padding: 1rem;
|
||
border-radius: 4px;
|
||
border-left: 4px solid #ffc107;
|
||
margin: 1rem 0;
|
||
}
|
||
|
||
code {
|
||
background: #f8f9fa;
|
||
padding: 0.2rem 0.4rem;
|
||
border-radius: 3px;
|
||
font-family: 'Monaco', 'Consolas', monospace;
|
||
}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<div class="demo-header">
|
||
<h1>📋 DocumentNavigator Live Demo</h1>
|
||
<p>This page demonstrates the Substack-style floating navigation widget in action.</p>
|
||
<p><strong>Look for the hamburger menu (☰) on the left side!</strong></p>
|
||
|
||
<div class="highlight">
|
||
<strong>Features to test:</strong><br>
|
||
• Click the hamburger menu to expand navigation<br>
|
||
• Click any heading in the navigator to jump to it<br>
|
||
• Scroll and watch the current section highlight<br>
|
||
• Try keyboard shortcuts (Enter/Space to toggle, Escape to close)<br>
|
||
• Resize window to test responsive behavior
|
||
</div>
|
||
</div>
|
||
|
||
<div id="markdown-content" class="demo-content">
|
||
<h1 id="introduction">1. Introduction to MarkiTect</h1>
|
||
<div class="content-section">
|
||
<p>MarkiTect is an advanced markdown processing engine that provides sophisticated document management capabilities. This demo showcases the DocumentNavigator widget, which provides Substack-style navigation for long-form documents.</p>
|
||
|
||
<p>The navigator automatically extracts headings from your content and builds a hierarchical table of contents that floats elegantly on the side of your document.</p>
|
||
</div>
|
||
|
||
<h2 id="features">1.1 Core Features</h2>
|
||
<div class="content-section">
|
||
<p>The DocumentNavigator widget includes numerous advanced features designed for optimal user experience:</p>
|
||
|
||
<ul>
|
||
<li><strong>Automatic Heading Detection</strong>: Scans document for H1, H2, H3 elements</li>
|
||
<li><strong>Hierarchical Structure</strong>: Maintains proper heading hierarchy with indentation</li>
|
||
<li><strong>Scroll Spy</strong>: Highlights current section as you scroll</li>
|
||
<li><strong>Smooth Navigation</strong>: Animated scrolling to clicked sections</li>
|
||
<li><strong>Responsive Design</strong>: Auto-hides on mobile devices</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<h3 id="responsive">1.1.1 Responsive Behavior</h3>
|
||
<div class="content-section">
|
||
<p>The navigator intelligently adapts to different screen sizes. On desktop computers, it remains visible as a floating panel. On mobile devices, it automatically hides to preserve screen real estate for content.</p>
|
||
|
||
<p>Try resizing your browser window to see this behavior in action. The navigator will disappear when the viewport becomes narrow (under 768px wide).</p>
|
||
</div>
|
||
|
||
<h3 id="accessibility">1.1.2 Accessibility Features</h3>
|
||
<div class="content-section">
|
||
<p>The DocumentNavigator is built with accessibility in mind:</p>
|
||
|
||
<ul>
|
||
<li>Full keyboard navigation support</li>
|
||
<li>ARIA labels and proper semantic markup</li>
|
||
<li>Screen reader compatibility</li>
|
||
<li>High contrast hover states</li>
|
||
<li>Focus management</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<h2 id="implementation">1.2 Implementation Details</h2>
|
||
<div class="content-section">
|
||
<p>The DocumentNavigator is implemented as a modular ES6 class that extends our base UIWidget class. This follows the planned plugin architecture for MarkiTect widgets.</p>
|
||
|
||
<p>Key implementation highlights include:</p>
|
||
|
||
<ul>
|
||
<li><code>extractHeadings()</code> - Scans DOM for heading elements</li>
|
||
<li><code>buildNavigationTree()</code> - Creates hierarchical structure</li>
|
||
<li><code>handleScroll()</code> - Manages scroll spy functionality</li>
|
||
<li><code>navigateToHeading()</code> - Handles smooth scrolling</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<h1 id="architecture">2. Widget Architecture</h1>
|
||
<div class="content-section">
|
||
<p>The DocumentNavigator follows a clean architectural pattern that separates concerns and provides maximum flexibility for customization and extension.</p>
|
||
|
||
<p>The widget is designed as part of a larger plugin ecosystem that will allow developers to create custom UI components that can be loaded dynamically and configured independently.</p>
|
||
</div>
|
||
|
||
<h2 id="base-classes">2.1 Base Class Hierarchy</h2>
|
||
<div class="content-section">
|
||
<p>Our widget system is built on a foundation of base classes that provide common functionality:</p>
|
||
|
||
<ul>
|
||
<li><strong>Widget</strong>: Core functionality (events, state, lifecycle)</li>
|
||
<li><strong>UIWidget</strong>: DOM manipulation and visual behavior</li>
|
||
<li><strong>InteractiveWidget</strong>: Event handling and user interaction</li>
|
||
</ul>
|
||
|
||
<p>DocumentNavigator extends UIWidget directly since it doesn't require complex interaction handling beyond basic click and keyboard events.</p>
|
||
</div>
|
||
|
||
<h3 id="events">2.1.1 Event System</h3>
|
||
<div class="content-section">
|
||
<p>The widget uses a custom event system built on the native EventTarget API. This allows for clean separation of concerns and easy integration with other components.</p>
|
||
|
||
<p>Key events emitted by DocumentNavigator:</p>
|
||
|
||
<ul>
|
||
<li><code>rendered</code> - Widget has been rendered to DOM</li>
|
||
<li><code>navigate</code> - User navigated to a heading</li>
|
||
<li><code>toggle</code> - Widget was expanded or collapsed</li>
|
||
<li><code>theme-changed</code> - Theme was changed</li>
|
||
<li><code>destroyed</code> - Widget was destroyed</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<h3 id="state">2.1.2 State Management</h3>
|
||
<div class="content-section">
|
||
<p>State management is handled through a simple Map-based system that provides reactive updates and event emission when state changes occur.</p>
|
||
|
||
<p>This approach is lightweight but powerful enough for most widget use cases while remaining debuggable and predictable.</p>
|
||
</div>
|
||
|
||
<h2 id="plugin-system">2.2 Plugin System Integration</h2>
|
||
<div class="content-section">
|
||
<p>While the current implementation works standalone, it's designed to integrate seamlessly with our planned plugin system. The plugin definition includes:</p>
|
||
|
||
<ul>
|
||
<li>Metadata and versioning information</li>
|
||
<li>Dependency declarations</li>
|
||
<li>Default configuration options</li>
|
||
<li>Lifecycle hooks</li>
|
||
<li>Theme variants</li>
|
||
<li>Development helpers</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<h1 id="usage">3. Usage Examples</h1>
|
||
<div class="content-section">
|
||
<p>The DocumentNavigator can be used in several ways, from simple instantiation to advanced configuration with custom themes and behavior.</p>
|
||
</div>
|
||
|
||
<h2 id="basic-usage">3.1 Basic Usage</h2>
|
||
<div class="content-section">
|
||
<p>The simplest way to use DocumentNavigator is with default settings:</p>
|
||
|
||
<pre><code>const navigator = new DocumentNavigator();
|
||
await navigator.initialize();
|
||
await navigator.render();</code></pre>
|
||
|
||
<p>This creates a navigator with default settings that will scan the entire document for headings and display them in a collapsible panel on the left side.</p>
|
||
</div>
|
||
|
||
<h2 id="advanced-usage">3.2 Advanced Configuration</h2>
|
||
<div class="content-section">
|
||
<p>For more control, you can specify detailed configuration options:</p>
|
||
|
||
<pre><code>const navigator = new DocumentNavigator({
|
||
position: 'right',
|
||
collapsed: false,
|
||
theme: 'dark',
|
||
maxHeadingLevel: 4,
|
||
enableScrollSpy: true,
|
||
smoothScroll: true
|
||
});</code></pre>
|
||
|
||
<p>This creates a navigator on the right side that starts expanded, includes H4 headings, and uses the dark theme.</p>
|
||
</div>
|
||
|
||
<h3 id="theming">3.2.1 Custom Theming</h3>
|
||
<div class="content-section">
|
||
<p>The navigator supports multiple built-in themes and can be extended with custom themes. The theming system integrates with MarkiTect's document themes for consistent styling.</p>
|
||
|
||
<p>Available themes include <code>default</code>, <code>dark</code>, and <code>minimal</code>, each optimized for different use cases and aesthetics.</p>
|
||
</div>
|
||
|
||
<h1 id="testing">4. Testing and Quality</h1>
|
||
<div class="content-section">
|
||
<p>The DocumentNavigator implementation follows Test-Driven Development (TDD) methodology with comprehensive test coverage ensuring reliability and maintainability.</p>
|
||
</div>
|
||
|
||
<h2 id="test-coverage">4.1 Test Coverage</h2>
|
||
<div class="content-section">
|
||
<p>Our test suite covers all major functionality:</p>
|
||
|
||
<ul>
|
||
<li>Widget instantiation and configuration</li>
|
||
<li>DOM rendering and element creation</li>
|
||
<li>Heading extraction and hierarchy building</li>
|
||
<li>Navigation and smooth scrolling</li>
|
||
<li>Expand/collapse animations</li>
|
||
<li>Scroll spy functionality</li>
|
||
<li>Responsive behavior</li>
|
||
<li>Keyboard navigation</li>
|
||
<li>Event emission</li>
|
||
<li>Edge cases and error handling</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<h2 id="performance">4.2 Performance Considerations</h2>
|
||
<div class="content-section">
|
||
<p>The navigator is optimized for performance with several key strategies:</p>
|
||
|
||
<ul>
|
||
<li><strong>Throttled Scroll Events</strong>: Scroll spy updates are throttled to 100ms intervals</li>
|
||
<li><strong>Efficient DOM Queries</strong>: Heading extraction is done once and cached</li>
|
||
<li><strong>Conditional Rendering</strong>: Navigator only renders if minimum heading count is met</li>
|
||
<li><strong>Memory Management</strong>: Proper cleanup prevents memory leaks</li>
|
||
<li><strong>Responsive Loading</strong>: Navigator automatically hides on mobile to save resources</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<h1 id="conclusion">5. Conclusion</h1>
|
||
<div class="content-section">
|
||
<p>The DocumentNavigator widget successfully brings Substack-style navigation to MarkiTect documents. It provides an intuitive, accessible, and performant way for users to navigate long-form content.</p>
|
||
|
||
<p>The implementation demonstrates the power of our widget architecture approach, with clean separation of concerns, comprehensive testing, and excellent extensibility for future enhancements.</p>
|
||
|
||
<p><strong>Scroll back to the top and try the navigation features!</strong> The hamburger menu should be visible on the left side of your screen.</p>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- Load widget classes -->
|
||
<script type="module">
|
||
// Import our widget classes
|
||
import { Widget } from '../widgets/base/Widget.js';
|
||
import { UIWidget } from '../widgets/base/UIWidget.js';
|
||
import { DocumentNavigator } from '../widgets/navigation/DocumentNavigator.js';
|
||
|
||
// Make classes available globally for demo
|
||
window.Widget = Widget;
|
||
window.UIWidget = UIWidget;
|
||
window.DocumentNavigator = DocumentNavigator;
|
||
|
||
// Initialize navigator on page load
|
||
document.addEventListener('DOMContentLoaded', async () => {
|
||
console.log('🧭 Initializing DocumentNavigator demo...');
|
||
|
||
try {
|
||
// Create navigator with demo settings
|
||
const navigator = new DocumentNavigator({
|
||
container: document.getElementById('markdown-content'),
|
||
position: 'left',
|
||
collapsed: true,
|
||
theme: 'default',
|
||
enableScrollSpy: true,
|
||
autoHide: true,
|
||
maxHeadingLevel: 3,
|
||
minHeadings: 1 // Show navigator even with few headings for demo
|
||
});
|
||
|
||
// Initialize and render
|
||
await navigator.initialize();
|
||
const element = await navigator.render();
|
||
|
||
if (element) {
|
||
console.log('✅ DocumentNavigator initialized successfully!');
|
||
console.log(` Found ${navigator.headings.length} headings`);
|
||
console.log(' Click the hamburger menu (☰) to expand navigation');
|
||
} else {
|
||
console.log('ℹ️ DocumentNavigator not rendered (insufficient headings)');
|
||
}
|
||
|
||
// Add some debugging helpers
|
||
window.navigator = navigator;
|
||
window.testNavigator = {
|
||
expand: () => navigator.expand(),
|
||
collapse: () => navigator.collapse(),
|
||
toggle: () => navigator.toggle(),
|
||
showHeadings: () => console.table(navigator.headings),
|
||
showTree: () => console.log(navigator.navigationTree)
|
||
};
|
||
|
||
console.log('🔧 Debugging helpers available:');
|
||
console.log(' window.navigator - navigator instance');
|
||
console.log(' window.testNavigator - helper functions');
|
||
|
||
} catch (error) {
|
||
console.error('❌ DocumentNavigator initialization failed:', error);
|
||
}
|
||
});
|
||
</script>
|
||
</body>
|
||
</html> |