@ckeditor/ckeditor5-find-and-replace 41.2.0 → 41.3.0-alpha.1

package/dist/types/augmentation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @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 type { FindAndReplace, FindAndReplaceEditing, FindAndReplaceUI, FindAndReplaceUtils, FindCommand, FindNextCommand, FindPreviousCommand, ReplaceAllCommand, ReplaceCommand } from './index.js';
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [FindAndReplace.pluginName]: FindAndReplace;
+        [FindAndReplaceEditing.pluginName]: FindAndReplaceEditing;
+        [FindAndReplaceUI.pluginName]: FindAndReplaceUI;
+        [FindAndReplaceUtils.pluginName]: FindAndReplaceUtils;
+    }
+    interface CommandsMap {
+        find: FindCommand;
+        findNext: FindNextCommand;
+        findPrevious: FindPreviousCommand;
+        replace: ReplaceCommand;
+        replaceAll: ReplaceAllCommand;
+    }
+}

package/dist/types/findandreplace.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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/findandreplace
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import FindAndReplaceUI from './findandreplaceui.js';
+import FindAndReplaceEditing from './findandreplaceediting.js';
+import type { Marker } from 'ckeditor5/src/engine.js';
+export type ResultType = {
+    id?: string;
+    label?: string;
+    start?: number;
+    end?: number;
+    marker?: Marker;
+};
+/**
+ * The find and replace plugin.
+ *
+ * For a detailed overview, check the {@glink features/find-and-replace Find and replace feature documentation}.
+ *
+ * This is a "glue" plugin which loads the following plugins:
+ *
+ * * The {@link module:find-and-replace/findandreplaceediting~FindAndReplaceEditing find and replace editing feature},
+ * * The {@link module:find-and-replace/findandreplaceui~FindAndReplaceUI find and replace UI feature}
+ */
+export default class FindAndReplace extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof FindAndReplaceEditing, typeof FindAndReplaceUI];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "FindAndReplace";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/findandreplaceconfig.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @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/findandreplaceconfig
+ */
+/**
+ * The configuration of the find and replace feature.
+ * The option is used by the {@link module:find-and-replace/findandreplace~FindAndReplace} feature.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( {
+ *     findAndReplace: ... // Find and replace feature config.
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface FindAndReplaceConfig {
+    /**
+     * The type of the find and replace UI opened by the `'findAndReplace'` button registered in the
+     * editor's {@link module:ui/componentfactory~ComponentFactory component factory}
+     *
+     * The default value is `'dialog'`.
+     */
+    uiType?: 'dialog' | 'dropdown';
+}

package/dist/types/findandreplaceediting.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @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 { type Collection } from 'ckeditor5/src/utils.js';
+import { type FindAttributes } from './findcommand.js';
+import FindAndReplaceState, { type FindCallback } from './findandreplacestate.js';
+import FindAndReplaceUtils from './findandreplaceutils.js';
+import type { ResultType } from './findandreplace.js';
+import '../theme/findandreplace.css';
+/**
+ * Implements the editing part for find and replace plugin. For example conversion, commands etc.
+ */
+export default class FindAndReplaceEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof FindAndReplaceUtils];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "FindAndReplaceEditing";
+    /**
+     * An object storing the find and replace state within a given editor instance.
+     */
+    state?: FindAndReplaceState;
+    /**
+     * A flag that indicates that the user has started a search and the editor is listening for changes
+     * to the text on which it will perform an automatic search. Among other things, the mode is activated
+     * when the user first clicks 'Find' button and then later deactivated when the modal or search dropdown is closed.
+     *
+     * @internal
+     */
+    _isSearchActive: boolean;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Initiate a search.
+     */
+    find(callbackOrText: string | FindCallback, findAttributes?: FindAttributes): Collection<ResultType>;
+    /**
+     * Stops active results from updating, and clears out the results.
+     */
+    stop(): void;
+    /**
+     * Sets up the commands.
+     */
+    private _defineCommands;
+    /**
+     * Sets up the marker downcast converters for search results highlighting.
+     */
+    private _defineConverters;
+    /**
+     * Reacts to document changes in order to update search list.
+     */
+    private _onDocumentChange;
+}

package/dist/types/findandreplacestate.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @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 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;
+}) => Array<ResultType>);
+export {};

package/dist/types/findandreplaceui.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @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";
+    /**
+     * 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 _createDialogButton;
+    /**
+     * 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: [];
+};

package/dist/types/findandreplaceutils.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @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/findandreplaceutils
+ */
+import type { Item, Model, Range } from 'ckeditor5/src/engine.js';
+import { Plugin } from 'ckeditor5/src/core.js';
+import { Collection } from 'ckeditor5/src/utils.js';
+import type { ResultType } from './findandreplace.js';
+/**
+ * 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>;
+}

package/dist/types/findcommand.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @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/findcommand
+*/
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+import type { Collection } from 'ckeditor5/src/utils.js';
+import type { default as FindAndReplaceState, FindCallback } from './findandreplacestate.js';
+import type { ResultType } from './findandreplace.js';
+/**
+ * The find command. It is used by the {@link module:find-and-replace/findandreplace~FindAndReplace find and replace feature}.
+ */
+export default class FindCommand extends Command {
+    /**
+     * The find and replace state object used for command operations.
+     */
+    private _state;
+    /**
+     * Creates a new `FindCommand` instance.
+     *
+     * @param editor The editor on which this command will be used.
+     * @param state An object to hold plugin state.
+     */
+    constructor(editor: Editor, state: FindAndReplaceState);
+    /**
+     * Executes the command.
+     *
+     * @param callbackOrText
+     * @param options Options object.
+     * @param options.matchCase If set to `true`, the letter case will be matched.
+     * @param options.wholeWords If set to `true`, only whole words that match `callbackOrText` will be matched.
+     *
+     * @fires execute
+     */
+    execute(callbackOrText: string | FindCallback, { matchCase, wholeWords }?: FindAttributes): {
+        results: Collection<ResultType>;
+        findCallback: FindCallback;
+    };
+}
+/**
+ * The options object for the find command.
+ */
+export type FindAttributes = {
+    matchCase?: boolean;
+    wholeWords?: boolean;
+};

package/dist/types/findnextcommand.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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/findnextcommand
+*/
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+import type FindAndReplaceState from './findandreplacestate.js';
+/**
+ * The find next command. Moves the highlight to the next search result.
+ *
+ * It is used by the {@link module:find-and-replace/findandreplace~FindAndReplace find and replace feature}.
+ */
+export default class FindNextCommand extends Command {
+    /**
+     * The find and replace state object used for command operations.
+     */
+    protected _state: FindAndReplaceState;
+    /**
+     * Creates a new `FindNextCommand` instance.
+     *
+     * @param editor The editor on which this command will be used.
+     * @param state An object to hold plugin state.
+     */
+    constructor(editor: Editor, state: FindAndReplaceState);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * @inheritDoc
+     */
+    execute(): void;
+}

package/dist/types/findpreviouscommand.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @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/findpreviouscommand
+*/
+import FindNextCommand from './findnextcommand.js';
+/**
+ * The find previous command. Moves the highlight to the previous search result.
+ *
+ * It is used by the {@link module:find-and-replace/findandreplace~FindAndReplace find and replace feature}.
+ */
+export default class FindPreviousCommand extends FindNextCommand {
+    /**
+     * @inheritDoc
+     */
+    execute(): void;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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
+ */
+export { default as FindAndReplace } from './findandreplace.js';
+export { default as FindAndReplaceEditing } from './findandreplaceediting.js';
+export { default as FindAndReplaceUI } from './findandreplaceui.js';
+export { default as FindAndReplaceUtils } from './findandreplaceutils.js';
+export { default as FindCommand } from './findcommand.js';
+export { default as FindNextCommand } from './findnextcommand.js';
+export { default as FindPreviousCommand } from './findpreviouscommand.js';
+export { default as ReplaceCommand } from './replacecommand.js';
+export { default as ReplaceAllCommand } from './replaceallcommand.js';
+export type { FindAndReplaceConfig } from './findandreplaceconfig.js';
+import './augmentation.js';

package/dist/types/replaceallcommand.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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/replaceallcommand
+ */
+import { Collection } from 'ckeditor5/src/utils.js';
+import type { ResultType } from './findandreplace.js';
+import { ReplaceCommandBase } from './replacecommandbase.js';
+/**
+ * The replace all command. It is used by the {@link module:find-and-replace/findandreplace~FindAndReplace find and replace feature}.
+ */
+export default class ReplaceAllCommand extends ReplaceCommandBase {
+    /**
+     * Replaces all the occurrences of `textToReplace` with a given `newText` string.
+     *
+     * ```ts
+     *	replaceAllCommand.execute( 'replaceAll', 'new text replacement', 'text to replace' );
+     * ```
+     *
+     * Alternatively you can call it from editor instance:
+     *
+     * ```ts
+     *	editor.execute( 'replaceAll', 'new text', 'old text' );
+     * ```
+     *
+     * @param newText Text that will be inserted to the editor for each match.
+     * @param textToReplace Text to be replaced or a collection of matches
+     * as returned by the find command.
+     *
+     * @fires module:core/command~Command#event:execute
+     */
+    execute(newText: string, textToReplace: string | Collection<ResultType>): void;
+}

package/dist/types/replacecommand.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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/replacecommand
+*/
+import type { ResultType } from './findandreplace.js';
+import { ReplaceCommandBase } from './replacecommandbase.js';
+/**
+ * The replace command. It is used by the {@link module:find-and-replace/findandreplace~FindAndReplace find and replace feature}.
+ */
+export default class ReplaceCommand extends ReplaceCommandBase {
+    /**
+     * Replace a given find result by a string or a callback.
+     *
+     * @param result A single result from the find command.
+     *
+     * @fires execute
+     */
+    execute(replacementText: string, result: ResultType): void;
+}

package/dist/types/replacecommandbase.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @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/replacecommandbase
+*/
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+import type { ResultType } from './findandreplace.js';
+import type FindAndReplaceState from './findandreplacestate.js';
+export declare abstract class ReplaceCommandBase extends Command {
+    /**
+     * The find and replace state object used for command operations.
+     */
+    protected _state: FindAndReplaceState;
+    /**
+     * Creates a new `ReplaceCommand` instance.
+     *
+     * @param editor Editor on which this command will be used.
+     * @param state An object to hold plugin state.
+     */
+    constructor(editor: Editor, state: FindAndReplaceState);
+    abstract execute(...args: Array<unknown>): void;
+    /**
+     * Common logic for both `replace` commands.
+     * Replace a given find result by a string or a callback.
+     *
+     * @param result A single result from the find command.
+     */
+    protected _replace(replacementText: string, result: ResultType): void;
+}