mentionui.js 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586
  1. /**
  2. * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /**
  6. * @module mention/mentionui
  7. */
  8. import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
  9. import ButtonView from '@ckeditor/ckeditor5-ui/src/button/buttonview';
  10. import Collection from '@ckeditor/ckeditor5-utils/src/collection';
  11. import BalloonPanelView from '@ckeditor/ckeditor5-ui/src/panel/balloon/balloonpanelview';
  12. import clickOutsideHandler from '@ckeditor/ckeditor5-ui/src/bindings/clickoutsidehandler';
  13. import { keyCodes } from '@ckeditor/ckeditor5-utils/src/keyboard';
  14. import Rect from '@ckeditor/ckeditor5-utils/src/dom/rect';
  15. import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  16. import TextWatcher from './textwatcher';
  17. import MentionsView from './ui/mentionsview';
  18. import DomWrapperView from './ui/domwrapperview';
  19. import MentionListItemView from './ui/mentionlistitemview';
  20. const VERTICAL_SPACING = 3;
  21. /**
  22. * The mention UI feature.
  23. *
  24. * @extends module:core/plugin~Plugin
  25. */
  26. export default class MentionUI extends Plugin {
  27. /**
  28. * @inheritDoc
  29. */
  30. static get pluginName() {
  31. return 'MentionUI';
  32. }
  33. /**
  34. * @inheritDoc
  35. */
  36. constructor( editor ) {
  37. super( editor );
  38. /**
  39. * The balloon panel view, containing the mention view.
  40. *
  41. * @type {module:ui/panel/balloon/balloonpanelview~BalloonPanelView}
  42. */
  43. this.panelView = this._creatPanelView();
  44. /**
  45. * The mentions view.
  46. *
  47. * @type {module:mention/ui/mentionsview~MentionsView}
  48. * @private
  49. */
  50. this._mentionsView = this._createMentionView();
  51. /**
  52. * Stores mentions feeds configurations.
  53. *
  54. * @type {Map<String, Object>}
  55. * @private
  56. */
  57. this._mentionsConfigurations = new Map();
  58. editor.config.define( 'mention', { feeds: [] } );
  59. }
  60. /**
  61. * @inheritDoc
  62. */
  63. init() {
  64. // Key listener that handles navigation in mention view.
  65. this.editor.editing.view.document.on( 'keydown', ( evt, data ) => {
  66. if ( isHandledKey( data.keyCode ) && this.panelView.isVisible ) {
  67. data.preventDefault();
  68. evt.stop(); // Required for enter overriding.
  69. if ( data.keyCode == keyCodes.arrowdown ) {
  70. this._mentionsView.selectNext();
  71. }
  72. if ( data.keyCode == keyCodes.arrowup ) {
  73. this._mentionsView.selectPrevious();
  74. }
  75. if ( data.keyCode == keyCodes.enter || data.keyCode == keyCodes.tab || data.keyCode == keyCodes.space ) {
  76. this._mentionsView.executeSelected();
  77. }
  78. if ( data.keyCode == keyCodes.esc ) {
  79. this._hidePanelAndRemoveMarker();
  80. }
  81. }
  82. }, { priority: 'highest' } ); // Required to override enter.
  83. // Close the #panelView upon clicking outside of the plugin UI.
  84. clickOutsideHandler( {
  85. emitter: this.panelView,
  86. contextElements: [ this.panelView.element ],
  87. activator: () => this.panelView.isVisible,
  88. callback: () => this._hidePanelAndRemoveMarker()
  89. } );
  90. const feeds = this.editor.config.get( 'mention.feeds' );
  91. for ( const mentionDescription of feeds ) {
  92. const feed = mentionDescription.feed;
  93. const marker = mentionDescription.marker;
  94. if ( !marker || marker.length != 1 ) {
  95. /**
  96. * The marker must be a single character.
  97. *
  98. * Correct markers: `'@'`, `'#'`.
  99. *
  100. * Incorrect markers: `'$$'`, `'[@'`.
  101. *
  102. * See {@link module:mention/mention~MentionConfig}.
  103. *
  104. * @error mentionconfig-incorrect-marker
  105. */
  106. throw new CKEditorError( 'mentionconfig-incorrect-marker: The marker must be provided and be a single character.' );
  107. }
  108. const minimumCharacters = mentionDescription.minimumCharacters || 0;
  109. const feedCallback = typeof feed == 'function' ? feed : createFeedCallback( feed );
  110. const watcher = this._setupTextWatcherForFeed( marker, minimumCharacters );
  111. const itemRenderer = mentionDescription.itemRenderer;
  112. const definition = { watcher, marker, feedCallback, itemRenderer };
  113. this._mentionsConfigurations.set( marker, definition );
  114. }
  115. }
  116. /**
  117. * @inheritDoc
  118. */
  119. destroy() {
  120. super.destroy();
  121. // Destroy created UI components as they are not automatically destroyed (see ckeditor5#1341).
  122. this.panelView.destroy();
  123. }
  124. /**
  125. * Creates the {@link #panelView}.
  126. *
  127. * @private
  128. * @returns {module:ui/panel/balloon/balloonpanelview~BalloonPanelView}
  129. */
  130. _creatPanelView() {
  131. const panelView = new BalloonPanelView( this.editor.locale );
  132. panelView.withArrow = false;
  133. panelView.render();
  134. this.editor.ui.view.body.add( panelView );
  135. return panelView;
  136. }
  137. /**
  138. * Creates the {@link #_mentionsView}.
  139. *
  140. * @private
  141. * @returns {module:mention/ui/mentionsview~MentionsView}
  142. */
  143. _createMentionView() {
  144. const locale = this.editor.locale;
  145. const mentionsView = new MentionsView( locale );
  146. this._items = new Collection();
  147. this.panelView.content.add( mentionsView );
  148. mentionsView.items.bindTo( this._items ).using( data => {
  149. const { item, marker } = data;
  150. const listItemView = new MentionListItemView( locale );
  151. const view = this._renderItem( item, marker );
  152. view.delegate( 'execute' ).to( listItemView );
  153. listItemView.children.add( view );
  154. listItemView.item = item;
  155. listItemView.marker = marker;
  156. listItemView.on( 'execute', () => {
  157. mentionsView.fire( 'execute', {
  158. item,
  159. marker
  160. } );
  161. } );
  162. return listItemView;
  163. } );
  164. mentionsView.on( 'execute', ( evt, data ) => {
  165. const editor = this.editor;
  166. const model = editor.model;
  167. const item = data.item;
  168. const marker = data.marker;
  169. const watcher = this._getWatcher( marker );
  170. const text = watcher.last;
  171. const textMatcher = createTextMatcher( marker );
  172. const matched = textMatcher( text );
  173. const matchedTextLength = matched.marker.length + matched.feedText.length;
  174. // Create a range on matched text.
  175. const end = model.createPositionAt( model.document.selection.focus );
  176. const start = end.getShiftedBy( -matchedTextLength );
  177. const range = model.createRange( start, end );
  178. this._hidePanelAndRemoveMarker();
  179. editor.execute( 'mention', {
  180. mention: item,
  181. text: item.text,
  182. marker,
  183. range
  184. } );
  185. editor.editing.view.focus();
  186. } );
  187. return mentionsView;
  188. }
  189. /**
  190. * Returns item renderer for marker.
  191. *
  192. * @private
  193. * @param {String} marker
  194. * @returns {Function|null}
  195. */
  196. _getItemRenderer( marker ) {
  197. const { itemRenderer } = this._mentionsConfigurations.get( marker );
  198. return itemRenderer;
  199. }
  200. /**
  201. * Returns a promise that resolves with autocomplete items for given text.
  202. *
  203. * @param {String} marker
  204. * @param {String} feedText
  205. * @return {Promise<module:mention/mention~MentionFeedItem>}
  206. * @private
  207. */
  208. _getFeed( marker, feedText ) {
  209. const { feedCallback } = this._mentionsConfigurations.get( marker );
  210. return Promise.resolve().then( () => feedCallback( feedText ) );
  211. }
  212. /**
  213. * Registers a text watcher for marker.
  214. *
  215. * @private
  216. * @param {String} marker
  217. * @param {Number} minimumCharacters
  218. * @returns {module:mention/textwatcher~TextWatcher}
  219. */
  220. _setupTextWatcherForFeed( marker, minimumCharacters ) {
  221. const editor = this.editor;
  222. const watcher = new TextWatcher( editor, createTestCallback( marker, minimumCharacters ), createTextMatcher( marker ) );
  223. watcher.on( 'matched', ( evt, data ) => {
  224. const matched = data.matched;
  225. const selection = editor.model.document.selection;
  226. const hasMention = selection.hasAttribute( 'mention' );
  227. const nodeBefore = selection.focus.nodeBefore;
  228. if ( hasMention || nodeBefore && nodeBefore.is( 'text' ) && nodeBefore.hasAttribute( 'mention' ) ) {
  229. return;
  230. }
  231. const { feedText, marker } = matched;
  232. const matchedTextLength = marker.length + feedText.length;
  233. // create marker range
  234. const start = selection.focus.getShiftedBy( -matchedTextLength );
  235. const end = selection.focus.getShiftedBy( -feedText.length );
  236. const markerRange = editor.model.createRange( start, end );
  237. let mentionMarker;
  238. if ( editor.model.markers.has( 'mention' ) ) {
  239. mentionMarker = editor.model.markers.get( 'mention' );
  240. } else {
  241. mentionMarker = editor.model.change( writer => writer.addMarker( 'mention', {
  242. range: markerRange,
  243. usingOperation: false,
  244. affectsData: false
  245. } ) );
  246. }
  247. this._getFeed( marker, feedText )
  248. .then( feed => {
  249. this._items.clear();
  250. for ( const feedItem of feed ) {
  251. const item = typeof feedItem != 'object' ? { id: feedItem, text: feedItem } : feedItem;
  252. this._items.add( { item, marker } );
  253. }
  254. if ( this._items.length ) {
  255. this._showPanel( mentionMarker );
  256. } else {
  257. this._hidePanelAndRemoveMarker();
  258. }
  259. } );
  260. } );
  261. watcher.on( 'unmatched', () => {
  262. this._hidePanelAndRemoveMarker();
  263. } );
  264. return watcher;
  265. }
  266. /**
  267. * Returns registered text watcher for marker.
  268. *
  269. * @private
  270. * @param {String} marker
  271. * @returns {module:mention/textwatcher~TextWatcher}
  272. */
  273. _getWatcher( marker ) {
  274. const { watcher } = this._mentionsConfigurations.get( marker );
  275. return watcher;
  276. }
  277. /**
  278. * Shows the {@link #panelView}. If panel is already visible it will reposition it.
  279. *
  280. * @private
  281. */
  282. _showPanel( markerMarker ) {
  283. this.panelView.pin( this._getBalloonPanelPositionData( markerMarker, this.panelView.position ) );
  284. this.panelView.show();
  285. this._mentionsView.selectFirst();
  286. }
  287. /**
  288. * Hides the {@link #panelView} and remove 'mention' marker from markers collection.
  289. *
  290. * @private
  291. */
  292. _hidePanelAndRemoveMarker() {
  293. if ( this.editor.model.markers.has( 'mention' ) ) {
  294. this.editor.model.change( writer => writer.removeMarker( 'mention' ) );
  295. }
  296. this.panelView.unpin();
  297. // Make last matched position on panel view undefined so the #_getBalloonPanelPositionData() will return all positions on next call.
  298. this.panelView.position = undefined;
  299. this.panelView.hide();
  300. }
  301. /**
  302. * Renders a single item in the autocomplete list.
  303. *
  304. * @private
  305. * @param {module:mention/mention~MentionFeedItem} item
  306. * @param {String} marker
  307. * @returns {module:ui/button/buttonview~ButtonView|module:mention/ui/domwrapperview~DomWrapperView}
  308. */
  309. _renderItem( item, marker ) {
  310. const editor = this.editor;
  311. let view;
  312. let label = item.id;
  313. const renderer = this._getItemRenderer( marker );
  314. if ( renderer ) {
  315. const renderResult = renderer( item );
  316. if ( typeof renderResult != 'string' ) {
  317. view = new DomWrapperView( editor.locale, renderResult );
  318. } else {
  319. label = renderResult;
  320. }
  321. }
  322. if ( !view ) {
  323. const buttonView = new ButtonView( editor.locale );
  324. buttonView.label = label;
  325. buttonView.withText = true;
  326. view = buttonView;
  327. }
  328. return view;
  329. }
  330. /**
  331. * Creates position options object used to position the balloon panel.
  332. *
  333. * @param {module:engine/model/markercollection~Marker} mentionMarker
  334. * @param {String|undefined} positionName Name of last matched position name.
  335. * @returns {module:utils/dom/position~Options}
  336. * @private
  337. */
  338. _getBalloonPanelPositionData( mentionMarker, positionName ) {
  339. const editing = this.editor.editing;
  340. const domConverter = editing.view.domConverter;
  341. const mapper = editing.mapper;
  342. return {
  343. target: () => {
  344. const viewRange = mapper.toViewRange( mentionMarker.getRange() );
  345. const rangeRects = Rect.getDomRangeRects( domConverter.viewRangeToDom( viewRange ) );
  346. return rangeRects.pop();
  347. },
  348. limiter: () => {
  349. const view = this.editor.editing.view;
  350. const viewDocument = view.document;
  351. const editableElement = viewDocument.selection.editableElement;
  352. if ( editableElement ) {
  353. return view.domConverter.mapViewToDom( editableElement.root );
  354. }
  355. return null;
  356. },
  357. positions: getBalloonPanelPositions( positionName ),
  358. fitInViewport: true
  359. };
  360. }
  361. }
  362. // Returns balloon positions data callbacks.
  363. //
  364. // @returns {Array.<module:utils/dom/position~Position>}
  365. function getBalloonPanelPositions( positionName ) {
  366. const positions = {
  367. // Positions panel to the south of caret rect.
  368. 'caret_se': targetRect => {
  369. return {
  370. top: targetRect.bottom + VERTICAL_SPACING,
  371. left: targetRect.right,
  372. name: 'caret_se'
  373. };
  374. },
  375. // Positions panel to the north of caret rect.
  376. 'caret_ne': ( targetRect, balloonRect ) => {
  377. return {
  378. top: targetRect.top - balloonRect.height - VERTICAL_SPACING,
  379. left: targetRect.right,
  380. name: 'caret_ne'
  381. };
  382. },
  383. // Positions panel to the south of caret rect.
  384. 'caret_sw': ( targetRect, balloonRect ) => {
  385. return {
  386. top: targetRect.bottom + VERTICAL_SPACING,
  387. left: targetRect.right - balloonRect.width,
  388. name: 'caret_sw'
  389. };
  390. },
  391. // Positions panel to the north of caret rect.
  392. 'caret_nw': ( targetRect, balloonRect ) => {
  393. return {
  394. top: targetRect.top - balloonRect.height - VERTICAL_SPACING,
  395. left: targetRect.right - balloonRect.width,
  396. name: 'caret_nw'
  397. };
  398. }
  399. };
  400. // Return only last position if it was matched to prevent panel from jumping after first match.
  401. if ( positions.hasOwnProperty( positionName ) ) {
  402. return [
  403. positions[ positionName ]
  404. ];
  405. }
  406. // As default return all positions callbacks.
  407. return [
  408. positions.caret_se,
  409. positions.caret_ne,
  410. positions.caret_sw,
  411. positions.caret_nw
  412. ];
  413. }
  414. // Creates a regex pattern for marker.
  415. //
  416. // @param {String} marker
  417. // @param {Number} minimumCharacters
  418. // @returns {String}
  419. function createPattern( marker, minimumCharacters ) {
  420. const numberOfCharacters = minimumCharacters == 0 ? '*' : `{${ minimumCharacters },}`;
  421. return `(^| )(\\${ marker })([_a-zA-Z0-9À-ž]${ numberOfCharacters }?)$`;
  422. }
  423. // Creates a test callback for marker to be used in text watcher instance.
  424. //
  425. // @param {String} marker
  426. // @param {Number} minimumCharacters
  427. // @returns {Function}
  428. function createTestCallback( marker, minimumCharacters ) {
  429. const regExp = new RegExp( createPattern( marker, minimumCharacters ) );
  430. return text => regExp.test( text );
  431. }
  432. // Creates a text watcher matcher for marker.
  433. //
  434. // @param {String} marker
  435. // @returns {Function}
  436. function createTextMatcher( marker ) {
  437. const regExp = new RegExp( createPattern( marker, 0 ) );
  438. return text => {
  439. const match = text.match( regExp );
  440. const marker = match[ 2 ];
  441. const feedText = match[ 3 ];
  442. return { marker, feedText };
  443. };
  444. }
  445. // Default feed callback
  446. function createFeedCallback( feedItems ) {
  447. return feedText => {
  448. const filteredItems = feedItems
  449. // Make default mention feed case-insensitive.
  450. .filter( item => {
  451. // Item might be defined as object.
  452. const itemId = typeof item == 'string' ? item : String( item.id );
  453. // The default feed is case insensitive.
  454. return itemId.toLowerCase().includes( feedText.toLowerCase() );
  455. } )
  456. // Do not return more than 10 items.
  457. .slice( 0, 10 );
  458. return Promise.resolve( filteredItems );
  459. };
  460. }
  461. // Checks if given key code is handled by the mention ui.
  462. //
  463. // @param {Number}
  464. // @returns {Boolean}
  465. function isHandledKey( keyCode ) {
  466. const handledKeyCodes = [
  467. keyCodes.arrowup,
  468. keyCodes.arrowdown,
  469. keyCodes.enter,
  470. keyCodes.tab,
  471. keyCodes.space,
  472. keyCodes.esc
  473. ];
  474. return handledKeyCodes.includes( keyCode );
  475. }