LiveDocument.js

/*
 * GNU AGPL-3.0 License
 *
 * Copyright (c) 2021 - present core.ai . All rights reserved.
 * Original work Copyright (c) 2014 - 2021 Adobe Systems Incorporated. All rights reserved.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program. If not, see https://opensource.org/licenses/AGPL-3.0.
 *
 */

define(function (require, exports, module) {


    const CONSTANTS           = require("LiveDevelopment/LivePreviewConstants"),
        EditorManager       = require("editor/EditorManager"),
        EventDispatcher     = require("utils/EventDispatcher"),
        PreferencesManager  = require("preferences/PreferencesManager"),
        _                   = require("thirdparty/lodash");

    /**
     * @const
     * CSS class to use for live preview errors.
     * @type {string}
     */
    var SYNC_ERROR_CLASS = "live-preview-sync-error";

    function _simpleHash(str) {
        let hash = 5381;
        for (let i = 0; i < str.length; ) {
            // eslint-disable-next-line no-bitwise
            hash = (hash * 33) ^ str.charCodeAt(i++);
        }
        // eslint-disable-next-line no-bitwise
        return hash >>> 0;
    }

    /**
     * @constructor
     * Base class for managing the connection between a live editor and the browser. Provides functions
     * for subclasses to highlight relevant nodes in the browser, and to mark errors in the editor.
     *
     * Raises these events:
     *     "connect" - when a browser connects from the URL that maps to this live document. Passes the
     *          URL as a parameter.
     *     "errorStatusChanged" - when the status of errors that might prevent live edits from
     *          working (e.g. HTML syntax errors) has changed. Passes a boolean that's true if there
     *          are errors, false otherwise.
     *
     * @param {LiveDevProtocol} protocol The protocol to use for communicating with the browser.
     * @param {function(string): string} urlResolver A function that, given a path on disk, should return
     *     the URL that Live Development serves that path at.
     * @param {Document} doc The Brackets document that this live document is connected to.
     * @param {?Editor} editor If specified, a particular editor that this live document is managing.
     *     If not specified initially, the LiveDocument will connect to the editor for the given document
     *     when it next becomes the active editor.
     */
    function LiveDocument(protocol, urlResolver, doc, editor, roots) {
        this.protocol = protocol;
        this.urlResolver = urlResolver;
        this.doc = doc;
        this.roots = roots || [];

        this._onActiveEditorChange = this._onActiveEditorChange.bind(this);
        this._onCursorActivity = this._onCursorActivity.bind(this);

        // we cant use file paths for event registration - paths may have spaces(treated as an event list separator)
        this.fileHashForEvents = _simpleHash(this.doc.file.fullPath);
        EditorManager.off(`activeEditorChange.LiveDocument-${this.fileHashForEvents}`);
        EditorManager.on(`activeEditorChange.LiveDocument-${this.fileHashForEvents}`, this._onActiveEditorChange);

        if (editor) {
            // Attach now
            this._attachToEditor(editor);
        }
    }

    EventDispatcher.makeEventDispatcher(LiveDocument.prototype);

    /**
     * Closes the live document, terminating its connection to the browser.
     */
    LiveDocument.prototype.close = function () {
        EditorManager.off(`activeEditorChange.LiveDocument-${this.fileHashForEvents}`);
        this._clearErrorDisplay();
        this._detachFromEditor();
    };

    /**
     * Returns true if document edits appear live in the connected browser.
     * Should be overridden by subclasses.
     * @return {boolean}
     */
    LiveDocument.prototype.isLiveEditingEnabled = function () {
        return false;
    };

    /**
     * Called to turn instrumentation on or off for this file. Triggered by being
     * requested from the browser. Should be implemented by subclasses if instrumentation
     * is necessary for the subclass's document type.
     * TODO: this doesn't seem necessary...if we're a live document, we should
     * always have instrumentation on anyway.
     * @param {boolean} enabled
     */
    LiveDocument.prototype.setInstrumentationEnabled = function (enabled) {
        // Does nothing in base class.
    };

    /**
     * Returns the instrumented version of the file. By default, just returns
     * the document text. Should be overridden by subclasses for cases if instrumentation
     * is necessary for the subclass's document type.
     * @return {{body: string}} document body
     */
    LiveDocument.prototype.getResponseData = function (enabled) {
        return {
            body: this.doc.getText()
        };
    };

    /**
     * @private
     * Handles when the active editor changes, attaching to the new editor if it's for the current document.
     * @param {$.Event} event
     * @param {?Editor} newActive
     * @param {?Editor} oldActive
     */
    LiveDocument.prototype._onActiveEditorChange = function (event, newActive, oldActive) {
        this._detachFromEditor();

        if (newActive && newActive.document.file.fullPath === this.doc.file.fullPath) {
            this._attachToEditor(newActive);
        }
    };

    /**
     * @private
     * Attaches to an editor for our associated document when it becomes active.
     * @param {Editor} editor
     */
    LiveDocument.prototype._attachToEditor = function (editor) {
        this.editor = editor;

        if (this.editor) {
            this.setInstrumentationEnabled(true, true);
            this.editor.off("cursorActivity", this._onCursorActivity);
            this.editor.on("cursorActivity", this._onCursorActivity);
            this.updateHighlight();
        }
    };

    /**
     * @private
     * Detaches from the current editor.
     */
    LiveDocument.prototype._detachFromEditor = function () {
        if (this.editor) {
            this.hideHighlight();
            this.editor.off("cursorActivity", this._onCursorActivity);
        }
    };

    let _disableHighlightOnCursor = false;

    /**
     * If tur, it will disable highlights in live preview on cursor movement in editor
     * @param {boolean} shouldDisable
     */
    LiveDocument.prototype.disableHighlightOnCursorActivity = function (shouldDisable) {
        // intentionally global. see usage for details
        _disableHighlightOnCursor = shouldDisable;
    };

    /**
     * @private
     * Handles a cursor change in our attached editor. Updates the highlight in the browser.
     * @param {$.Event} event
     * @param {Editor} editor
     */
    LiveDocument.prototype._onCursorActivity = function (event, editor) {
        if (!this.editor) {
            return;
        }
        if(!_disableHighlightOnCursor){
            this.updateHighlight();
        }
    };

    /**
     * @private
     * Update errors shown by the live document in the editor. Should be called by subclasses
     * when the list of errors changes.
     */
    LiveDocument.prototype._updateErrorDisplay = function () {
        var self = this,
            startLine,
            endLine,
            i,
            lineHandle;

        if (!this.editor) {
            return;
        }

        // Buffer addLineClass DOM changes in a CodeMirror operation
        this.editor._codeMirror.operation(function () {
            // Remove existing errors before marking new ones
            self._clearErrorDisplay();

            self._errorLineHandles = self._errorLineHandles || [];

            self.errors.forEach(function (error) {
                startLine = error.startPos.line;
                endLine = error.endPos.line;

                for (i = startLine; i < endLine + 1; i++) {
                    lineHandle = self.editor._codeMirror.addLineClass(i, "wrap", SYNC_ERROR_CLASS);
                    self._errorLineHandles.push(lineHandle);
                }
            });
        });

        this.trigger("errorStatusChanged", !!this.errors.length);
    };

    /**
     * @private
     * Clears the errors shown in the attached editor.
     */
    LiveDocument.prototype._clearErrorDisplay = function () {
        var self = this,
            lineHandle;

        if (!this.editor ||
                !this._errorLineHandles ||
                !this._errorLineHandles.length) {
            return;
        }

        this.editor._codeMirror.operation(function () {
            while (true) {
                // Iterate over all lines that were previously marked with an error
                lineHandle = self._errorLineHandles.pop();

                if (!lineHandle) {
                    break;
                }

                self.editor._codeMirror.removeLineClass(lineHandle, "wrap", SYNC_ERROR_CLASS);
            }
        });
    };

    /**
     * Returns true if we should be highlighting.
     * @return {boolean}
     */
    LiveDocument.prototype.isHighlightEnabled = function () {
        return PreferencesManager.get(CONSTANTS.PREFERENCE_LIVE_PREVIEW_MODE) !== CONSTANTS.LIVE_PREVIEW_MODE;
    };

    /**
     * Called when the highlight in the browser should be updated because the user has
     * changed the selection. Does nothing in base class, should be implemented by subclasses
     * that implement highlighting functionality.
     */
    LiveDocument.prototype.updateHighlight = function () {
        // Does nothing in base class
    };

    /**
     * Hides the current highlight in the browser.
     * @param {boolean=} temporary If true, this isn't a change of state - we're just about
     *     to re-highlight.
     */
    LiveDocument.prototype.hideHighlight = function (temporary) {
        if (!temporary) {
            this._lastHighlight = null;
        }
        this.protocol.evaluate("_LD.hideHighlight()");
    };

    /**
     * Highlight all nodes affected by a CSS rule. Should be called by subclass implementations of
     * `updateHighlight()`.
     * @param {string} name The selector whose matched nodes should be highlighted.
     */
    LiveDocument.prototype.highlightRule = function (name) {
        if (this._lastHighlight === name) {
            return;
        }
        this._lastHighlight = name;
        this.protocol.evaluate("_LD.highlightRule(" + JSON.stringify(name) + ")");
    };

    /**
     * Highlight all nodes with 'data-brackets-id' value
     * that matches id, or if id is an array, matches any of the given ids.
     * Should be called by subclass implementations of
     * `updateHighlight()`.
     * @param {string|Array.<string>} value of the 'data-brackets-id' to match,
     * or an array of such.
     */
    LiveDocument.prototype.highlightDomElement = function (ids) {
        var selector = "";
        if (!Array.isArray(ids)) {
            ids = [ids];
        }
        _.each(ids, function (id) {
            if (selector !== "") {
                selector += ",";
            }
            selector += "[data-brackets-id='" + id + "']";
        });
        this.highlightRule(selector);
    };

    /**
     * Redraw active highlights.
     */
    LiveDocument.prototype.redrawHighlights = function () {
        if (this.isHighlightEnabled()) {
            this.protocol.evaluate("_LD.redrawHighlights()");
        }
    };

    module.exports = LiveDocument;
});