flexdesk 0.1.0

package/src/editor/split_pane_container.js

@@ -0,0 +1,197 @@
+/**
+ * SplitPaneContainer — horizontal split with a draggable divider.
+ *
+ * Manages exactly 1 or 2 child panes. When only one pane exists, the divider
+ * is hidden and the single pane fills the container. When split, both panes
+ * share space according to a ratio (default 50/50), adjustable via drag.
+ *
+ * Usage:
+ *   const split = new SplitPaneContainer();
+ *   split.mount(parentEl);
+ *   split.setPanes(leftEl);             // single pane
+ *   split.setPanes(leftEl, rightEl);    // split view
+ *   split.setRatio(0.6);               // 60/40 split
+ *   split.unsplit();                    // collapse to single pane
+ */
+
+export class SplitPaneContainer {
+    /** @type {HTMLElement} */
+    #container = null;
+
+    /** @type {HTMLElement} */
+    #pane1 = null;
+
+    /** @type {HTMLElement} */
+    #pane2 = null;
+
+    /** @type {HTMLElement} */
+    #divider = null;
+
+    /** @type {number} 0..1, fraction of width for pane 1 */
+    #ratio = 0.5;
+
+    /** @type {boolean} */
+    #isSplit = false;
+
+    /** @type {Function|null} */
+    #onRatioChanged = null;
+
+    // Drag state
+    #dragging = false;
+    #boundOnMouseMove = null;
+    #boundOnMouseUp = null;
+
+    /**
+     * @param {{ onRatioChanged?: (ratio: number) => void }} opts
+     */
+    constructor(opts = {}) {
+        this.#onRatioChanged = opts.onRatioChanged ?? null;
+    }
+
+    get isSplit() { return this.#isSplit; }
+    get ratio()   { return this.#ratio; }
+
+    mount(container) {
+        this.#container = container;
+        this.#container.classList.add('split-pane-container');
+        this.#container.innerHTML = '';
+
+        // Divider
+        this.#divider = document.createElement('div');
+        this.#divider.className = 'split-pane-divider';
+        this.#divider.addEventListener('mousedown', (e) => this.#onDividerMouseDown(e));
+
+        this.#applyLayout();
+    }
+
+    /**
+     * Set pane elements. Pass one element for single view, two for split.
+     * @param {HTMLElement} pane1
+     * @param {HTMLElement} [pane2]
+     */
+    setPanes(pane1, pane2) {
+        this.#pane1 = pane1;
+        this.#pane2 = pane2 ?? null;
+        this.#isSplit = !!pane2;
+        this.#applyLayout();
+    }
+
+    /**
+     * Set the split ratio (fraction for left pane).
+     * @param {number} ratio — 0.2..0.8
+     */
+    setRatio(ratio) {
+        this.#ratio = Math.max(0.2, Math.min(0.8, ratio));
+        if (this.#isSplit) this.#applySizes();
+    }
+
+    /**
+     * Collapse to single pane (left). Returns the removed right pane element.
+     * @returns {HTMLElement|null}
+     */
+    unsplit() {
+        if (!this.#isSplit) return null;
+        const removed = this.#pane2;
+        this.#pane2 = null;
+        this.#isSplit = false;
+        this.#applyLayout();
+        return removed;
+    }
+
+    dispose() {
+        this.#stopDrag();
+        this.#container = null;
+        this.#pane1 = null;
+        this.#pane2 = null;
+        this.#divider = null;
+    }
+
+    // ─── Layout ──────────────────────────────────────────────────────────────
+
+    #applyLayout() {
+        if (!this.#container) return;
+        this.#container.innerHTML = '';
+
+        if (!this.#pane1) return;
+
+        if (!this.#isSplit) {
+            // Single pane: fills container
+            this.#pane1.className = 'split-pane';
+            this.#pane1.style.flex = '1 1 0';
+            this.#pane1.style.minWidth = '0';
+            this.#container.appendChild(this.#pane1);
+            this.#container.classList.remove('split-pane-container--split');
+        } else {
+            // Split view
+            this.#pane1.className = 'split-pane';
+            this.#pane2.className = 'split-pane';
+            this.#pane1.style.minWidth = '0';
+            this.#pane2.style.minWidth = '0';
+
+            this.#container.appendChild(this.#pane1);
+            this.#container.appendChild(this.#divider);
+            this.#container.appendChild(this.#pane2);
+            this.#container.classList.add('split-pane-container--split');
+
+            this.#applySizes();
+        }
+    }
+
+    #applySizes() {
+        if (!this.#pane1 || !this.#pane2) return;
+        // Use flex-grow proportional to ratio
+        const r = this.#ratio;
+        this.#pane1.style.flex = `${r} 1 0`;
+        this.#pane2.style.flex = `${1 - r} 1 0`;
+    }
+
+    // ─── Divider drag ────────────────────────────────────────────────────────
+
+    #onDividerMouseDown(e) {
+        if (e.button !== 0) return;
+        e.preventDefault();
+        this.#dragging = true;
+        this.#divider.classList.add('split-pane-divider--active');
+        document.body.style.cursor = 'col-resize';
+
+        // Prevent text selection and iframes capturing mouse
+        document.body.style.userSelect = 'none';
+        this.#container.querySelectorAll('iframe').forEach(f => f.style.pointerEvents = 'none');
+
+        this.#boundOnMouseMove = (e) => this.#onMouseMove(e);
+        this.#boundOnMouseUp = () => this.#onMouseUp();
+        document.addEventListener('mousemove', this.#boundOnMouseMove);
+        document.addEventListener('mouseup', this.#boundOnMouseUp);
+    }
+
+    #onMouseMove(e) {
+        if (!this.#dragging || !this.#container) return;
+        const rect = this.#container.getBoundingClientRect();
+        const dividerWidth = this.#divider.offsetWidth;
+        const usable = rect.width - dividerWidth;
+        if (usable <= 0) return;
+
+        const x = e.clientX - rect.left - dividerWidth / 2;
+        const ratio = Math.max(0.2, Math.min(0.8, x / usable));
+        this.#ratio = ratio;
+        this.#applySizes();
+    }
+
+    #onMouseUp() {
+        this.#stopDrag();
+        this.#onRatioChanged?.(this.#ratio);
+    }
+
+    #stopDrag() {
+        if (!this.#dragging) return;
+        this.#dragging = false;
+        this.#divider?.classList.remove('split-pane-divider--active');
+        document.body.style.cursor = '';
+        document.body.style.userSelect = '';
+        this.#container?.querySelectorAll('iframe').forEach(f => f.style.pointerEvents = '');
+        document.removeEventListener('mousemove', this.#boundOnMouseMove);
+        document.removeEventListener('mouseup', this.#boundOnMouseUp);
+        this.#boundOnMouseMove = null;
+        this.#boundOnMouseUp = null;
+    }
+}

package/src/help/help_modal.js

@@ -0,0 +1,409 @@
+/**
+ * HelpModal - Modal dialog for displaying help content
+ *
+ * Features:
+ * - Markdown rendering with syntax highlighting
+ * - Table of contents navigation
+ * - Topic search
+ * - Category browsing
+ * - Keyboard navigation (Escape to close)
+ */
+
+import { helpProvider, helpCategories, helpCopy } from './help_registry.js';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HelpModal Class
+// ═══════════════════════════════════════════════════════════════════════════
+
+let _activeModal = null;
+
+export class HelpModal {
+    /** The application's help, resolved at use time. */
+    get _service() { return helpProvider(); }
+
+    get _categories() { return helpCategories(); }
+
+    get _copy() { return helpCopy(); }
+
+    constructor() {
+        // Read LAZILY, not here. A HelpModal can be constructed at boot (the
+        // command palette holds one) before the application has registered its
+        // help, and a constructor read would freeze the empty default forever.
+        this._overlay = null;
+        this._modal = null;
+        this._currentTopic = null;
+        this._searchQuery = '';
+        this._boundKeyHandler = this._handleKeyDown.bind(this);
+    }
+
+    /**
+     * Open the help modal.
+     * @param {string} [topicId] - Initial topic to display
+     */
+    async open(topicId = null) {
+        // Close any existing modal
+        if (_activeModal && _activeModal !== this) {
+            _activeModal.close();
+        }
+        _activeModal = this;
+
+        this._createModal();
+        document.body.appendChild(this._overlay);
+
+        // Add keyboard handler
+        document.addEventListener('keydown', this._boundKeyHandler);
+
+        // Focus search input
+        const searchInput = this._modal.querySelector('.help-search-input');
+        if (searchInput) {
+            setTimeout(() => searchInput.focus(), 100);
+        }
+
+        // Load initial topic or show index
+        if (topicId) {
+            await this._loadTopic(topicId);
+        } else {
+            this._showIndex();
+        }
+    }
+
+    /**
+     * Close the help modal.
+     */
+    close() {
+        if (this._overlay) {
+            document.removeEventListener('keydown', this._boundKeyHandler);
+            this._overlay.remove();
+            this._overlay = null;
+            this._modal = null;
+        }
+        if (_activeModal === this) {
+            _activeModal = null;
+        }
+    }
+
+    /**
+     * Create the modal DOM structure.
+     * @private
+     */
+    _createModal() {
+        // Overlay
+        this._overlay = document.createElement('div');
+        this._overlay.className = 'help-modal-overlay';
+        this._overlay.addEventListener('click', (e) => {
+            if (e.target === this._overlay) this.close();
+        });
+
+        // Modal container
+        this._modal = document.createElement('div');
+        this._modal.className = 'help-modal';
+        this._modal.innerHTML = `
+            <div class="help-modal__header">
+                <div class="help-modal__title">
+                    <span class="material-symbols-outlined">help</span>
+                    <span>Help</span>
+                </div>
+                <button class="help-modal__close" title="Close (Esc)">
+                    <span class="material-symbols-outlined">close</span>
+                </button>
+            </div>
+            <div class="help-modal__search">
+                <span class="material-symbols-outlined">search</span>
+                <input type="text" class="help-search-input" placeholder="Search help topics..." autocomplete="off">
+            </div>
+            <div class="help-modal__body">
+                <nav class="help-modal__sidebar">
+                    <div class="help-sidebar__categories"></div>
+                </nav>
+                <main class="help-modal__content">
+                    <div class="help-content__loading">Loading...</div>
+                </main>
+            </div>
+        `;
+
+        // Event handlers
+        const closeBtn = this._modal.querySelector('.help-modal__close');
+        closeBtn.addEventListener('click', () => this.close());
+
+        const searchInput = this._modal.querySelector('.help-search-input');
+        searchInput.addEventListener('input', (e) => this._handleSearch(e.target.value));
+        searchInput.addEventListener('keydown', (e) => {
+            if (e.key === 'Escape') {
+                if (e.target.value) {
+                    e.target.value = '';
+                    this._handleSearch('');
+                    e.stopPropagation();
+                }
+            }
+        });
+
+        // Build sidebar
+        this._buildSidebar();
+
+        this._overlay.appendChild(this._modal);
+    }
+
+    /**
+     * Build the sidebar navigation.
+     * @private
+     */
+    _buildSidebar() {
+        const container = this._modal.querySelector('.help-sidebar__categories');
+        const categories = this._service.getCategories();
+
+        // Sort categories by order
+        const categoryOrder = Object.keys(this._categories);
+        categories.sort((a, b) => {
+            const orderA = categoryOrder.indexOf(a);
+            const orderB = categoryOrder.indexOf(b);
+            return (orderA === -1 ? 99 : orderA) - (orderB === -1 ? 99 : orderB);
+        });
+
+        container.innerHTML = categories.map(category => {
+            const topics = this._service.getTopicsByCategory(category);
+            const label = this._categories[category]?.label || category;
+            const icon = this._categories[category]?.icon || 'folder';
+
+            return `
+                <div class="help-category" data-category="${category}">
+                    <div class="help-category__header">
+                        <span class="material-symbols-outlined">${icon}</span>
+                        <span>${label}</span>
+                    </div>
+                    <ul class="help-category__topics">
+                        ${topics.map(topic => `
+                            <li class="help-topic-item" data-topic="${topic.id}">
+                                ${topic.title}
+                            </li>
+                        `).join('')}
+                    </ul>
+                </div>
+            `;
+        }).join('');
+
+        // Add click handlers
+        container.querySelectorAll('.help-topic-item').forEach(item => {
+            item.addEventListener('click', () => {
+                this._loadTopic(item.dataset.topic);
+            });
+        });
+
+        container.querySelectorAll('.help-category__header').forEach(header => {
+            header.addEventListener('click', () => {
+                header.parentElement.classList.toggle('collapsed');
+            });
+        });
+    }
+
+    /**
+     * Show the help index page.
+     * @private
+     */
+    _showIndex() {
+        const content = this._modal.querySelector('.help-modal__content');
+        const categories = this._service.getCategories();
+
+        const categoryOrder = Object.keys(this._categories);
+        categories.sort((a, b) => {
+            const orderA = categoryOrder.indexOf(a);
+            const orderB = categoryOrder.indexOf(b);
+            return (orderA === -1 ? 99 : orderA) - (orderB === -1 ? 99 : orderB);
+        });
+
+        content.innerHTML = `
+            <div class="help-index">
+                <h1>${this._copy.title}</h1>
+                <p>${this._copy.welcome}</p>
+
+                <div class="help-index__grid">
+                    ${categories.map(category => {
+                        const topics = this._service.getTopicsByCategory(category);
+                        const label = this._categories[category]?.label || category;
+                        const icon = this._categories[category]?.icon || 'folder';
+
+                        return `
+                            <div class="help-index__category" data-category="${category}">
+                                <div class="help-index__category-header">
+                                    <span class="material-symbols-outlined">${icon}</span>
+                                    <span>${label}</span>
+                                </div>
+                                <ul class="help-index__topics">
+                                    ${topics.slice(0, 3).map(topic => `
+                                        <li class="help-index__topic" data-topic="${topic.id}">
+                                            ${topic.title}
+                                        </li>
+                                    `).join('')}
+                                    ${topics.length > 3 ? `<li class="help-index__more">+${topics.length - 3} more</li>` : ''}
+                                </ul>
+                            </div>
+                        `;
+                    }).join('')}
+                </div>
+            </div>
+        `;
+
+        // Add click handlers
+        content.querySelectorAll('.help-index__topic').forEach(item => {
+            item.addEventListener('click', () => {
+                this._loadTopic(item.dataset.topic);
+            });
+        });
+    }
+
+    /**
+     * Load and display a topic.
+     * @param {string} topicId - Topic ID
+     * @private
+     */
+    async _loadTopic(topicId) {
+        const content = this._modal.querySelector('.help-modal__content');
+        content.innerHTML = '<div class="help-content__loading">Loading...</div>';
+
+        // Update sidebar selection
+        this._modal.querySelectorAll('.help-topic-item').forEach(item => {
+            item.classList.toggle('active', item.dataset.topic === topicId);
+        });
+
+        try {
+            const topic = await this._service.loadTopic(topicId);
+            this._currentTopic = topicId;
+
+            content.innerHTML = `
+                <div class="help-content__article">
+                    <div class="help-content__breadcrumb">
+                        <a href="#" class="help-breadcrumb__home" title="Help Index">
+                            <span class="material-symbols-outlined">home</span>
+                        </a>
+                        <span class="help-breadcrumb__separator">/</span>
+                        <span class="help-breadcrumb__title">${topic.title}</span>
+                    </div>
+                    <article class="help-article">
+                        ${topic.html}
+                    </article>
+                </div>
+            `;
+
+            // Add breadcrumb handler
+            content.querySelector('.help-breadcrumb__home').addEventListener('click', (e) => {
+                e.preventDefault();
+                this._showIndex();
+            });
+        } catch (error) {
+            content.innerHTML = `
+                <div class="help-content__error">
+                    <span class="material-symbols-outlined">error</span>
+                    <p>Failed to load help topic.</p>
+                </div>
+            `;
+        }
+    }
+
+    /**
+     * Handle search input.
+     * @param {string} query - Search query
+     * @private
+     */
+    _handleSearch(query) {
+        this._searchQuery = query;
+        const content = this._modal.querySelector('.help-modal__content');
+
+        if (!query.trim()) {
+            this._showIndex();
+            return;
+        }
+
+        const results = this._service.searchTopics(query);
+
+        if (results.length === 0) {
+            content.innerHTML = `
+                <div class="help-search-results">
+                    <h2>Search Results</h2>
+                    <p class="help-search-empty">No results found for "${query}"</p>
+                </div>
+            `;
+            return;
+        }
+
+        content.innerHTML = `
+            <div class="help-search-results">
+                <h2>Search Results</h2>
+                <p class="help-search-count">${results.length} result${results.length !== 1 ? 's' : ''} for "${query}"</p>
+                <ul class="help-search-list">
+                    ${results.map(topic => `
+                        <li class="help-search-item" data-topic="${topic.id}">
+                            <span class="help-search-item__title">${topic.title}</span>
+                            <span class="help-search-item__category">${this._categories[topic.category]?.label || topic.category}</span>
+                        </li>
+                    `).join('')}
+                </ul>
+            </div>
+        `;
+
+        // Add click handlers
+        content.querySelectorAll('.help-search-item').forEach(item => {
+            item.addEventListener('click', () => {
+                this._loadTopic(item.dataset.topic);
+            });
+        });
+    }
+
+    /**
+     * Handle keyboard events.
+     * @param {KeyboardEvent} event
+     * @private
+     */
+    _handleKeyDown(event) {
+        if (event.key === 'Escape') {
+            this.close();
+        }
+    }
+
+    /**
+     * Static method to open help modal.
+     * @param {string} [topicId] - Initial topic
+     * @returns {HelpModal}
+     */
+    static open(topicId = null) {
+        const modal = new HelpModal();
+        modal.open(topicId);
+        return modal;
+    }
+
+    /**
+     * Get the currently active modal.
+     * @returns {HelpModal|null}
+     */
+    static getActive() {
+        return _activeModal;
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Global Help Shortcut
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Open help modal with the `?` key. (F1 is reserved for top-nav Home.)
+ */
+function setupGlobalHelpShortcut() {
+    document.addEventListener('keydown', (event) => {
+        if (event.key !== '?') return;
+        // Don't hijack `?` typed into a field (search boxes, editors).
+        const t = event.target;
+        if (t?.closest?.(
+            'input, textarea, select, [contenteditable="true"]')) return;
+        event.preventDefault();
+        if (_activeModal) {
+            _activeModal.close();
+        } else {
+            HelpModal.open();
+        }
+    });
+}
+
+// Initialize global shortcut
+if (typeof document !== 'undefined') {
+    setupGlobalHelpShortcut();
+}
+
+export default HelpModal;

package/src/help/help_registry.js

@@ -0,0 +1,65 @@
+/**
+ * Where the help modal gets its help.
+ *
+ * HelpModal used to `import { getHelpService, HELP_TOPICS } from './help_service.js'` —
+ * and help_service.js is 249 domain words of EcoAgent prose about sectors,
+ * currencies, agents and markets. That import was the last framework -> domain
+ * edge in the core: a generic modal reaching into one application's manual.
+ *
+ * The modal now asks this registry, and the application fills it. If nobody
+ * fills it, the modal opens and says there is no help — which is the correct
+ * behaviour for a library that ships no documentation about your app.
+ *
+ * @typedef {Object} HelpProvider
+ * @property {() => string[]} getCategories
+ * @property {(category: string) => Array<{id: string, title: string}>} getTopicsByCategory
+ * @property {(id: string) => Promise<Object|null>} loadTopic
+ * @property {(query: string) => Array<Object>} searchTopics
+ *
+ * @typedef {Object.<string, {label: string, icon: string}>} HelpCategories
+ *   Keyed by category id; ITERATION ORDER IS DISPLAY ORDER.
+ *
+ * @typedef {{title: string, welcome: string}} HelpCopy
+ *   The landing heading. The modal used to hardcode "EcoAgent Help" and
+ *   "Welcome to EcoAgent!".
+ */
+
+/** A provider with nothing in it. Not an error — just an app with no help. */
+const EMPTY_PROVIDER = Object.freeze({
+    getCategories: () => [],
+    getTopicsByCategory: () => [],
+    loadTopic: async () => null,
+    searchTopics: () => [],
+});
+
+const DEFAULT_COPY = Object.freeze({
+    title: 'Help',
+    welcome: 'Select a topic from the sidebar or browse the categories below.',
+});
+
+let _provider = EMPTY_PROVIDER;
+let _categories = Object.freeze({});
+let _copy = DEFAULT_COPY;
+
+/**
+ * @param {HelpProvider} provider
+ * @param {HelpCategories} [categories] Display labels + icons, in display order.
+ * @param {Partial<HelpCopy>} [copy] Landing heading and welcome line.
+ */
+export function setHelpProvider(provider, categories = {}, copy = {}) {
+    _provider = provider ?? EMPTY_PROVIDER;
+    _categories = Object.freeze({ ...categories });
+    _copy = Object.freeze({ ...DEFAULT_COPY, ...copy });
+}
+
+export function helpProvider() {
+    return _provider;
+}
+
+export function helpCategories() {
+    return _categories;
+}
+
+export function helpCopy() {
+    return _copy;
+}