JezK
Edit File: code-editor.js
/** * @output wp-admin/js/code-editor.js */ /* global console */ /* eslint-env es2020 */ if ( 'undefined' === typeof window.wp ) { /** * @namespace wp */ window.wp = {}; } if ( 'undefined' === typeof window.wp.codeEditor ) { /** * @namespace wp.codeEditor */ window.wp.codeEditor = {}; } /** * @typedef {object} CodeMirrorState * @property {boolean} [completionActive] - Whether completion is active. * @property {boolean} [focused] - Whether the editor is focused. */ /** * @typedef {import('codemirror').EditorFromTextArea & { * options: import('codemirror').EditorConfiguration, * performLint?: () => void, * showHint?: (options: import('codemirror').ShowHintOptions) => void, * state: CodeMirrorState * }} CodeMirrorEditor */ /** * @typedef {object} LintAnnotation * @property {string} message - Message. * @property {'error'|'warning'} severity - Severity. * @property {import('codemirror').Position} from - From position. * @property {import('codemirror').Position} to - To position. */ /** * @typedef {object} CodeMirrorTokenState * @property {object} [htmlState] - HTML state. * @property {string} [htmlState.tagName] - Tag name. * @property {CodeMirrorTokenState} [curState] - Current state. */ /** * @typedef {import('codemirror').EditorConfiguration & { * lint?: boolean | CombinedLintOptions, * autoCloseBrackets?: boolean, * matchBrackets?: boolean, * continueComments?: boolean, * styleActiveLine?: boolean * }} CodeMirrorSettings */ /** * @typedef {object} CSSLintRules * @property {boolean} [errors] - Errors. * @property {boolean} [box-model] - Box model rules. * @property {boolean} [display-property-grouping] - Display property grouping rules. * @property {boolean} [duplicate-properties] - Duplicate properties rules. * @property {boolean} [known-properties] - Known properties rules. * @property {boolean} [outline-none] - Outline none rules. */ /** * @typedef {object} JSHintRules * @property {number} [esversion] - ECMAScript version. * @property {boolean} [module] - Whether to use modules. * @property {boolean} [boss] - Whether to allow assignments in control expressions. * @property {boolean} [curly] - Whether to require curly braces. * @property {boolean} [eqeqeq] - Whether to require === and !==. * @property {boolean} [eqnull] - Whether to allow == null. * @property {boolean} [expr] - Whether to allow expressions. * @property {boolean} [immed] - Whether to require immediate function invocation. * @property {boolean} [noarg] - Whether to prohibit arguments.caller/callee. * @property {boolean} [nonbsp] - Whether to prohibit non-breaking spaces. * @property {string} [quotmark] - Quote mark preference. * @property {boolean} [undef] - Whether to prohibit undefined variables. * @property {boolean} [unused] - Whether to prohibit unused variables. * @property {boolean} [browser] - Whether to enable browser globals. * @property {Record<string, boolean>} [globals] - Global variables. */ /** * @typedef {object} HTMLHintRules * @property {boolean} [tagname-lowercase] - Tag name lowercase rules. * @property {boolean} [attr-lowercase] - Attribute lowercase rules. * @property {boolean} [attr-value-double-quotes] - Attribute value double quotes rules. * @property {boolean} [doctype-first] - Doctype first rules. * @property {boolean} [tag-pair] - Tag pair rules. * @property {boolean} [spec-char-escape] - Spec char escape rules. * @property {boolean} [id-unique] - ID unique rules. * @property {boolean} [src-not-empty] - Src not empty rules. * @property {boolean} [attr-no-duplication] - Attribute no duplication rules. * @property {boolean} [alt-require] - Alt require rules. * @property {string} [space-tab-mixed-disabled] - Space tab mixed disabled rules. * @property {boolean} [attr-unsafe-chars] - Attribute unsafe chars rules. * @property {JSHintRules} [jshint] - JSHint rules. * @property {CSSLintRules} [csslint] - CSSLint rules. */ /** * Settings for the code editor. * * @typedef {object} CodeEditorSettings * * @property {CodeMirrorSettings} [codemirror] - CodeMirror settings. * @property {CSSLintRules} [csslint] - CSSLint rules. * @property {JSHintRules} [jshint] - JSHint rules. * @property {HTMLHintRules} [htmlhint] - HTMLHint rules. * * @property {(codemirror: CodeMirrorEditor, event: KeyboardEvent|JQuery.KeyDownEvent) => void} [onTabNext] - Callback to handle tabbing to the next tabbable element. * @property {(codemirror: CodeMirrorEditor, event: KeyboardEvent|JQuery.KeyDownEvent) => void} [onTabPrevious] - Callback to handle tabbing to the previous tabbable element. * @property {(errorAnnotations: LintAnnotation[], annotations: LintAnnotation[], annotationsSorted: LintAnnotation[], cm: CodeMirrorEditor) => void} [onChangeLintingErrors] - Callback for when the linting errors have changed. * @property {(errorAnnotations: LintAnnotation[], editor: CodeMirrorEditor) => void} [onUpdateErrorNotice] - Callback for when error notice should be displayed. */ /** * @typedef {import('codemirror/addon/lint/lint').LintStateOptions<Record<string, unknown>> & JSHintRules & CSSLintRules & { rules?: HTMLHintRules }} CombinedLintOptions */ /** * @typedef {object} CodeEditorInstance * @property {CodeEditorSettings} settings - The code editor settings. * @property {CodeMirrorEditor} codemirror - The CodeMirror instance. * @property {() => void} updateErrorNotice - Force update the error notice. */ /** * @typedef {object} WpCodeEditor * @property {CodeEditorSettings} defaultSettings - Default settings. * @property {(textarea: string|JQuery|Element, settings?: CodeEditorSettings) => CodeEditorInstance} initialize - Initialize. */ /** * @param {JQueryStatic} $ - jQuery. * @param {Object & { * codeEditor: WpCodeEditor, * CodeMirror: typeof import('codemirror'), * }} wp - WordPress namespace. */ ( function( $, wp ) { 'use strict'; /** * Default settings for code editor. * * @since 4.9.0 * @type {CodeEditorSettings} */ wp.codeEditor.defaultSettings = { codemirror: {}, csslint: {}, htmlhint: {}, jshint: {}, onTabNext: function() {}, onTabPrevious: function() {}, onChangeLintingErrors: function() {}, onUpdateErrorNotice: function() {}, }; /** * Configure linting. * * @param {CodeEditorSettings} settings - Code editor settings. * * @return {LintingController} Linting controller. */ function configureLinting( settings ) { // eslint-disable-line complexity /** @type {LintAnnotation[]} */ let currentErrorAnnotations = []; /** @type {LintAnnotation[]} */ let previouslyShownErrorAnnotations = []; /** * Call the onUpdateErrorNotice if there are new errors to show. * * @param {import('codemirror').Editor} editor - Editor. * @return {void} */ function updateErrorNotice( editor ) { if ( settings.onUpdateErrorNotice && ! _.isEqual( currentErrorAnnotations, previouslyShownErrorAnnotations ) ) { settings.onUpdateErrorNotice( currentErrorAnnotations, /** @type {CodeMirrorEditor} */ ( editor ) ); previouslyShownErrorAnnotations = currentErrorAnnotations; } } /** * Get lint options. * * @return {CombinedLintOptions|false} Lint options. */ function getLintOptions() { // eslint-disable-line complexity /** @type {CombinedLintOptions | boolean} */ let options = settings.codemirror?.lint ?? false; if ( ! options ) { return false; } if ( true === options ) { options = {}; } else if ( _.isObject( options ) ) { options = $.extend( {}, options ); } const linterOptions = /** @type {CombinedLintOptions} */ ( options ); // Configure JSHint. if ( 'javascript' === settings.codemirror?.mode && settings.jshint ) { $.extend( linterOptions, settings.jshint ); } // Configure CSSLint. if ( 'css' === settings.codemirror?.mode && settings.csslint ) { $.extend( linterOptions, settings.csslint ); } // Configure HTMLHint. if ( 'htmlmixed' === settings.codemirror?.mode && settings.htmlhint ) { linterOptions.rules = $.extend( {}, settings.htmlhint ); if ( settings.jshint && linterOptions.rules ) { linterOptions.rules.jshint = settings.jshint; } if ( settings.csslint && linterOptions.rules ) { linterOptions.rules.csslint = settings.csslint; } } // Wrap the onUpdateLinting CodeMirror event to route to onChangeLintingErrors and onUpdateErrorNotice. linterOptions.onUpdateLinting = (function( onUpdateLintingOverridden ) { /** * @param {LintAnnotation[]} annotations - Annotations. * @param {LintAnnotation[]} annotationsSorted - Sorted annotations. * @param {CodeMirrorEditor} cm - Editor. */ return function( annotations, annotationsSorted, cm ) { const errorAnnotations = annotations.filter( function( annotation ) { return 'error' === annotation.severity; } ); if ( onUpdateLintingOverridden ) { onUpdateLintingOverridden( annotations, annotationsSorted, cm ); } // Skip if there are no changes to the errors. if ( _.isEqual( errorAnnotations, currentErrorAnnotations ) ) { return; } currentErrorAnnotations = errorAnnotations; if ( settings.onChangeLintingErrors ) { settings.onChangeLintingErrors( errorAnnotations, annotations, annotationsSorted, cm ); } /* * Update notifications when the editor is not focused to prevent error message * from overwhelming the user during input, unless there are now no errors or there * were previously errors shown. In these cases, update immediately so they can know * that they fixed the errors. */ if ( ! cm.state.focused || 0 === currentErrorAnnotations.length || previouslyShownErrorAnnotations.length > 0 ) { updateErrorNotice( cm ); } }; })( linterOptions.onUpdateLinting ); return linterOptions; } return { getLintOptions, /** * @param {CodeMirrorEditor} editor - Editor instance. * @return {void} */ init: function( editor ) { // Keep lint options populated. editor.on( 'optionChange', function( _cm, option ) { const gutterName = 'CodeMirror-lint-markers'; if ( 'lint' !== ( /** @type {string} */ ( option ) ) ) { return; } const gutters = ( /** @type {string[]} */ ( editor.getOption( 'gutters' ) ) ) || []; const options = editor.getOption( 'lint' ); if ( true === options ) { if ( ! _.contains( gutters, gutterName ) ) { editor.setOption( 'gutters', [ gutterName ].concat( gutters ) ); } editor.setOption( 'lint', getLintOptions() ); // Expand to include linting options. } else if ( ! options ) { editor.setOption( 'gutters', _.without( gutters, gutterName ) ); } // Force update on error notice to show or hide. if ( editor.getOption( 'lint' ) && editor.performLint ) { editor.performLint(); } else { currentErrorAnnotations = []; updateErrorNotice( editor ); } } ); // Update error notice when leaving the editor. editor.on( 'blur', updateErrorNotice ); // Work around hint selection with mouse causing focus to leave editor. editor.on( 'startCompletion', function() { editor.off( 'blur', updateErrorNotice ); } ); editor.on( 'endCompletion', function() { const editorRefocusWait = 500; editor.on( 'blur', updateErrorNotice ); // Wait for editor to possibly get re-focused after selection. _.delay( function() { if ( ! editor.state.focused ) { updateErrorNotice( editor ); } }, editorRefocusWait ); } ); /* * Make sure setting validities are set if the user tries to click Publish * while an autocomplete dropdown is still open. The Customizer will block * saving when a setting has an error notifications on it. This is only * necessary for mouse interactions because keyboards will have already * blurred the field and cause onUpdateErrorNotice to have already been * called. */ $( document.body ).on( 'mousedown', function( /** @type {JQuery.MouseDownEvent} */ event ) { if ( editor.state.focused && ! editor.getWrapperElement().contains( event.target ) && ! event.target.classList.contains( 'CodeMirror-hint' ) ) { updateErrorNotice( editor ); } } ); }, /** * @param {CodeMirrorEditor} editor - Editor instance. * @return {void} */ updateErrorNotice, }; } /** * Configure tabbing. * * @param {CodeMirrorEditor} codemirror - Editor. * @param {CodeEditorSettings} settings - Code editor settings. * * @return {void} */ function configureTabbing( codemirror, settings ) { const $textarea = $( codemirror.getTextArea() ); codemirror.on( 'blur', function() { $textarea.data( 'next-tab-blurs', false ); }); codemirror.on( 'keydown', function onKeydown( _editor, event ) { // Take note of the ESC keypress so that the next TAB can focus outside the editor. if ( 'Escape' === event.key ) { $textarea.data( 'next-tab-blurs', true ); return; } // Short-circuit if tab key is not being pressed or the tab key press should move focus. if ( 'Tab' !== event.key || ! $textarea.data( 'next-tab-blurs' ) ) { return; } // Focus on previous or next focusable item. if ( event.shiftKey && settings.onTabPrevious ) { settings.onTabPrevious( codemirror, event ); } else if ( ! event.shiftKey && settings.onTabNext ) { settings.onTabNext( codemirror, event ); } // Reset tab state. $textarea.data( 'next-tab-blurs', false ); // Prevent tab character from being added. event.preventDefault(); }); } /** * @typedef {object} LintingController * @property {() => CombinedLintOptions|false} getLintOptions - Get lint options. * @property {(editor: CodeMirrorEditor) => void} init - Initialize. * @property {(editor: import('codemirror').Editor) => void} updateErrorNotice - Update error notice. */ /** * Initialize Code Editor (CodeMirror) for an existing textarea. * * @since 4.9.0 * * @param {string|JQuery<HTMLElement>|HTMLElement} textarea - The HTML id, jQuery object, or DOM Element for the textarea that is used for the editor. * @param {CodeEditorSettings} [settings] - Settings to override defaults. * * @return {CodeEditorInstance} Instance. */ wp.codeEditor.initialize = function initialize( textarea, settings ) { if ( document.readyState === 'loading' ) { console.warn( 'wp.codeEditor.initialize() ran too early. Invoke this function in a `DOMContentLoaded` event listener.' ); } let $textarea; if ( 'string' === typeof textarea ) { $textarea = $( '#' + textarea ); } else { $textarea = $( textarea ); } /** @type {CodeEditorSettings} */ const instanceSettings = $.extend( true, {}, wp.codeEditor.defaultSettings, settings ); const lintingController = configureLinting( instanceSettings ); if ( instanceSettings.codemirror ) { instanceSettings.codemirror.lint = lintingController.getLintOptions(); } const codemirror = /** @type {CodeMirrorEditor} */ ( wp.CodeMirror.fromTextArea( $textarea[0], instanceSettings.codemirror ) ); lintingController.init( codemirror ); /** @type {CodeEditorInstance} */ const instance = { settings: instanceSettings, codemirror, updateErrorNotice: function() { lintingController.updateErrorNotice( codemirror ); }, }; if ( codemirror.showHint ) { codemirror.on( 'inputRead', function( _editor, change ) { // Only trigger autocompletion for typed input or IME composition. if ( ! change.origin || ( '+input' !== change.origin && ! change.origin.startsWith( '*compose' ) ) ) { return; } // Only trigger autocompletion for single-character inputs. // The text property is an array of strings, one for each line. // We check that there is only one line and that line has only one character. if ( 1 !== change.text.length || 1 !== change.text[0].length ) { return; } const char = change.text[0]; const isAlphaKey = /^[a-zA-Z]$/.test( char ); if ( codemirror.state.completionActive && isAlphaKey ) { return; } // Prevent autocompletion in string literals or comments. const token = /** @type {import('codemirror').Token & { state: CodeMirrorTokenState }} */ ( codemirror.getTokenAt( codemirror.getCursor() ) ); if ( 'string' === token.type || 'comment' === token.type ) { return; } const innerMode = wp.CodeMirror.innerMode( codemirror.getMode(), token.state ).mode.name; const doc = codemirror.getDoc(); const lineBeforeCursor = doc.getLine( doc.getCursor().line ).slice( 0, doc.getCursor().ch ); let shouldAutocomplete = false; if ( 'html' === innerMode || 'xml' === innerMode ) { shouldAutocomplete = ( '<' === char || ( '/' === char && 'tag' === token.type ) || ( isAlphaKey && 'tag' === token.type ) || ( isAlphaKey && 'attribute' === token.type ) || ( '=' === char && !! ( token.state.htmlState?.tagName || token.state.curState?.htmlState?.tagName ) ) ); } else if ( 'css' === innerMode ) { shouldAutocomplete = isAlphaKey || ':' === char || ( ' ' === char && /:\s+$/.test( lineBeforeCursor ) ); } else if ( 'javascript' === innerMode ) { shouldAutocomplete = isAlphaKey || '.' === char; } else if ( 'clike' === innerMode && 'php' === codemirror.options.mode ) { shouldAutocomplete = isAlphaKey && ( 'keyword' === token.type || 'variable' === token.type ); } if ( shouldAutocomplete ) { codemirror.showHint( { completeSingle: false } ); } } ); } // Facilitate tabbing out of the editor. configureTabbing( codemirror, instanceSettings ); return instance; }; })( jQuery, window.wp );