flexdesk 0.1.0

package/src/core/state_machine.js

@@ -0,0 +1,258 @@
+/**
+ * State Machine Base (js_new)
+ *
+ * Purpose
+ * -------
+ * Shared finite-state-machine utility that workspace, simulation, and other controllers extend.
+ *
+ * Responsibilities
+ * - Provide declarative state/transition definitions with guard + action hooks.
+ * - Emit lifecycle events via the injected EventBus for observability.
+ * - Supply debugging helpers (transition tracing) without referencing window globals.
+ *
+ * Source Material
+ * - html/js/state_machine.js (base implementation semantics).
+ * - html/js/workspace_state_machine.js (practical usage patterns to support).
+ *
+ */
+
+const BUS_EVENTS = Object.freeze({
+    ATTEMPT: 'fsm:transition:attempt',
+    BLOCKED: 'fsm:transition:blocked',
+    COMPLETE: 'fsm:transition:complete',
+    ERROR: 'fsm:transition:error',
+});
+
+const isPromiseLike = (value) => Boolean(value) && typeof value.then === 'function';
+
+export class StateMachine {
+    constructor({
+        name = 'state-machine',
+        initialState,
+        states = {},
+        eventBus = null,
+        logger = null,
+        trace = false,
+    } = {}) {
+        if (!initialState || typeof initialState !== 'string') {
+            throw new Error('StateMachine requires a non-empty initialState name');
+        }
+        if (!states[initialState]) {
+            throw new Error(`StateMachine initial state "${initialState}" is not defined in states map`);
+        }
+
+        this.name = name;
+        this.states = this._normalizeStates(states);
+        this.initialState = initialState;
+        this.currentState = null;
+        this.previousState = null;
+        this.eventBus = eventBus;
+        this.logger = logger;
+        this.trace = trace;
+        this._isTransitioning = false;
+        this._ready = Promise.resolve().then(() => this._enterState(initialState, {
+            type: 'init',
+            payload: undefined,
+            fromState: null,
+        }));
+
+        this._ready.catch((err) => {
+            this.logger?.error?.('state-machine', 'Failed to enter initial state', {
+                machine: this.name,
+                error: err,
+            });
+        });
+    }
+
+    describeStates() {
+        return Object.keys(this.states);
+    }
+
+    getState() {
+        return this.currentState;
+    }
+
+    canTransition(eventName) {
+        const current = this.states[this.currentState];
+        return Boolean(current?.transitions?.[eventName]);
+    }
+
+    async transition(eventName, payload = undefined) {
+        await this._ready;
+
+        if (this._isTransitioning) {
+            throw new Error(`StateMachine "${this.name}" is already processing a transition`);
+        }
+        const currentDef = this.states[this.currentState];
+        const transitionDef = currentDef?.transitions?.[eventName];
+
+        if (!transitionDef) {
+            this._emitBus(BUS_EVENTS.BLOCKED, { reason: 'missing-transition', event: eventName });
+            this.logger?.warn?.('state-machine', `No transition for event "${eventName}" in state "${this.currentState}"`, {
+                machine: this.name,
+                state: this.currentState,
+                event: eventName,
+            });
+            return { transitioned: false, reason: 'missing-transition' };
+        }
+
+        const targetState = transitionDef.target;
+        if (!targetState || !this.states[targetState]) {
+            throw new Error(`Transition from "${this.currentState}" via "${eventName}" references undefined target state "${targetState}"`);
+        }
+
+        const context = {
+            machine: this,
+            event: eventName,
+            fromState: this.currentState,
+            toState: targetState,
+            payload,
+        };
+
+        const guardAllowed = await this._evaluateGuard(transitionDef.guard, context);
+        if (!guardAllowed) {
+            this._emitBus(BUS_EVENTS.BLOCKED, {
+                reason: 'guard-blocked',
+                event: eventName,
+                fromState: this.currentState,
+                toState: targetState,
+            });
+            return { transitioned: false, reason: 'guard-blocked' };
+        }
+
+        this._emitBus(BUS_EVENTS.ATTEMPT, context);
+        this._isTransitioning = true;
+
+        try {
+            await this._runHook(this.states[this.currentState]?.onExit, context, 'onExit');
+            await this._runHook(transitionDef.action, context, 'transition-action');
+            await this._enterState(targetState, { type: eventName, payload, fromState: context.fromState });
+            this._emitBus(BUS_EVENTS.COMPLETE, context);
+            return { transitioned: true };
+        } catch (err) {
+            this._emitBus(BUS_EVENTS.ERROR, { ...context, error: err });
+            this.logger?.error?.('state-machine', 'Transition failed', {
+                machine: this.name,
+                event: eventName,
+                fromState: context.fromState,
+                toState: context.toState,
+                error: err,
+            });
+            throw err;
+        } finally {
+            this._isTransitioning = false;
+        }
+    }
+
+    async reset(stateName = this.initialState) {
+        await this._ready;
+        if (!this.states[stateName]) {
+            throw new Error(`Cannot reset state machine to undefined state "${stateName}"`);
+        }
+        this.previousState = this.currentState;
+        await this._enterState(stateName, {
+            type: 'reset',
+            payload: undefined,
+            fromState: this.previousState,
+        });
+        this._emitBus(BUS_EVENTS.COMPLETE, {
+            machine: this,
+            event: 'reset',
+            fromState: this.previousState,
+            toState: stateName,
+            payload: undefined,
+        });
+    }
+
+    updateStates(partialStates = {}) {
+        this.states = this._normalizeStates({ ...this.states, ...partialStates });
+        if (!this.states[this.currentState]) {
+            throw new Error('Current state was removed during updateStates');
+        }
+    }
+
+    _normalizeStates(definitions) {
+        const normalized = {};
+        for (const [stateName, config] of Object.entries(definitions)) {
+            if (!config || typeof config !== 'object') {
+                throw new Error(`Invalid state definition for "${stateName}"`);
+            }
+            normalized[stateName] = {
+                onEnter: config.onEnter ?? null,
+                onExit: config.onExit ?? null,
+                transitions: { ...(config.transitions ?? {}) },
+            };
+        }
+        return normalized;
+    }
+
+    async _enterState(stateName, meta) {
+        const prev = this.currentState;
+        this.previousState = prev;
+        this.currentState = stateName;
+
+        const context = {
+            machine: this,
+            event: meta.type,
+            fromState: meta.fromState,
+            toState: stateName,
+            payload: meta.payload,
+        };
+
+        await this._runHook(this.states[stateName]?.onEnter, context, 'onEnter');
+        if (this.trace) {
+            this.logger?.debug?.('state-machine', `State machine "${this.name}" entered state "${stateName}"`, {
+                machine: this.name,
+                fromState: prev,
+                toState: stateName,
+            });
+        }
+    }
+
+    async _evaluateGuard(guardFn, context) {
+        if (!guardFn) {
+            return true;
+        }
+        const result = guardFn(context);
+        if (isPromiseLike(result)) {
+            return result;
+        }
+        return result !== false;
+    }
+
+    async _runHook(hook, context, hookName) {
+        if (typeof hook !== 'function') {
+            return;
+        }
+        const result = hook(context);
+        if (isPromiseLike(result)) {
+            await result;
+        }
+        if (this.trace) {
+            this.logger?.debug?.('state-machine', `${hookName} executed`, {
+                machine: this.name,
+                hook: hookName,
+                state: context.toState,
+            });
+        }
+    }
+
+    _emitBus(eventName, detail) {
+        if (!this.eventBus || !eventName) {
+            return;
+        }
+        try {
+            this.eventBus.emit(eventName, {
+                machine: this.name,
+                state: this.currentState,
+                detail,
+            });
+        } catch (err) {
+            this.logger?.warn?.('state-machine', 'Failed to emit state machine event', {
+                machine: this.name,
+                eventName,
+                error: err,
+            });
+        }
+    }
+}

package/src/editor/editor_pane.js

@@ -0,0 +1,264 @@
+/**
+ * EditorPane — one half (or whole) of the split editor.
+ *
+ * Each pane owns:
+ *   - A NotebookTabBar instance
+ *   - An editor container where the active file's editor is mounted
+ *   - A list of file paths assigned to this pane
+ *   - The active file path within this pane
+ *
+ * The pane does NOT mount editors itself — it delegates to the parent
+ * (NotebookPage) via callbacks, since editor mounting requires access to
+ * ProjectModel, symbol index, plot controller, etc.
+ *
+ * Layout:
+ *   ┌──────────────────────────────┐
+ *   │  [Tab1] [Tab2]              │  ← NotebookTabBar
+ *   ├──────────────────────────────┤
+ *   │                              │
+ *   │  Editor content              │  ← editorContainer
+ *   │                              │
+ *   └──────────────────────────────┘
+ */
+
+import { NotebookTabBar } from './notebook_tab_bar.js';
+
+export class EditorPane {
+    /** @type {string} */
+    #id;
+
+    /** @type {HTMLElement} root element */
+    #el = null;
+
+    /** @type {NotebookTabBar} */
+    #tabBar = null;
+
+    /** @type {HTMLElement} */
+    #editorContainer = null;
+
+    /** @type {string[]} file paths in tab order */
+    #filePaths = [];
+
+    /** @type {string|null} */
+    #activeFilePath = null;
+
+    /** @type {string|null} file path of the preview (transient) tab, if any */
+    #previewFilePath = null;
+
+    /** @type {object} callbacks from parent */
+    #callbacks = {};
+
+    /** @type {boolean} whether this pane is the focused/active pane */
+    #focused = false;
+
+    /**
+     * @param {string} id — unique pane identifier ('left' or 'right')
+     * @param {object} callbacks
+     * @param {Function} callbacks.onActivate — (paneId, filePath) => void
+     * @param {Function} callbacks.onClose — (paneId, filePath) => void
+     * @param {Function} callbacks.onCloseOthers — (paneId, filePath) => void
+     * @param {Function} callbacks.onCloseToRight — (paneId, filePath) => void
+     * @param {Function} callbacks.onCloseAll — (paneId) => void
+     * @param {Function} callbacks.onCloseSaved — (paneId) => void
+     * @param {Function} callbacks.onRename — (oldPath, newPath) => void
+     * @param {Function} callbacks.onDuplicate — (filePath) => void
+     * @param {Function} callbacks.onReorder — (paneId, orderedPaths) => void
+     * @param {Function} callbacks.onRevealInExplorer — (filePath) => void
+     * @param {Function} callbacks.onFocus — (paneId) => void
+     * @param {Function} callbacks.onSplitRight — (paneId, filePath) => void
+     * @param {Function} callbacks.onMoveToOtherPane — (paneId, filePath) => void
+     */
+    constructor(id, callbacks = {}) {
+        this.#id = id;
+        this.#callbacks = callbacks;
+    }
+
+    get id() { return this.#id; }
+    get activeFilePath() { return this.#activeFilePath; }
+    get filePaths() { return [...this.#filePaths]; }
+    get editorContainer() { return this.#editorContainer; }
+    get element() { return this.#el; }
+    get isEmpty() { return this.#filePaths.length === 0; }
+
+    /**
+     * Build DOM and mount the tab bar.
+     * @returns {HTMLElement} the root element (to be placed in SplitPaneContainer)
+     */
+    mount() {
+        this.#el = document.createElement('div');
+        this.#el.className = 'editor-pane';
+        this.#el.dataset.paneId = this.#id;
+
+        // Focus tracking — clicking anywhere in the pane focuses it
+        this.#el.addEventListener('mousedown', () => {
+            this.#callbacks.onFocus?.(this.#id);
+        }, true);
+
+        // Tab bar
+        const tabBarEl = document.createElement('div');
+        this.#el.appendChild(tabBarEl);
+
+        this.#tabBar = new NotebookTabBar();
+        this.#tabBar.mount(tabBarEl, {
+            onActivate:        (path) => this.#callbacks.onActivate?.(this.#id, path),
+            onClose:           (path) => this.#callbacks.onClose?.(this.#id, path),
+            onCloseOthers:     (path) => this.#callbacks.onCloseOthers?.(this.#id, path),
+            onCloseToRight:    (path) => this.#callbacks.onCloseToRight?.(this.#id, path),
+            onCloseAll:        ()     => this.#callbacks.onCloseAll?.(this.#id),
+            onCloseSaved:      ()     => this.#callbacks.onCloseSaved?.(this.#id),
+            onRename:          (o, n) => this.#callbacks.onRename?.(o, n),
+            onDuplicate:       (path) => this.#callbacks.onDuplicate?.(path),
+            onReorder:         (paths) => this.#callbacks.onReorder?.(this.#id, paths),
+            onRevealInExplorer:(path) => this.#callbacks.onRevealInExplorer?.(path),
+            onSplitRight:      (path) => this.#callbacks.onSplitRight?.(this.#id, path),
+            onMoveToOtherPane: (path) => this.#callbacks.onMoveToOtherPane?.(this.#id, path),
+            onDropFromOtherPane: (path) => this.#callbacks.onDropFromOtherPane?.(this.#id, path),
+        });
+
+        // Editor body wrapper — positioned container that fills remaining
+        // flex space.  The actual editor container is absolutely positioned
+        // inside, so its height is ALWAYS the wrapper's height, regardless
+        // of content.  This makes the scroll chain bulletproof — no flex
+        // ancestor chain needed for the scrollbar to work.
+        const body = document.createElement('div');
+        body.className = 'editor-pane__body';
+        this.#el.appendChild(body);
+
+        // Editor container (absolutely positioned inside wrapper)
+        this.#editorContainer = document.createElement('div');
+        this.#editorContainer.className = 'notebook-editor-container';
+        body.appendChild(this.#editorContainer);
+
+        // Accept cross-pane tab drops on the editor area too
+        this.#editorContainer.addEventListener('dragover', (e) => {
+            if (this.#isExternalTabDrag(e)) {
+                e.preventDefault();
+                try { e.dataTransfer.dropEffect = 'move'; } catch {}
+                this.#editorContainer.classList.add('notebook-editor-container--drop-target');
+            }
+        });
+        this.#editorContainer.addEventListener('drop', (e) => {
+            if (this.#isExternalTabDrag(e)) {
+                e.preventDefault();
+                this.#editorContainer.classList.remove('notebook-editor-container--drop-target');
+                const filePath = e.dataTransfer.getData('application/x-ecosim-tab')
+                    || e.dataTransfer.getData('text/plain');
+                if (filePath) {
+                    this.#callbacks.onDropFromOtherPane?.(this.#id, filePath);
+                }
+            }
+        });
+        this.#editorContainer.addEventListener('dragleave', (e) => {
+            if (!this.#editorContainer.contains(e.relatedTarget)) {
+                this.#editorContainer.classList.remove('notebook-editor-container--drop-target');
+            }
+        });
+
+        return this.#el;
+    }
+
+    /**
+     * Update the file list and active tab.
+     * @param {Array<{filePath: string, fileType: string, isDirty: boolean}>} tabs
+     * @param {string|null} activeFilePath
+     */
+    syncTabBar(tabs, activeFilePath) {
+        this.#tabBar?.update(tabs, activeFilePath);
+    }
+
+    /**
+     * Set the files assigned to this pane.
+     * @param {string[]} filePaths
+     */
+    setFilePaths(filePaths) {
+        this.#filePaths = [...filePaths];
+    }
+
+    /**
+     * Add a file to this pane's tabs (at end).
+     * @param {string} filePath
+     */
+    addFile(filePath) {
+        if (!this.#filePaths.includes(filePath)) {
+            this.#filePaths.push(filePath);
+        }
+    }
+
+    /**
+     * Remove a file from this pane's tabs.
+     * @param {string} filePath
+     */
+    removeFile(filePath) {
+        this.#filePaths = this.#filePaths.filter(p => p !== filePath);
+        if (this.#previewFilePath === filePath) this.#previewFilePath = null;
+        if (this.#activeFilePath === filePath) {
+            this.#activeFilePath = this.#filePaths.length > 0
+                ? this.#filePaths[this.#filePaths.length - 1]
+                : null;
+        }
+    }
+
+    hasFile(filePath) {
+        return this.#filePaths.includes(filePath);
+    }
+
+    setActiveFile(filePath) {
+        this.#activeFilePath = filePath;
+    }
+
+    setFocused(focused) {
+        this.#focused = focused;
+        this.#el?.classList.toggle('editor-pane--focused', focused);
+    }
+
+    markDirty(filePath, isDirty) {
+        this.#tabBar?.markDirty(filePath, isDirty);
+    }
+
+    reorderFiles(orderedPaths) {
+        // Keep only paths that belong to this pane
+        const valid = orderedPaths.filter(p => this.#filePaths.includes(p));
+        // Append any missing (shouldn't happen)
+        for (const p of this.#filePaths) {
+            if (!valid.includes(p)) valid.push(p);
+        }
+        this.#filePaths = valid;
+    }
+
+    renameFile(oldPath, newPath) {
+        const idx = this.#filePaths.indexOf(oldPath);
+        if (idx !== -1) this.#filePaths[idx] = newPath;
+        if (this.#activeFilePath === oldPath) this.#activeFilePath = newPath;
+        if (this.#previewFilePath === oldPath) this.#previewFilePath = newPath;
+    }
+
+    // ─── Preview (transient) tab ──────────────────────────────────────────────
+
+    /** @returns {string|null} the preview file path, or null if no preview tab */
+    get previewFilePath() { return this.#previewFilePath; }
+
+    /** Mark a file as the preview tab. Only one preview tab per pane. */
+    setPreview(filePath) { this.#previewFilePath = filePath; }
+
+    /** Whether a file is the preview (transient) tab. */
+    isPreview(filePath) { return this.#previewFilePath === filePath; }
+
+    /** Pin the preview tab (promote to permanent). */
+    pinPreview() { this.#previewFilePath = null; }
+
+    /** Check if a drag event is carrying a tab from another pane. */
+    #isExternalTabDrag(e) {
+        try { return e.dataTransfer.types.includes('application/x-ecosim-tab'); } catch { return false; }
+    }
+
+    dispose() {
+        this.#tabBar?.dispose();
+        this.#tabBar = null;
+        this.#el?.remove();
+        this.#el = null;
+        this.#editorContainer = null;
+        this.#filePaths = [];
+        this.#activeFilePath = null;
+        this.#previewFilePath = null;
+    }
+}