@ckeditor/ckeditor5-find-and-replace 0.0.0-internal-20241017.0

package/src/findandreplaceediting.js

@@ -0,0 +1,233 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/findandreplaceediting
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { scrollViewportToShowTarget } from 'ckeditor5/src/utils.js';
+import FindCommand from './findcommand.js';
+import ReplaceCommand from './replacecommand.js';
+import ReplaceAllCommand from './replaceallcommand.js';
+import FindNextCommand from './findnextcommand.js';
+import FindPreviousCommand from './findpreviouscommand.js';
+import FindAndReplaceState from './findandreplacestate.js';
+import FindAndReplaceUtils from './findandreplaceutils.js';
+import { debounce } from 'lodash-es';
+import '../theme/findandreplace.css';
+const HIGHLIGHT_CLASS = 'ck-find-result_selected';
+/**
+ * Implements the editing part for find and replace plugin. For example conversion, commands etc.
+ */
+export default class FindAndReplaceEditing extends Plugin {
+    constructor() {
+        super(...arguments);
+        /**
+         * Reacts to document changes in order to update search list.
+         */
+        this._onDocumentChange = () => {
+            const changedNodes = new Set();
+            const removedMarkers = new Set();
+            const model = this.editor.model;
+            const { results } = this.state;
+            const changes = model.document.differ.getChanges();
+            const changedMarkers = model.document.differ.getChangedMarkers();
+            // Get nodes in which changes happened to re-run a search callback on them.
+            changes.forEach(change => {
+                if (!change.position) {
+                    return;
+                }
+                if (change.name === '$text' || (change.position.nodeAfter && model.schema.isInline(change.position.nodeAfter))) {
+                    changedNodes.add(change.position.parent);
+                    [...model.markers.getMarkersAtPosition(change.position)].forEach(markerAtChange => {
+                        removedMarkers.add(markerAtChange.name);
+                    });
+                }
+                else if (change.type === 'insert' && change.position.nodeAfter) {
+                    changedNodes.add(change.position.nodeAfter);
+                }
+            });
+            // Get markers from removed nodes also.
+            changedMarkers.forEach(({ name, data: { newRange } }) => {
+                if (newRange && newRange.start.root.rootName === '$graveyard') {
+                    removedMarkers.add(name);
+                }
+            });
+            // Get markers from the updated nodes and remove all (search will be re-run on these nodes).
+            changedNodes.forEach(node => {
+                const markersInNode = [...model.markers.getMarkersIntersectingRange(model.createRangeIn(node))];
+                markersInNode.forEach(marker => removedMarkers.add(marker.name));
+            });
+            // Remove results from the changed part of content.
+            removedMarkers.forEach(markerName => {
+                if (!results.has(markerName)) {
+                    return;
+                }
+                if (results.get(markerName) === this.state.highlightedResult) {
+                    this.state.highlightedResult = null;
+                }
+                results.remove(markerName);
+            });
+            // Run search callback again on updated nodes.
+            const changedSearchResults = [];
+            const findAndReplaceUtils = this.editor.plugins.get('FindAndReplaceUtils');
+            changedNodes.forEach(nodeToCheck => {
+                const changedNodeSearchResults = findAndReplaceUtils.updateFindResultFromRange(model.createRangeOn(nodeToCheck), model, this.state.lastSearchCallback, results);
+                changedSearchResults.push(...changedNodeSearchResults);
+            });
+            changedMarkers.forEach(markerToCheck => {
+                // Handle search result highlight update when T&C plugin is active.
+                // Lookup is performed only on newly inserted markers.
+                if (markerToCheck.data.newRange) {
+                    const changedNodeSearchResults = findAndReplaceUtils.updateFindResultFromRange(markerToCheck.data.newRange, model, this.state.lastSearchCallback, results);
+                    changedSearchResults.push(...changedNodeSearchResults);
+                }
+            });
+            if (!this.state.highlightedResult && changedSearchResults.length) {
+                // If there are found phrases but none is selected, select the first one.
+                this.state.highlightedResult = changedSearchResults[0];
+            }
+            else {
+                // If there is already highlight item then refresh highlight offset after appending new items.
+                this.state.refreshHighlightOffset();
+            }
+        };
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [FindAndReplaceUtils];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'FindAndReplaceEditing';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        this.state = new FindAndReplaceState(this.editor.model);
+        this.set('_isSearchActive', false);
+        this._defineConverters();
+        this._defineCommands();
+        this.listenTo(this.state, 'change:highlightedResult', (eventInfo, name, newValue, oldValue) => {
+            const { model } = this.editor;
+            model.change(writer => {
+                if (oldValue) {
+                    const oldMatchId = oldValue.marker.name.split(':')[1];
+                    const oldMarker = model.markers.get(`findResultHighlighted:${oldMatchId}`);
+                    if (oldMarker) {
+                        writer.removeMarker(oldMarker);
+                    }
+                }
+                if (newValue) {
+                    const newMatchId = newValue.marker.name.split(':')[1];
+                    writer.addMarker(`findResultHighlighted:${newMatchId}`, {
+                        usingOperation: false,
+                        affectsData: false,
+                        range: newValue.marker.getRange()
+                    });
+                }
+            });
+        });
+        /* istanbul ignore next -- @preserve */
+        const scrollToHighlightedResult = (eventInfo, name, newValue) => {
+            if (newValue) {
+                const domConverter = this.editor.editing.view.domConverter;
+                const viewRange = this.editor.editing.mapper.toViewRange(newValue.marker.getRange());
+                scrollViewportToShowTarget({
+                    target: domConverter.viewRangeToDom(viewRange),
+                    viewportOffset: 40
+                });
+            }
+        };
+        const debouncedScrollListener = debounce(scrollToHighlightedResult.bind(this), 32);
+        // Debounce scroll as highlight might be changed very frequently, e.g. when there's a replace all command.
+        this.listenTo(this.state, 'change:highlightedResult', debouncedScrollListener, { priority: 'low' });
+        // It's possible that the editor will get destroyed before debounced call kicks in.
+        // This would result with accessing a view three that is no longer in DOM.
+        this.listenTo(this.editor, 'destroy', debouncedScrollListener.cancel);
+        this.on('change:_isSearchActive', (evt, name, isSearchActive) => {
+            if (isSearchActive) {
+                this.listenTo(this.editor.model.document, 'change:data', this._onDocumentChange);
+            }
+            else {
+                this.stopListening(this.editor.model.document, 'change:data', this._onDocumentChange);
+            }
+        });
+    }
+    /**
+     * Initiate a search.
+     */
+    find(callbackOrText, findAttributes) {
+        this._isSearchActive = true;
+        this.editor.execute('find', callbackOrText, findAttributes);
+        return this.state.results;
+    }
+    /**
+     * Stops active results from updating, and clears out the results.
+     */
+    stop() {
+        this.state.clear(this.editor.model);
+        this._isSearchActive = false;
+    }
+    /**
+     * Sets up the commands.
+     */
+    _defineCommands() {
+        this.editor.commands.add('find', new FindCommand(this.editor, this.state));
+        this.editor.commands.add('findNext', new FindNextCommand(this.editor, this.state));
+        this.editor.commands.add('findPrevious', new FindPreviousCommand(this.editor, this.state));
+        this.editor.commands.add('replace', new ReplaceCommand(this.editor, this.state));
+        this.editor.commands.add('replaceAll', new ReplaceAllCommand(this.editor, this.state));
+    }
+    /**
+     * Sets up the marker downcast converters for search results highlighting.
+     */
+    _defineConverters() {
+        const { editor } = this;
+        // Setup the marker highlighting conversion.
+        editor.conversion.for('editingDowncast').markerToHighlight({
+            model: 'findResult',
+            view: ({ markerName }) => {
+                const [, id] = markerName.split(':');
+                // Marker removal from the view has a bug: https://github.com/ckeditor/ckeditor5/issues/7499
+                // A minimal option is to return a new object for each converted marker...
+                return {
+                    name: 'span',
+                    classes: ['ck-find-result'],
+                    attributes: {
+                        // ...however, adding a unique attribute should be future-proof..
+                        'data-find-result': id
+                    }
+                };
+            }
+        });
+        editor.conversion.for('editingDowncast').markerToHighlight({
+            model: 'findResultHighlighted',
+            view: ({ markerName }) => {
+                const [, id] = markerName.split(':');
+                // Marker removal from the view has a bug: https://github.com/ckeditor/ckeditor5/issues/7499
+                // A minimal option is to return a new object for each converted marker...
+                return {
+                    name: 'span',
+                    classes: [HIGHLIGHT_CLASS],
+                    attributes: {
+                        // ...however, adding a unique attribute should be future-proof..
+                        'data-find-result': id
+                    }
+                };
+            }
+        });
+    }
+}

package/src/findandreplacestate.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @license Copyright (c) 2003-2024, 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 type { Model, Item } from 'ckeditor5/src/engine.js';
+import { Collection } from 'ckeditor5/src/utils.js';
+import type { ResultType } from './findandreplace.js';
+declare const FindAndReplaceState_base: {
+    new (): import("ckeditor5/src/utils.js").Observable;
+    prototype: import("ckeditor5/src/utils.js").Observable;
+};
+/**
+ * The object storing find and replace plugin state for a given editor instance.
+ */
+export default class FindAndReplaceState extends /* #__PURE__ */ FindAndReplaceState_base {
+    /**
+     * A collection of find matches.
+     *
+     * @observable
+     */
+    results: Collection<ResultType>;
+    /**
+     * Currently highlighted search result in {@link #results matched results}.
+     *
+     * @readonly
+     * @observable
+     */
+    highlightedResult: ResultType | null;
+    /**
+     * Currently highlighted search result offset in {@link #results matched results}.
+     *
+     * @readonly
+     * @observable
+     */
+    highlightedOffset: number;
+    /**
+     * Searched text value.
+     *
+     * @readonly
+     * @observable
+     */
+    searchText: string;
+    /**
+     *  The most recent search callback used by the feature to find matches.
+     *  It is used to re-run the search when user modifies the editor content.
+     *
+     * @readonly
+     * @observable
+     */
+    lastSearchCallback: FindCallback | null;
+    /**
+     * Replace text value.
+     *
+     * @readonly
+     * @observable
+     */
+    replaceText: string;
+    /**
+     * Indicates whether the matchCase checkbox has been checked.
+     *
+     * @readonly
+     * @observable
+     */
+    matchCase: boolean;
+    /**
+     * Indicates whether the matchWholeWords checkbox has been checked.
+     *
+     * @readonly
+     * @observable
+     */
+    matchWholeWords: boolean;
+    /**
+     * Creates an instance of the state.
+     */
+    constructor(model: Model);
+    /**
+     * Cleans the state up and removes markers from the model.
+     */
+    clear(model: Model): void;
+    /**
+     * Refreshes the highlight result offset based on it's index within the result list.
+     */
+    refreshHighlightOffset(): void;
+}
+/**
+ * The callback function used to find matches in the document.
+ */
+export type FindCallback = ({ item, text }: {
+    item: Item;
+    text: string;
+}) => FindCallbackResultObject | FindCallbackResult;
+/**
+ * Represents the result of a find callback.
+ *
+ * The `searchText` attribute in the result object is used to determine if the search text has changed.
+ * If returned `searchText` is different than the last search text, the search results will be invalidated
+ * while searching for next item and the search will start from the beginning of the document.
+ */
+export type FindCallbackResultObject = {
+    results: Array<ResultType>;
+    searchText: string;
+};
+/**
+ * Represents the result of a find callback.
+ *
+ * @deprecated Use `FindCallbackResultObject` instead.
+ */
+export type FindCallbackResult = Array<ResultType>;
+export {};

package/src/findandreplacestate.js

@@ -0,0 +1,80 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { ObservableMixin, Collection } from 'ckeditor5/src/utils.js';
+/**
+ * The object storing find and replace plugin state for a given editor instance.
+ */
+export default class FindAndReplaceState extends /* #__PURE__ */ ObservableMixin() {
+    /**
+     * Creates an instance of the state.
+     */
+    constructor(model) {
+        super();
+        this.set('results', new Collection());
+        this.set('highlightedResult', null);
+        this.set('highlightedOffset', 0);
+        this.set('searchText', '');
+        this.set('replaceText', '');
+        this.set('lastSearchCallback', null);
+        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);
+                }
+            }
+        });
+        this.on('change:highlightedResult', () => {
+            this.refreshHighlightOffset();
+        });
+    }
+    /**
+     * 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();
+    }
+    /**
+     * Refreshes the highlight result offset based on it's index within the result list.
+     */
+    refreshHighlightOffset() {
+        const { highlightedResult, results } = this;
+        const sortMapping = { before: -1, same: 0, after: 1, different: 1 };
+        if (highlightedResult) {
+            this.highlightedOffset = Array.from(results)
+                .sort((a, b) => sortMapping[a.marker.getStart().compareWith(b.marker.getStart())])
+                .indexOf(highlightedResult) + 1;
+        }
+        else {
+            this.highlightedOffset = 0;
+        }
+    }
+}

package/src/findandreplaceui.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+import { Dialog, type ViewWithCssTransitionDisabler } from 'ckeditor5/src/ui.js';
+import FindAndReplaceFormView from './ui/findandreplaceformview.js';
+/**
+ * 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 requires(): readonly [typeof Dialog];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "FindAndReplaceUI";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * A reference to the find and replace form view.
+     */
+    formView: FindAndReplaceFormView & ViewWithCssTransitionDisabler | null;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Creates a dropdown containing the find and replace form.
+     */
+    private _createDropdown;
+    /**
+     * Creates a button that opens a dialog with the find and replace form.
+     */
+    private _createDialogButtonForToolbar;
+    /**
+     * Creates a button for for menu bar that will show find and replace dialog.
+     */
+    private _createDialogButtonForMenuBar;
+    /**
+     * Creates a button for find and replace command to use either in toolbar or in menu bar.
+     */
+    private _createButton;
+    /**
+     * Shows the find and replace dialog.
+     */
+    private _showDialog;
+    /**
+     * Sets up the form view for the find and replace.
+     *
+     * @param formView A related form view.
+     */
+    private _createFormView;
+    /**
+     * Clears the find and replace form and focuses the search text field.
+     */
+    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 ~FindAndReplaceUI#searchReseted
+ */
+export type SearchResetedEvent = {
+    name: 'searchReseted';
+    args: [];
+};