@ckeditor/ckeditor5-find-and-replace 41.3.0 → 41.4.0-alpha.0

package/dist/types/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
+ */
+/**
+ * @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 _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: [];
+};

package/dist/types/findandreplaceutils.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @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
+ */
+/**
+ * @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,52 @@
+/**
+ * @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
+ */
+/**
+ * @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,39 @@
+/**
+ * @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
+ */
+/**
+ * @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,23 @@
+/**
+ * @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
+ */
+/**
+ * @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,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
+ */
+/**
+ * @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,39 @@
+/**
+ * @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
+ */
+/**
+ * @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,26 @@
+/**
+ * @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
+ */
+/**
+ * @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,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
+ */
+/**
+ * @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;
+}