const { Compartment, EditorState, EditorView, Extension, KeyBinding, ViewUpdate, bracketMatching, crosshairCursor, defaultKeymap, drawSelection, highlightActiveLine, highlightSpecialChars, history, historyKeymap, indentUnit, keymap, lineNumbers, rectangularSelection, redo } = require( 'ext.CodeMirror.v6.lib' ); const CodeMirrorTextSelection = require( './codemirror.textSelection.js' ); const CodeMirrorSearch = require( './codemirror.search.js' ); const CodeMirrorGotoLine = require( './codemirror.gotoLine.js' ); const CodeMirrorPreferences = require( './codemirror.preferences.js' ); require( './ext.CodeMirror.data.js' ); /** * Interface for the CodeMirror editor. * * @example * mw.loader.using( [ * 'ext.CodeMirror.v6', * 'ext.CodeMirror.v6.mode.mediawiki' * ] ).then( ( require ) => { * const CodeMirror = require( 'ext.CodeMirror.v6' ); * const mediawikiLang = require( 'ext.CodeMirror.v6.mode.mediawiki' ); * const cm = new CodeMirror( myTextarea ); * cm.initialize( [ cm.defaultExtensions, mediawikiLang() ] ); * } ); */ class CodeMirror { /** * Instantiate a new CodeMirror instance. * * @param {HTMLTextAreaElement|jQuery|string|ve.ui.Surface} textarea Textarea to * add syntax highlighting to. * @constructor */ constructor( textarea ) { if ( textarea.constructor.name === 'VeUiMWWikitextSurface' ) { /** * The VisualEditor surface CodeMirror is bound to. * * @type {ve.ui.Surface} */ this.surface = textarea; // Let the content editable mimic the textarea. // eslint-disable-next-line no-jquery/variable-pattern textarea = this.surface.getView().$attachedRootNode; } /** * The textarea that CodeMirror is bound to. * * @type {jQuery} */ this.$textarea = $( textarea ); /** * The editor user interface. * * @type {EditorView} */ this.view = null; /** * The editor state. * * @type {EditorState} */ this.state = null; /** * Whether the textarea is read-only. * * @type {boolean} */ this.readOnly = this.surface ? this.surface.getModel().isReadOnly() : this.$textarea.prop( 'readonly' ); /** * The [edit recovery]{@link https://www.mediawiki.org/wiki/Manual:Edit_Recovery} handler. * * @type {Function|null} */ this.editRecoveryHandler = null; /** * The form `submit` event handler. * * @type {Function|null} */ this.formSubmitEventHandler = null; /** * jQuery.textSelection overrides for CodeMirror. * * @type {CodeMirrorTextSelection} */ this.textSelection = null; /** * Compartment to control the direction of the editor. * * @type {Compartment} */ this.dirCompartment = new Compartment(); /** * The CodeMirror preferences panel. * * @type {CodeMirrorPreferences} */ this.preferences = new CodeMirrorPreferences( { bracketMatching: this.bracketMatchingExtension, lineNumbering: this.lineNumberingExtension, lineWrapping: this.lineWrappingExtension, activeLine: this.activeLineExtension, specialChars: this.specialCharsExtension }, !!this.surface ); } /** * Default extensions used by CodeMirror. * Extensions here should be applicable to all theoretical uses of CodeMirror in MediaWiki. * * @see https://codemirror.net/docs/ref/#state.Extension * @type {Extension|Extension[]} * @stable to call */ get defaultExtensions() { const extensions = [ this.contentAttributesExtension, this.phrasesExtension, this.heightExtension, this.updateExtension, this.dirExtension, this.searchExtension, this.preferences.extension, indentUnit.of( '\t' ), EditorState.readOnly.of( this.readOnly ), EditorView.domEventHandlers( { blur: () => { this.$textarea[ 0 ].dispatchEvent( new Event( 'blur' ) ); }, focus: () => { this.$textarea[ 0 ].dispatchEvent( new Event( 'focus' ) ); } } ), keymap.of( defaultKeymap ), EditorState.allowMultipleSelections.of( true ), drawSelection(), rectangularSelection(), crosshairCursor() ]; // Add extensions relevant to editing (not read-only). if ( !this.readOnly ) { extensions.push( EditorView.updateListener.of( ( update ) => { if ( update.docChanged && typeof this.editRecoveryHandler === 'function' ) { this.editRecoveryHandler(); } } ) ); extensions.push( history() ); extensions.push( keymap.of( historyKeymap.concat( /** @type {KeyBinding} */ { win: 'Ctrl-Shift-z', run: redo, preventDefault: true } ) ) ); } return extensions; } /** * Extension for highlighting the active line. * * @return {Extension} */ get activeLineExtension() { return highlightActiveLine(); } /** * Extension for line wrapping. * * @return {Extension} */ get lineWrappingExtension() { return EditorView.lineWrapping; } /** * Extension for line numbering. * * @return {Extension|Extension[]} */ get lineNumberingExtension() { return lineNumbers(); } /** * Extension for search and goto line functionality. * * @return {Extension|Extension[]} */ get searchExtension() { return [ new CodeMirrorSearch().extension, new CodeMirrorGotoLine().extension ]; } /** * This extension adds bracket matching to the CodeMirror editor. * * @return {Extension} */ get bracketMatchingExtension() { return bracketMatching( mw.config.get( 'wgPageContentModel' ) === 'wikitext' ? { // Also match CJK full-width brackets (T362992) // This is only for wikitext as it can be confusing in programming languages. brackets: '()[]{}()【】[]{}' } : {} ); } /** * This extension listens for changes in the CodeMirror editor and fires * the `ext.CodeMirror.input` hook with the {@link ViewUpdate} object. * * @type {Extension} * @fires CodeMirror~'ext.CodeMirror.input' * @stable to call and override */ get updateExtension() { return EditorView.updateListener.of( ( update ) => { if ( update.docChanged ) { /** * Called when document changes are made in CodeMirror. * The native textarea is not necessarily updated yet. * * @event CodeMirror~'ext.CodeMirror.input' * @param {ViewUpdate} update * @stable to use */ mw.hook( 'ext.CodeMirror.input' ).fire( update ); } } ); } /** * This extension sets the height of the CodeMirror editor to match the textarea. * Override this method to change the height of the editor. * * @type {Extension} * @stable to call and override */ get heightExtension() { return EditorView.theme( { '&': { height: this.surface ? '100%' : `${ this.$textarea.outerHeight() }px` }, '.cm-scroller': { overflow: 'auto' } } ); } /** * This specifies which attributes get added to the `.cm-content` and `.cm-editor` elements. * Subclasses are safe to override this method, but attributes here are considered vital. * * @see https://codemirror.net/docs/ref/#view.EditorView^contentAttributes * @type {Extension} * @stable to call and override */ get contentAttributesExtension() { const classList = []; // T245568: Sync text editor font preferences with CodeMirror, // but don't do this for the 2017 wikitext editor. if ( !this.surface ) { const fontClass = Array.from( this.$textarea[ 0 ].classList ) .find( ( style ) => style.startsWith( 'mw-editfont-' ) ); if ( fontClass ) { classList.push( fontClass ); } // Add colorblind mode if preference is set. // This currently is only to be used for the MediaWiki markup language. if ( mw.user.options.get( 'usecodemirror-colorblind' ) && mw.config.get( 'wgPageContentModel' ) === 'wikitext' ) { classList.push( 'cm-mw-colorblind-colors' ); } } return [ // .cm-content element (the contenteditable area) EditorView.contentAttributes.of( { // T259347: Use accesskey of the original textbox accesskey: this.$textarea.attr( 'accesskey' ), // Classes need to be on .cm-content to have precedence over .cm-scroller class: classList.join( ' ' ), spellcheck: 'true', tabindex: this.$textarea.attr( 'tabindex' ) } ), // .cm-editor element (contains the whole CodeMirror UI) EditorView.editorAttributes.of( { // Use language of the original textbox. // These should be attributes of .cm-editor, not the .cm-content (T359589) lang: this.$textarea.attr( 'lang' ) } ), // The search panel should use the same direction as the interface language (T359611) EditorView.theme( { '.cm-panels': { direction: document.dir } } ) ]; } /** * These are all potential messages used in a full-featured CodeMirror setup. * We lump them all here and supply it as default extensions because it is only a small cost * and we don't want localization to be overlooked by CodeMirror clients and subclasses. * * @see https://codemirror.net/examples/translate/ * @type {Extension} * @stable to call. Instead of overriding, pass in an additional `EditorState.phrases.of()` * when calling `initialize()`. */ get phrasesExtension() { return EditorState.phrases.of( { 'Control character': mw.msg( 'codemirror-control-character' ) } ); } /** * We give a small subset of special characters a tooltip explaining what they are. * The messages and for what characters are defined here. * Any character that does not have a message will instead use CM6 defaults, * which is the localization of 'codemirror-control-character' followed by the Unicode number. * * @see https://codemirror.net/docs/ref/#view.highlightSpecialChars * @type {Extension} * @stable to call */ get specialCharsExtension() { // Keys are the decimal Unicode number, values are the messages. const messages = { 0: mw.msg( 'codemirror-special-char-null' ), 7: mw.msg( 'codemirror-special-char-bell' ), 8: mw.msg( 'codemirror-special-char-backspace' ), 10: mw.msg( 'codemirror-special-char-newline' ), 11: mw.msg( 'codemirror-special-char-vertical-tab' ), 13: mw.msg( 'codemirror-special-char-carriage-return' ), 27: mw.msg( 'codemirror-special-char-escape' ), 160: mw.msg( 'codemirror-special-char-nbsp' ), 8203: mw.msg( 'codemirror-special-char-zero-width-space' ), 8204: mw.msg( 'codemirror-special-char-zero-width-non-joiner' ), 8205: mw.msg( 'codemirror-special-char-zero-width-joiner' ), 8206: mw.msg( 'codemirror-special-char-left-to-right-mark' ), 8207: mw.msg( 'codemirror-special-char-right-to-left-mark' ), 8232: mw.msg( 'codemirror-special-char-line-separator' ), 8237: mw.msg( 'codemirror-special-char-left-to-right-override' ), 8238: mw.msg( 'codemirror-special-char-right-to-left-override' ), 8239: mw.msg( 'codemirror-special-char-narrow-nbsp' ), 8294: mw.msg( 'codemirror-special-char-left-to-right-isolate' ), 8295: mw.msg( 'codemirror-special-char-right-to-left-isolate' ), 8297: mw.msg( 'codemirror-special-char-pop-directional-isolate' ), 8233: mw.msg( 'codemirror-special-char-paragraph-separator' ), 65279: mw.msg( 'codemirror-special-char-zero-width-no-break-space' ), 65532: mw.msg( 'codemirror-special-char-object-replacement' ) }; return highlightSpecialChars( { render: ( code, description, placeholder ) => { description = messages[ code ] || mw.msg( 'codemirror-control-character', code ); const span = document.createElement( 'span' ); span.className = 'cm-specialChar'; // Special case non-breaking spaces (T181677). if ( code === 160 || code === 8239 ) { placeholder = '·'; span.className = 'cm-special-char-nbsp'; } span.textContent = placeholder; span.title = description; span.setAttribute( 'aria-label', description ); return span; }, // Highlight non-breaking spaces (T181677) addSpecialChars: /[\u00a0\u202f]/g } ); } /** * This extension adds the ability to change the direction of the editor. * * @type {Extension} * @stable to call */ get dirExtension() { return [ this.dirCompartment.of( EditorView.editorAttributes.of( { // Use direction of the original textbox. // These should be attributes of .cm-editor, not the .cm-content (T359589) dir: this.$textarea.attr( 'dir' ) } ) ), keymap.of( [ { key: 'Mod-Shift-x', run: ( view ) => { const dir = this.$textarea.attr( 'dir' ) === 'rtl' ? 'ltr' : 'rtl'; this.$textarea.attr( 'dir', dir ); view.dispatch( { effects: this.dirCompartment.reconfigure( EditorView.editorAttributes.of( { dir } ) ) } ); return true; } } ] ) ]; } /** * Setup CodeMirror and add it to the DOM. This will hide the original textarea. * * @param {Extension|Extension[]} [extensions=this.defaultExtensions] Extensions to use. * @fires CodeMirror~'ext.CodeMirror.initialize' * @fires CodeMirror~'ext.CodeMirror.ready' * @stable to call and override */ initialize( extensions = this.defaultExtensions ) { /** * Called just before CodeMirror is initialized. * This can be used to manipulate the DOM to suit CodeMirror * (i.e. if you manipulate WikiEditor's DOM, you may need this). * * @event CodeMirror~'ext.CodeMirror.initialize' * @param {jQuery} $textarea The textarea that CodeMirror is bound to. * @stable to use */ mw.hook( 'ext.CodeMirror.initialize' ).fire( this.$textarea ); mw.hook( 'editRecovery.loadEnd' ).add( ( data ) => { this.editRecoveryHandler = data.fieldChangeHandler; } ); // Set up the initial EditorState of CodeMirror with contents of the native textarea. this.state = EditorState.create( { doc: this.surface ? this.surface.getDom() : this.$textarea.textSelection( 'getContents' ), extensions } ); // Add CodeMirror view to the DOM. this.addCodeMirrorToDom(); // Hide native textarea and sync CodeMirror contents upon submission. if ( !this.surface ) { this.$textarea.hide(); if ( this.$textarea[ 0 ].form ) { this.formSubmitEventHandler = () => { this.$textarea.val( this.view.state.doc.toString() ); const scrollTop = document.getElementById( 'wpScrolltop' ); if ( scrollTop ) { scrollTop.value = this.view.scrollDOM.scrollTop; } }; this.$textarea[ 0 ].form.addEventListener( 'submit', this.formSubmitEventHandler ); } } // Register $.textSelection() on the .cm-editor element. $( this.view.dom ).textSelection( 'register', this.cmTextSelection ); // Also override textSelection() functions for the "real" hidden textarea to route to // CodeMirror. We unregister this when switching to normal textarea mode. this.$textarea.textSelection( 'register', this.cmTextSelection ); /** * Called just after CodeMirror is initialized. * * @event CodeMirror~'ext.CodeMirror.ready' * @param {jQuery} $view The CodeMirror view element. * @param {CodeMirror} cm The CodeMirror instance. * @stable to use */ mw.hook( 'ext.CodeMirror.ready' ).fire( $( this.view.dom ), this ); } /** * Instantiate the EditorView, adding the CodeMirror editor to the DOM. * We use a dummy container to ensure that the editor will * always be placed where the textarea is. * * @private */ addCodeMirrorToDom() { this.$textarea.wrap( '
' ); this.view = new EditorView( { state: this.state, parent: this.surface ? this.surface.getView().$element[ 0 ] : this.$textarea.parent()[ 0 ] } ); } /** * Destroy the CodeMirror instance and revert to the original textarea. * * @fires CodeMirror~'ext.CodeMirror.destroy' * @stable to call and override */ destroy() { const scrollTop = this.view.scrollDOM.scrollTop; const hasFocus = this.surface ? this.surface.getView().isFocused() : this.view.hasFocus; const { from, to } = this.view.state.selection.ranges[ 0 ]; $( this.view.dom ).textSelection( 'unregister' ); this.$textarea.textSelection( 'unregister' ); this.$textarea.unwrap( '.ext-codemirror-wrapper' ); if ( !this.surface ) { this.$textarea.val( this.view.state.doc.toString() ); } this.view.destroy(); this.view = null; this.$textarea.show(); if ( hasFocus ) { this.$textarea.trigger( 'focus' ); } this.$textarea.prop( 'selectionStart', Math.min( from, to ) ) .prop( 'selectionEnd', Math.max( to, from ) ); this.$textarea.scrollTop( scrollTop ); this.textSelection = null; // remove all hook handlers and event listeners if ( this.formSubmitEventHandler && this.$textarea[ 0 ].form ) { this.$textarea[ 0 ].form.removeEventListener( 'submit', this.formSubmitEventHandler ); this.formSubmitEventHandler = null; } /** * Called just after CodeMirror is destroyed and the original textarea is restored. * * @event CodeMirror~'ext.CodeMirror.destroy' * @param {jQuery} $textarea The original textarea. * @stable to use */ mw.hook( 'ext.CodeMirror.destroy' ).fire( this.$textarea ); } /** * Log usage of CodeMirror. * * @param {Object} data * @stable to call * @internal * @ignore */ static logUsage( data ) { /* eslint-disable camelcase */ const event = Object.assign( { session_token: mw.user.sessionId(), user_id: mw.user.getId() }, data ); const editCountBucket = mw.config.get( 'wgUserEditCountBucket' ); if ( editCountBucket !== null ) { event.user_edit_count_bucket = editCountBucket; } /* eslint-enable camelcase */ mw.track( 'event.CodeMirrorUsage', event ); } /** * Save CodeMirror enabled preference. * * @param {boolean} prefValue True, if CodeMirror should be enabled by default, otherwise false. * @stable to call and override */ static setCodeMirrorPreference( prefValue ) { // Skip for unnamed users if ( !mw.user.isNamed() ) { return; } new mw.Api().saveOption( 'usecodemirror', prefValue ? 1 : 0 ); mw.user.options.set( 'usecodemirror', prefValue ? 1 : 0 ); } /** * jQuery.textSelection overrides for CodeMirror. * * @see jQuery.fn.textSelection * @type {Object} * @private */ get cmTextSelection() { if ( !this.textSelection ) { this.textSelection = new CodeMirrorTextSelection( this.view ); } return { getContents: () => this.textSelection.getContents(), setContents: ( content ) => this.textSelection.setContents( content ), getCaretPosition: ( options ) => this.textSelection.getCaretPosition( options ), scrollToCaretPosition: () => this.textSelection.scrollToCaretPosition(), getSelection: () => this.textSelection.getSelection(), setSelection: ( options ) => this.textSelection.setSelection( options ), replaceSelection: ( value ) => this.textSelection.replaceSelection( value ), encapsulateSelection: ( options ) => this.textSelection.encapsulateSelection( options ) }; } } module.exports = CodeMirror;