markitect-main/markitect/static/js/plugins/document-navigator-plugin.js

/**
 * DocumentNavigator Plugin Definition
 *
 * Plugin definition for the Substack-style document navigation widget.
 * Provides floating table of contents with smooth scrolling and scroll spy.
 */
export default {
    name: 'DocumentNavigator',
    version: '1.0.0',
    description: 'Substack-style floating document navigation with table of contents',
    author: 'Markitect Core',
    category: 'navigation',

    // Dependencies that must be loaded first
    dependencies: ['UIWidget'],

    // Mixins to apply (none required for this widget)
    mixins: [],

    // Lazy load the actual widget class
    async load() {
        const { DocumentNavigator } = await import('../widgets/navigation/DocumentNavigator.js');
        return DocumentNavigator;
    },

    // Default configuration
    defaultOptions: {
        position: 'left',               // 'left' or 'right' side
        collapsed: true,                // Start in collapsed state
        autoHide: true,                 // Hide on mobile devices
        maxHeadingLevel: 3,            // Include H1, H2, H3
        enableScrollSpy: true,          // Highlight current section
        smoothScroll: true,             // Smooth scroll to headings
        animationDuration: 300,         // Animation timing in ms
        minHeadings: 2,                // Minimum headings to show widget
        theme: 'default',              // Theme variant

        // Layout options
        width: '280px',                // Expanded width
        collapsedWidth: '40px',        // Collapsed width
        offset: {                      // Position offset
            top: '80px',
            side: '20px'
        },

        // Accessibility
        enableKeyboard: true,           // Keyboard navigation support
        ariaLabel: 'Document Navigation'
    },

    // Plugin lifecycle hooks
    async onLoad(instance, options) {
        console.log('DocumentNavigator plugin loaded:', {
            headings: instance.headings.length,
            position: options.position,
            collapsed: options.collapsed
        });

        // Auto-initialize after load
        await instance.initialize();

        return instance;
    },

    async onUnload(instance) {
        console.log('DocumentNavigator plugin unloading');
        await instance.destroy();
    },

    // Feature flags and capabilities
    capabilities: {
        draggable: false,              // Not draggable (fixed position)
        resizable: false,              // Not resizable (fixed width)
        themeable: true,               // Supports themes
        persistent: false,             // Rebuilds on page changes
        responsive: true,              // Responsive behavior
        keyboard: true,                // Keyboard accessible
        scrollSpy: true,              // Scroll spy functionality
        smoothScroll: true            // Smooth scroll navigation
    },

    // Integration requirements
    requirements: {
        container: true,               // Requires container element
        headings: true,               // Requires document headings
        scrollable: true              // Requires scrollable content
    },

    // Event types emitted by this widget
    events: [
        'rendered',                   // Widget rendered to DOM
        'navigate',                   // User navigated to heading
        'toggle',                     // Widget expanded/collapsed
        'theme-changed',              // Theme was changed
        'destroyed'                   // Widget was destroyed
    ],

    // CSS classes used by this widget
    cssClasses: [
        'document-navigator',         // Main widget class
        'navigator-toggle',           // Toggle button
        'navigator-list',            // Navigation list
        'navigator-item',            // Navigation items
        'navigator-link',            // Navigation links
        'navigator-header',          // List header
        'navigator-close',           // Close button
        'navigator-empty'            // Empty state
    ],

    // Theme variants
    themes: {
        default: {
            backgroundColor: 'rgba(255, 255, 255, 0.95)',
            borderColor: '#e1e5e9',
            textColor: '#333',
            activeColor: '#1976d2',
            activeBackground: '#e3f2fd'
        },
        dark: {
            backgroundColor: 'rgba(45, 45, 45, 0.95)',
            borderColor: '#555',
            textColor: '#e0e0e0',
            activeColor: '#64b5f6',
            activeBackground: '#1e3a8a'
        },
        minimal: {
            backgroundColor: 'rgba(248, 249, 250, 0.90)',
            borderColor: '#dee2e6',
            textColor: '#495057',
            activeColor: '#007bff',
            activeBackground: '#e7f1ff'
        }
    },

    // Usage examples
    examples: {
        basic: {
            description: 'Basic document navigator on the left side',
            code: `
                const navigator = await widgetSystem.createWidget('DocumentNavigator');
                await navigator.show();
            `
        },
        customized: {
            description: 'Customized navigator with specific options',
            code: `
                const navigator = await widgetSystem.createWidget('DocumentNavigator', {
                    position: 'right',
                    collapsed: false,
                    maxHeadingLevel: 4,
                    theme: 'dark'
                });
                await navigator.show();
            `
        },
        withContainer: {
            description: 'Navigator for specific container content',
            code: `
                const container = document.getElementById('article-content');
                const navigator = await widgetSystem.createWidget('DocumentNavigator', {
                    container: container,
                    minHeadings: 1
                });
                await navigator.show();
            `
        }
    },

    // Development and testing helpers
    dev: {
        testHeadingStructure() {
            // Helper to create test content with headings
            const testContent = `
                <h1>Chapter 1: Introduction</h1>
                <p>Lorem ipsum content...</p>
                <h2>Section 1.1: Overview</h2>
                <h3>Subsection 1.1.1: Details</h3>
                <h2>Section 1.2: Implementation</h2>
                <h1>Chapter 2: Advanced Topics</h1>
                <h2>Section 2.1: Performance</h2>
            `;

            const container = document.createElement('div');
            container.innerHTML = testContent;
            container.style.cssText = 'height: 2000px; padding: 2rem;';
            document.body.appendChild(container);

            return container;
        },

        async createTestInstance(options = {}) {
            // Helper to create test instance with sample content
            const container = this.testHeadingStructure();

            const navigator = new (await this.load())({
                container,
                collapsed: false,
                ...options
            });

            await navigator.initialize();
            await navigator.render();

            return { navigator, container };
        }
    }
};