@ckeditor/ckeditor5-find-and-replace 36.0.0 → 37.0.0-alpha.0

package/src/findandreplacestate.js

@@ -2,130 +2,59 @@
  * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
-/**
- * @module find-and-replace/findandreplacestate
- */
-
-import { ObservableMixin, mix, Collection } from 'ckeditor5/src/utils';
-
+import { ObservableMixin, Collection } from 'ckeditor5/src/utils';
 /**
  * The object storing find and replace plugin state for a given editor instance.
- *
- * @mixes module:utils/observablemixin~ObservableMixin
  */
-export default class FindAndReplaceState {
-	/**
-	 * Creates an instance of the state.
-	 *
-	 * @param {module:engine/model/model~Model} model
-	 */
-	constructor( model ) {
-		/**
-		 * A collection of find matches.
-		 *
-		 * @protected
-		 * @observable
-		 * @member {module:utils/collection~Collection} #results
-		 */
-		this.set( 'results', new Collection() );
-
-		/**
-		 * Currently highlighted search result in {@link #results matched results}.
-		 *
-		 * @readonly
-		 * @observable
-		 * @member {Object|null} #highlightedResult
-		 */
-		this.set( 'highlightedResult', null );
-
-		/**
-		 * Searched text value.
-		 *
-		 * @readonly
-		 * @observable
-		 * @member {String} #searchText
-		 */
-		this.set( 'searchText', '' );
-
-		/**
-		 * Replace text value.
-		 *
-		 * @readonly
-		 * @observable
-		 * @member {String} #replaceText
-		 */
-		this.set( 'replaceText', '' );
-
-		/**
-		 * Indicates whether the matchCase checkbox has been checked.
-		 *
-		 * @readonly
-		 * @observable
-		 * @member {Boolean} #matchCase
-		 */
-		this.set( 'matchCase', false );
-
-		/**
-		 * Indicates whether the matchWholeWords checkbox has been checked.
-		 *
-		 * @readonly
-		 * @observable
-		 * @member {Boolean} #matchWholeWords
-		 */
-		this.set( 'matchWholeWords', false );
-
-		this.results.on( 'change', ( eventInfo, { removed, index } ) => {
-			removed = Array.from( removed );
-
-			if ( removed.length ) {
-				let highlightedResultRemoved = false;
-
-				model.change( writer => {
-					for ( const removedResult of removed ) {
-						if ( this.highlightedResult === removedResult ) {
-							highlightedResultRemoved = true;
-						}
-
-						if ( model.markers.has( removedResult.marker.name ) ) {
-							writer.removeMarker( removedResult.marker );
-						}
-					}
-				} );
-
-				if ( highlightedResultRemoved ) {
-					const nextHighlightedIndex = index >= this.results.length ? 0 : index;
-					this.highlightedResult = this.results.get( nextHighlightedIndex );
-				}
-			}
-		} );
-	}
-
-	/**
-	 * Cleans the state up and removes markers from the model.
-	 *
-	 * @param {module:engine/model/model~Model} model
-	 */
-	clear( model ) {
-		this.searchText = '';
-
-		model.change( writer => {
-			if ( this.highlightedResult ) {
-				const oldMatchId = this.highlightedResult.marker.name.split( ':' )[ 1 ];
-				const oldMarker = model.markers.get( `findResultHighlighted:${ oldMatchId }` );
-
-				if ( oldMarker ) {
-					writer.removeMarker( oldMarker );
-				}
-			}
-
-			[ ...this.results ].forEach( ( { marker } ) => {
-				writer.removeMarker( marker );
-			} );
-		} );
-
-		this.results.clear();
-	}
+export default class FindAndReplaceState extends ObservableMixin() {
+    /**
+     * Creates an instance of the state.
+     */
+    constructor(model) {
+        super();
+        this.set('results', new Collection());
+        this.set('highlightedResult', null);
+        this.set('searchText', '');
+        this.set('replaceText', '');
+        this.set('matchCase', false);
+        this.set('matchWholeWords', false);
+        this.results.on('change', (eventInfo, { removed, index }) => {
+            if (Array.from(removed).length) {
+                let highlightedResultRemoved = false;
+                model.change(writer => {
+                    for (const removedResult of removed) {
+                        if (this.highlightedResult === removedResult) {
+                            highlightedResultRemoved = true;
+                        }
+                        if (model.markers.has(removedResult.marker.name)) {
+                            writer.removeMarker(removedResult.marker);
+                        }
+                    }
+                });
+                if (highlightedResultRemoved) {
+                    const nextHighlightedIndex = index >= this.results.length ? 0 : index;
+                    this.highlightedResult = this.results.get(nextHighlightedIndex);
+                }
+            }
+        });
+    }
+    /**
+     * Cleans the state up and removes markers from the model.
+     */
+    clear(model) {
+        this.searchText = '';
+        model.change(writer => {
+            if (this.highlightedResult) {
+                const oldMatchId = this.highlightedResult.marker.name.split(':')[1];
+                const oldMarker = model.markers.get(`findResultHighlighted:${oldMatchId}`);
+                if (oldMarker) {
+                    writer.removeMarker(oldMarker);
+                }
+            }
+            [...this.results].forEach(({ marker }) => {
+                writer.removeMarker(marker);
+            });
+        });
+        this.results.clear();
+    }
 }
-
-mix( FindAndReplaceState, ObservableMixin );

package/src/findandreplaceui.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module find-and-replace/findandreplaceui
+ */
+import { type Editor, Plugin } from 'ckeditor5/src/core';
+import { type ViewWithCssTransitionDisabler } from 'ckeditor5/src/ui';
+import FindAndReplaceFormView from './ui/findandreplaceformview';
+/**
+ * The default find and replace UI.
+ *
+ * It registers the `'findAndReplace'` UI button in the editor's {@link module:ui/componentfactory~ComponentFactory component factory}.
+ * that uses the {@link module:find-and-replace/findandreplace~FindAndReplace FindAndReplace} plugin API.
+ */
+export default class FindAndReplaceUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'FindAndReplaceUI';
+    /**
+     * A reference to the find and replace form view.
+     */
+    formView: FindAndReplaceFormView & ViewWithCssTransitionDisabler | null;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Sets up the find and replace button.
+     */
+    private _setupDropdownButton;
+    /**
+     * Sets up the form view for the find and replace.
+     *
+     * @param formView A related form view.
+     */
+    private _setupFormView;
+}
+/**
+ * Fired when the UI was reset and the search results marked in the editing root should be invalidated,
+ * for instance, because the user changed the searched phrase (or options) but didn't hit
+ * the "Find" button yet.
+ *
+ * @eventName searchReseted
+ */
+export type SearchResetedEvent = {
+    name: 'searchReseted';
+    args: [];
+};
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [FindAndReplaceUI.pluginName]: FindAndReplaceUI;
+    }
+}

package/src/findandreplaceui.js

@@ -2,205 +2,131 @@
  * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
 /**
  * @module find-and-replace/findandreplaceui
  */
-
 import { Plugin } from 'ckeditor5/src/core';
-import { createDropdown } from 'ckeditor5/src/ui';
+import { createDropdown, CssTransitionDisablerMixin } from 'ckeditor5/src/ui';
 import FindAndReplaceFormView from './ui/findandreplaceformview';
-
 import loupeIcon from '../theme/icons/find-replace.svg';
-
 /**
  * The default find and replace UI.
  *
  * It registers the `'findAndReplace'` UI button in the editor's {@link module:ui/componentfactory~ComponentFactory component factory}.
  * that uses the {@link module:find-and-replace/findandreplace~FindAndReplace FindAndReplace} plugin API.
- *
- * @extends module:core/plugin~Plugin
  */
 export default class FindAndReplaceUI extends Plugin {
-	/**
-	 * @inheritDoc
-	 */
-	static get pluginName() {
-		return 'FindAndReplaceUI';
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	constructor( editor ) {
-		super( editor );
-
-		/**
-		 * A reference to the find and replace form view.
-		 *
-		 * @member {module:find-and-replace/ui/findandreplaceformview~FindAndReplaceFormView} #formView
-		 */
-		this.formView = null;
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	init() {
-		const editor = this.editor;
-
-		// Register the toolbar dropdown component.
-		editor.ui.componentFactory.add( 'findAndReplace', locale => {
-			const dropdown = createDropdown( locale );
-
-			// Dropdown should be disabled when in source editing mode. See #10001.
-			dropdown.bind( 'isEnabled' ).to( editor.commands.get( 'find' ) );
-
-			dropdown.once( 'change:isOpen', () => {
-				this.formView = new FindAndReplaceFormView( editor.locale );
-
-				dropdown.panelView.children.add( this.formView );
-
-				this._setupFormView( this.formView );
-			} );
-
-			// Every time a dropdown is opened, the search text field should get focused and selected for better UX.
-			// Note: Using the low priority here to make sure the following listener starts working after
-			// the default action of the drop-down is executed (i.e. the panel showed up). Otherwise,
-			// the invisible form/input cannot be focused/selected.
-			//
-			// Each time a dropdown is closed, move the focus back to the find and replace toolbar button
-			// and let the find and replace editing feature know that all search results can be invalidated
-			// and no longer should be marked in the content.
-			dropdown.on( 'change:isOpen', ( event, name, isOpen ) => {
-				if ( isOpen ) {
-					this.formView.disableCssTransitions();
-
-					this.formView.reset();
-					this.formView._findInputView.fieldView.select();
-
-					this.formView.enableCssTransitions();
-				} else {
-					this.fire( 'searchReseted' );
-				}
-			}, { priority: 'low' } );
-
-			this._setupDropdownButton( dropdown );
-
-			return dropdown;
-		} );
-	}
-
-	/**
-	 * Sets up the find and replace button.
-	 *
-	 * @private
-	 * @param {module:ui/dropdown/dropdownview~DropdownView} dropdown
-	 */
-	_setupDropdownButton( dropdown ) {
-		const editor = this.editor;
-		const t = editor.locale.t;
-
-		dropdown.buttonView.set( {
-			icon: loupeIcon,
-			label: t( 'Find and replace' ),
-			keystroke: 'CTRL+F',
-			tooltip: true
-		} );
-
-		editor.keystrokes.set( 'Ctrl+F', ( data, cancelEvent ) => {
-			if ( dropdown.isEnabled ) {
-				dropdown.isOpen = true;
-				cancelEvent();
-			}
-		} );
-	}
-
-	/**
-	 * Sets up the form view for the find and replace.
-	 *
-	 * @private
-	 * @param {module:find-and-replace/ui/findandreplaceformview~FindAndReplaceFormView} formView A related form view.
-	 */
-	_setupFormView( formView ) {
-		const editor = this.editor;
-		const commands = editor.commands;
-		const findAndReplaceEditing = this.editor.plugins.get( 'FindAndReplaceEditing' );
-		const editingState = findAndReplaceEditing.state;
-		const sortMapping = { before: -1, same: 0, after: 1 };
-
-		// Let the form know which result is being highlighted.
-		formView.bind( 'highlightOffset' ).to( editingState, 'highlightedResult', highlightedResult => {
-			if ( !highlightedResult ) {
-				return 0;
-			}
-
-			return Array.from( editingState.results )
-				.sort( ( a, b ) => sortMapping[ a.marker.getStart().compareWith( b.marker.getStart() ) ] )
-				.indexOf( highlightedResult ) + 1;
-		} );
-
-		// Let the form know how many results were found in total.
-		formView.listenTo( editingState.results, 'change', () => {
-			formView.matchCount = editingState.results.length;
-		} );
-
-		// Command states are used to enable/disable individual form controls.
-		// To keep things simple, instead of binding 4 individual observables, there's only one that combines every
-		// commands' isEnabled state. Yes, it will change more often but this simplifies the structure of the form.
-		formView.bind( '_areCommandsEnabled' ).to(
-			commands.get( 'findNext' ), 'isEnabled',
-			commands.get( 'findPrevious' ), 'isEnabled',
-			commands.get( 'replace' ), 'isEnabled',
-			commands.get( 'replaceAll' ), 'isEnabled',
-			( findNext, findPrevious, replace, replaceAll ) => ( { findNext, findPrevious, replace, replaceAll } )
-		);
-
-		// The UI plugin works as an interface between the form and the editing part of the feature.
-		formView.delegate( 'findNext', 'findPrevious', 'replace', 'replaceAll' ).to( this );
-
-		// Let the feature know that search results are no longer relevant because the user changed the searched phrase
-		// (or options) but didn't hit the "Find" button yet (e.g. still typing).
-		formView.on( 'change:isDirty', ( evt, data, isDirty ) => {
-			if ( isDirty ) {
-				this.fire( 'searchReseted' );
-			}
-		} );
-	}
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'FindAndReplaceUI';
+    }
+    /**
+     * @inheritDoc
+     */
+    constructor(editor) {
+        super(editor);
+        this.formView = null;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        // Register the toolbar dropdown component.
+        editor.ui.componentFactory.add('findAndReplace', locale => {
+            const dropdown = createDropdown(locale);
+            // Dropdown should be disabled when in source editing mode. See #10001.
+            const findCommand = editor.commands.get('find');
+            dropdown.bind('isEnabled').to(findCommand);
+            dropdown.once('change:isOpen', () => {
+                this.formView = new (CssTransitionDisablerMixin(FindAndReplaceFormView))(editor.locale);
+                dropdown.panelView.children.add(this.formView);
+                this._setupFormView(this.formView);
+            });
+            // Every time a dropdown is opened, the search text field should get focused and selected for better UX.
+            // Note: Using the low priority here to make sure the following listener starts working after
+            // the default action of the drop-down is executed (i.e. the panel showed up). Otherwise,
+            // the invisible form/input cannot be focused/selected.
+            //
+            // Each time a dropdown is closed, move the focus back to the find and replace toolbar button
+            // and let the find and replace editing feature know that all search results can be invalidated
+            // and no longer should be marked in the content.
+            dropdown.on('change:isOpen', (event, name, isOpen) => {
+                if (isOpen) {
+                    this.formView.disableCssTransitions();
+                    this.formView.reset();
+                    this.formView._findInputView.fieldView.select();
+                    this.formView.enableCssTransitions();
+                }
+                else {
+                    this.fire('searchReseted');
+                }
+            }, { priority: 'low' });
+            this._setupDropdownButton(dropdown);
+            return dropdown;
+        });
+    }
+    /**
+     * Sets up the find and replace button.
+     */
+    _setupDropdownButton(dropdown) {
+        const editor = this.editor;
+        const t = editor.locale.t;
+        dropdown.buttonView.set({
+            icon: loupeIcon,
+            label: t('Find and replace'),
+            keystroke: 'CTRL+F',
+            tooltip: true
+        });
+        editor.keystrokes.set('Ctrl+F', (data, cancelEvent) => {
+            if (dropdown.isEnabled) {
+                dropdown.isOpen = true;
+                cancelEvent();
+            }
+        });
+    }
+    /**
+     * Sets up the form view for the find and replace.
+     *
+     * @param formView A related form view.
+     */
+    _setupFormView(formView) {
+        const editor = this.editor;
+        const commands = editor.commands;
+        const findAndReplaceEditing = this.editor.plugins.get('FindAndReplaceEditing');
+        const editingState = findAndReplaceEditing.state;
+        const sortMapping = { before: -1, same: 0, after: 1, different: 1 };
+        // Let the form know which result is being highlighted.
+        formView.bind('highlightOffset').to(editingState, 'highlightedResult', highlightedResult => {
+            if (!highlightedResult) {
+                return 0;
+            }
+            return Array.from(editingState.results)
+                .sort((a, b) => sortMapping[a.marker.getStart().compareWith(b.marker.getStart())])
+                .indexOf(highlightedResult) + 1;
+        });
+        // Let the form know how many results were found in total.
+        formView.listenTo(editingState.results, 'change', () => {
+            formView.matchCount = editingState.results.length;
+        });
+        // Command states are used to enable/disable individual form controls.
+        // To keep things simple, instead of binding 4 individual observables, there's only one that combines every
+        // commands' isEnabled state. Yes, it will change more often but this simplifies the structure of the form.
+        const findNextCommand = commands.get('findNext');
+        const findPreviousCommand = commands.get('findPrevious');
+        const replaceCommand = commands.get('replace');
+        const replaceAllCommand = commands.get('replaceAll');
+        formView.bind('_areCommandsEnabled').to(findNextCommand, 'isEnabled', findPreviousCommand, 'isEnabled', replaceCommand, 'isEnabled', replaceAllCommand, 'isEnabled', (findNext, findPrevious, replace, replaceAll) => ({ findNext, findPrevious, replace, replaceAll }));
+        // The UI plugin works as an interface between the form and the editing part of the feature.
+        formView.delegate('findNext', 'findPrevious', 'replace', 'replaceAll').to(this);
+        // Let the feature know that search results are no longer relevant because the user changed the searched phrase
+        // (or options) but didn't hit the "Find" button yet (e.g. still typing).
+        formView.on('change:isDirty', (evt, data, isDirty) => {
+            if (isDirty) {
+                this.fire('searchReseted');
+            }
+        });
+    }
 }
-
-/**
- * Fired when the find next button is triggered.
- *
- * @event findNext
- * @param {String} searchText Search text.
- */
-
-/**
- * Fired when the find previous button is triggered.
- *
- * @event findPrevious
- * @param {String} searchText Search text.
- */
-
-/**
- * Fired when the replace button is triggered.
- *
- * @event replace
- * @param {String} replaceText Replacement text.
- */
-
-/**
- * Fired when the replaceAll button is triggered.
- *
- * @event replaceAll
- * @param {String} replaceText Replacement text.
- */
-
-/**
- * Fired when the UI was reset and the search results marked in the editing root should be invalidated,
- * for instance, because the user changed the searched phrase (or options) but didn't hit
- * the "Find" button yet.
- *
- * @event searchReseted
- */

package/src/findandreplaceutils.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module find-and-replace/findandreplaceutils
+ */
+import type { Item, Model, Range } from 'ckeditor5/src/engine';
+import { Plugin } from 'ckeditor5/src/core';
+import { Collection } from 'ckeditor5/src/utils';
+import type { ResultType } from './findandreplace';
+/**
+ * A set of helpers related to find and replace.
+ */
+export default class FindAndReplaceUtils extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'FindAndReplaceUtils';
+    /**
+     * Executes findCallback and updates search results list.
+     *
+     * @param range The model range to scan for matches.
+     * @param model The model.
+     * @param findCallback The callback that should return `true` if provided text matches the search term.
+     * @param startResults An optional collection of find matches that the function should
+     * start with. This would be a collection returned by a previous `updateFindResultFromRange()` call.
+     * @returns A collection of objects describing find match.
+     *
+     * An example structure:
+     *
+     * ```js
+     * {
+     *	id: resultId,
+     *	label: foundItem.label,
+     *	marker
+     *	}
+     * ```
+     */
+    updateFindResultFromRange(range: Range, model: Model, findCallback: ({ item, text }: {
+        item: Item;
+        text: string;
+    }) => Array<ResultType>, startResults: Collection<ResultType> | null): Collection<ResultType>;
+    /**
+     * Returns text representation of a range. The returned text length should be the same as range length.
+     * In order to achieve this, this function will replace inline elements (text-line) as new line character ("\n").
+     *
+     * @param range The model range.
+     * @returns The text content of the provided range.
+     */
+    rangeToText(range: Range): string;
+    /**
+     * Creates a text matching callback for a specified search term and matching options.
+     *
+     * @param searchTerm The search term.
+     * @param options Matching options.
+     * 	- options.matchCase=false If set to `true` letter casing will be ignored.
+     * 	- options.wholeWords=false If set to `true` only whole words that match `callbackOrText` will be matched.
+     */
+    findByTextCallback(searchTerm: string, options: {
+        matchCase?: boolean;
+        wholeWords?: boolean;
+    }): ({ item, text }: {
+        item: Item;
+        text: string;
+    }) => Array<ResultType>;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [FindAndReplaceUtils.pluginName]: FindAndReplaceUtils;
+    }
+}