@ckeditor/ckeditor5-typing 0.0.0-internal-20241017.0

package/dist/input.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @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 typing/input
+ */
+import { Plugin } from '@ckeditor/ckeditor5-core';
+/**
+ * Handles text input coming from the keyboard or other input methods.
+ */
+export default class Input extends Plugin {
+    /**
+     * The queue of `insertText` command executions that are waiting for the DOM to get updated after beforeinput event.
+     */
+    private _compositionQueue;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "Input";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}

package/dist/inserttextcommand.d.ts

@@ -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
+ */
+/**
+ * @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 typing/inserttextcommand
+ */
+import { Command, type Editor } from '@ckeditor/ckeditor5-core';
+import ChangeBuffer from './utils/changebuffer.js';
+import type { DocumentSelection, Range, Selection } from '@ckeditor/ckeditor5-engine';
+/**
+ * The insert text command. Used by the {@link module:typing/input~Input input feature} to handle typing.
+ */
+export default class InsertTextCommand extends Command {
+    /**
+     * Typing's change buffer used to group subsequent changes into batches.
+     */
+    private readonly _buffer;
+    /**
+     * Creates an instance of the command.
+     *
+     * @param undoStepSize The maximum number of atomic changes
+     * which can be contained in one batch in the command buffer.
+     */
+    constructor(editor: Editor, undoStepSize: number);
+    /**
+     * The current change buffer.
+     */
+    get buffer(): ChangeBuffer;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Executes the input command. It replaces the content within the given range with the given text.
+     * Replacing is a two step process, first the content within the range is removed and then the new text is inserted
+     * at the beginning of the range (which after the removal is a collapsed range).
+     *
+     * @fires execute
+     * @param options The command options.
+     */
+    execute(options?: InsertTextCommandOptions): void;
+}
+/**
+ * Interface with parameters for executing InsertTextCommand.
+ *
+ * Both `range` and `selection` parameters are used for defining selection but should not be used together.
+ * If both are defined, only `selection` will be considered.
+ */
+export interface InsertTextCommandOptions {
+    /**
+     * The text to be inserted.
+     */
+    text?: string;
+    /**
+     * The selection in which the text is inserted.
+     * Inserting a text into a selection deletes the current content within selection ranges. If the selection is not specified,
+     * the current selection in the model will be used instead.
+     */
+    selection?: Selection | DocumentSelection;
+    /**
+     * The range in which the text is inserted. Defaults to the first range in the current selection.
+     */
+    range?: Range;
+    /**
+     * The range where the selection should be placed after the insertion.
+     * If not specified, the selection will be placed right after the inserted text.
+     */
+    resultRange?: Range;
+}
+export interface InsertTextCommandExecuteEvent {
+    name: 'execute';
+    args: [
+        data: [options: InsertTextCommandOptions]
+    ];
+}

package/dist/inserttextobserver.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @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
+ */
+import { DomEventData, Observer, FocusObserver, type EditingView, type ViewDocumentSelection, type ViewSelection } from '@ckeditor/ckeditor5-engine';
+/**
+ * Text insertion observer introduces the {@link module:engine/view/document~Document#event:insertText} event.
+ */
+export default class InsertTextObserver extends Observer {
+    /**
+     * Instance of the focus observer. Insert text observer calls
+     * {@link module:engine/view/observer/focusobserver~FocusObserver#flush} to mark the latest focus change as complete.
+     */
+    readonly focusObserver: FocusObserver;
+    /**
+     * @inheritDoc
+     */
+    constructor(view: EditingView);
+    /**
+     * @inheritDoc
+     */
+    observe(): void;
+    /**
+     * @inheritDoc
+     */
+    stopObserving(): void;
+}
+/**
+ * Event fired when the user types text, for instance presses <kbd>A</kbd> or <kbd>?</kbd> in the
+ * editing view document.
+ *
+ * **Note**: This event will **not** fire for keystrokes such as <kbd>Delete</kbd> or <kbd>Enter</kbd>.
+ * They have dedicated events, see {@link module:engine/view/document~Document#event:delete} and
+ * {@link module:engine/view/document~Document#event:enter} to learn more.
+ *
+ * **Note**: This event is fired by the {@link module:typing/inserttextobserver~InsertTextObserver input feature}.
+ *
+ * @eventName module:engine/view/document~Document#insertText
+ * @param data The event data.
+ */
+export type ViewDocumentInsertTextEvent = {
+    name: 'insertText';
+    args: [data: InsertTextEventData];
+};
+export interface InsertTextEventData extends DomEventData {
+    /**
+     *  The text to be inserted.
+     */
+    text: string;
+    /**
+     * The selection into which the text should be inserted.
+     * If not specified, the insertion should occur at the current view selection.
+     */
+    selection?: ViewSelection | ViewDocumentSelection;
+}

package/dist/texttransformation.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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 typing/texttransformation
+ */
+import { Plugin, type Editor } from '@ckeditor/ckeditor5-core';
+/**
+ * The text transformation plugin.
+ */
+export default class TextTransformation extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly ["Delete", "Input"];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TextTransformation";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Create new TextWatcher listening to the editor for typing and selection events.
+     */
+    private _enableTransformationWatchers;
+}

package/dist/textwatcher.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @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
+ */
+import type { Batch, Model, Range } from '@ckeditor/ckeditor5-engine';
+declare const TextWatcher_base: {
+    new (): import("@ckeditor/ckeditor5-utils").Observable;
+    prototype: import("@ckeditor/ckeditor5-utils").Observable;
+};
+/**
+ * The text watcher feature.
+ *
+ * Fires the {@link module:typing/textwatcher~TextWatcher#event:matched:data `matched:data`},
+ * {@link module:typing/textwatcher~TextWatcher#event:matched:selection `matched:selection`} and
+ * {@link module:typing/textwatcher~TextWatcher#event:unmatched `unmatched`} events on typing or selection changes.
+ */
+export default class TextWatcher extends /* #__PURE__ */ TextWatcher_base {
+    /**
+     * The editor's model.
+     */
+    readonly model: Model;
+    /**
+     * The function used to match the text.
+     *
+     * The test callback can return 3 values:
+     *
+     * * `false` if there is no match,
+     * * `true` if there is a match,
+     * * an object if there is a match and we want to pass some additional information to the {@link #event:matched:data} event.
+     */
+    testCallback: (text: string) => unknown;
+    /**
+     * Whether there is a match currently.
+     */
+    private _hasMatch;
+    /**
+     * Flag indicating whether the `TextWatcher` instance is enabled or disabled.
+     * A disabled TextWatcher will not evaluate text.
+     *
+     * To disable TextWatcher:
+     *
+     * ```ts
+     * const watcher = new TextWatcher( editor.model, testCallback );
+     *
+     * // After this a testCallback will not be called.
+     * watcher.isEnabled = false;
+     * ```
+     */
+    isEnabled: boolean;
+    /**
+     * Creates a text watcher instance.
+     *
+     * @param testCallback See {@link module:typing/textwatcher~TextWatcher#testCallback}.
+     */
+    constructor(model: Model, testCallback: (text: string) => unknown);
+    /**
+     * Flag indicating whether there is a match currently.
+     */
+    get hasMatch(): boolean;
+    /**
+     * Starts listening to the editor for typing and selection events.
+     */
+    private _startListening;
+    /**
+     * Checks the editor content for matched text.
+     *
+     * @fires matched:data
+     * @fires matched:selection
+     * @fires unmatched
+     *
+     * @param suffix A suffix used for generating the event name.
+     * @param data Data object for event.
+     */
+    private _evaluateTextBeforeSelection;
+}
+export type TextWatcherMatchedEvent<TCallbackResult extends Record<string, unknown> = Record<string, unknown>> = {
+    name: 'matched' | 'matched:data' | 'matched:selection';
+    args: [
+        {
+            text: string;
+            range: Range;
+            batch?: Batch;
+        } & TCallbackResult
+    ];
+};
+/**
+ * Fired whenever the text watcher found a match for data changes.
+ *
+ * @eventName ~TextWatcher#matched:data
+ * @param data Event data.
+ * @param data.testResult The additional data returned from the {@link module:typing/textwatcher~TextWatcher#testCallback}.
+ */
+export type TextWatcherMatchedDataEvent<TCallbackResult extends Record<string, unknown>> = {
+    name: 'matched:data';
+    args: [data: TextWatcherMatchedDataEventData & TCallbackResult];
+};
+export interface TextWatcherMatchedDataEventData {
+    /**
+     * The full text before selection to which the regexp was applied.
+     */
+    text: string;
+    /**
+     * The range representing the position of the `data.text`.
+     */
+    range: Range;
+    batch: Batch;
+}
+/**
+ * Fired whenever the text watcher found a match for selection changes.
+ *
+ * @eventName ~TextWatcher#matched:selection
+ * @param data Event data.
+ * @param data.testResult The additional data returned from the {@link module:typing/textwatcher~TextWatcher#testCallback}.
+ */
+export type TextWatcherMatchedSelectionEvent<TCallbackResult extends Record<string, unknown>> = {
+    name: 'matched:selection';
+    args: [data: TextWatcherMatchedSelectionEventData & TCallbackResult];
+};
+export interface TextWatcherMatchedSelectionEventData {
+    /**
+     * The full text before selection.
+     */
+    text: string;
+    /**
+     * The range representing the position of the `data.text`.
+     */
+    range: Range;
+}
+/**
+ * Fired whenever the text does not match anymore. Fired only when the text watcher found a match.
+ *
+ * @eventName ~TextWatcher#unmatched
+ */
+export type TextWatcherUnmatchedEvent = {
+    name: 'unmatched';
+    args: [];
+};
+export {};

package/dist/twostepcaretmovement.d.ts

@@ -0,0 +1,240 @@
+/**
+ * @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 typing/twostepcaretmovement
+ */
+import { Plugin, type Editor } from '@ckeditor/ckeditor5-core';
+/**
+ * This plugin enables the two-step caret (phantom) movement behavior for
+ * {@link module:typing/twostepcaretmovement~TwoStepCaretMovement#registerAttribute registered attributes}
+ * on arrow right (<kbd>→</kbd>) and left (<kbd>←</kbd>) key press.
+ *
+ * Thanks to this (phantom) caret movement the user is able to type before/after as well as at the
+ * beginning/end of an attribute.
+ *
+ * **Note:** This plugin support right–to–left (Arabic, Hebrew, etc.) content by mirroring its behavior
+ * but for the sake of simplicity examples showcase only left–to–right use–cases.
+ *
+ * # Forward movement
+ *
+ * ## "Entering" an attribute:
+ *
+ * When this plugin is enabled and registered for the `a` attribute and the selection is right before it
+ * (at the attribute boundary), pressing the right arrow key will not move the selection but update its
+ * attributes accordingly:
+ *
+ * * When enabled:
+ *
+ * ```xml
+ * foo{}<$text a="true">bar</$text>
+ * ```
+ *
+ * 	<kbd>→</kbd>
+ *
+ * ```xml
+ * foo<$text a="true">{}bar</$text>
+ * ```
+ *
+ * * When disabled:
+ *
+ * ```xml
+ * foo{}<$text a="true">bar</$text>
+ * ```
+ *
+ * 	<kbd>→</kbd>
+ *
+ * ```xml
+ * foo<$text a="true">b{}ar</$text>
+ * ```
+ *
+ *
+ * ## "Leaving" an attribute:
+ *
+ * * When enabled:
+ *
+ * ```xml
+ * <$text a="true">bar{}</$text>baz
+ * ```
+ *
+ * 	<kbd>→</kbd>
+ *
+ * ```xml
+ * <$text a="true">bar</$text>{}baz
+ * ```
+ *
+ * * When disabled:
+ *
+ * ```xml
+ * <$text a="true">bar{}</$text>baz
+ * ```
+ *
+ * 	<kbd>→</kbd>
+ *
+ * ```xml
+ * <$text a="true">bar</$text>b{}az
+ * ```
+ *
+ * # Backward movement
+ *
+ * * When enabled:
+ *
+ * ```xml
+ * <$text a="true">bar</$text>{}baz
+ * ```
+ *
+ * 	<kbd>←</kbd>
+ *
+ * ```xml
+ * <$text a="true">bar{}</$text>baz
+ * ```
+ *
+ * * When disabled:
+ *
+ * ```xml
+ * <$text a="true">bar</$text>{}baz
+ * ```
+ *
+ * 	<kbd>←</kbd>
+ *
+ * ```xml
+ * <$text a="true">ba{}r</$text>b{}az
+ * ```
+ *
+ * # Multiple attributes
+ *
+ * * When enabled and many attributes starts or ends at the same position:
+ *
+ * ```xml
+ * <$text a="true" b="true">bar</$text>{}baz
+ * ```
+ *
+ * 	<kbd>←</kbd>
+ *
+ * ```xml
+ * <$text a="true" b="true">bar{}</$text>baz
+ * ```
+ *
+ * * When enabled and one procedes another:
+ *
+ * ```xml
+ * <$text a="true">bar</$text><$text b="true">{}bar</$text>
+ * ```
+ *
+ * 	<kbd>←</kbd>
+ *
+ * ```xml
+ * <$text a="true">bar{}</$text><$text b="true">bar</$text>
+ * ```
+ *
+ */
+export default class TwoStepCaretMovement extends Plugin {
+    /**
+     * A set of attributes to handle.
+     */
+    private attributes;
+    /**
+     * The current UID of the overridden gravity, as returned by
+     * {@link module:engine/model/writer~Writer#overrideSelectionGravity}.
+     */
+    private _overrideUid;
+    /**
+     * A flag indicating that the automatic gravity restoration should not happen upon the next
+     * gravity restoration.
+     * {@link module:engine/model/selection~Selection#event:change:range} event.
+     */
+    private _isNextGravityRestorationSkipped;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "TwoStepCaretMovement";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Registers a given attribute for the two-step caret movement.
+     *
+     * @param attribute Name of the attribute to handle.
+     */
+    registerAttribute(attribute: string): void;
+    /**
+     * Updates the document selection and the view according to the two–step caret movement state
+     * when moving **forwards**. Executed upon `keypress` in the {@link module:engine/view/view~View}.
+     *
+     * @param data Data of the key press.
+     * @returns `true` when the handler prevented caret movement.
+     */
+    private _handleForwardMovement;
+    /**
+     * Updates the document selection and the view according to the two–step caret movement state
+     * when moving **backwards**. Executed upon `keypress` in the {@link module:engine/view/view~View}.
+     *
+     * @param data Data of the key press.
+     * @returns `true` when the handler prevented caret movement
+     */
+    private _handleBackwardMovement;
+    /**
+     * Starts listening to {@link module:engine/view/document~Document#event:mousedown} and
+     * {@link module:engine/view/document~Document#event:selectionChange} and puts the selection before/after a 2-step node
+     * if clicked at the beginning/ending of the 2-step node.
+     *
+     * The purpose of this action is to allow typing around the 2-step node directly after a click.
+     *
+     * See https://github.com/ckeditor/ckeditor5/issues/1016.
+     */
+    private _enableClickingAfterNode;
+    /**
+     * Starts listening to {@link module:engine/model/model~Model#event:insertContent} and corrects the model
+     * selection attributes if the selection is at the end of a two-step node after inserting the content.
+     *
+     * The purpose of this action is to improve the overall UX because the user is no longer "trapped" by the
+     * two-step attribute of the selection, and they can type a "clean" (`linkHref`–less) text right away.
+     *
+     * See https://github.com/ckeditor/ckeditor5/issues/6053.
+     */
+    private _enableInsertContentSelectionAttributesFixer;
+    /**
+     * Starts listening to {@link module:engine/model/model~Model#deleteContent} and checks whether
+     * removing a content right after the tow-step attribute.
+     *
+     * If so, the selection should not preserve the two-step attribute. However, if
+     * the {@link module:typing/twostepcaretmovement~TwoStepCaretMovement} plugin is active and
+     * the selection has the two-step attribute due to overridden gravity (at the end), the two-step attribute should stay untouched.
+     *
+     * The purpose of this action is to allow removing the link text and keep the selection outside the link.
+     *
+     * See https://github.com/ckeditor/ckeditor5/issues/7521.
+     */
+    private _handleDeleteContentAfterNode;
+    /**
+     * `true` when the gravity is overridden for the plugin.
+     */
+    private get _isGravityOverridden();
+    /**
+     * Overrides the gravity using the {@link module:engine/model/writer~Writer model writer}
+     * and stores the information about this fact in the {@link #_overrideUid}.
+     *
+     * A shorthand for {@link module:engine/model/writer~Writer#overrideSelectionGravity}.
+     */
+    private _overrideGravity;
+    /**
+     * Restores the gravity using the {@link module:engine/model/writer~Writer model writer}.
+     *
+     * A shorthand for {@link module:engine/model/writer~Writer#restoreSelectionGravity}.
+     */
+    private _restoreGravity;
+}

package/dist/typing.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
+ */
+/**
+ * @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 typing/typing
+ */
+import { Plugin } from '@ckeditor/ckeditor5-core';
+import Input from './input.js';
+import Delete from './delete.js';
+/**
+ * The typing feature. It handles typing.
+ *
+ * This is a "glue" plugin which loads the {@link module:typing/input~Input} and {@link module:typing/delete~Delete}
+ * plugins.
+ */
+export default class Typing extends Plugin {
+    static get requires(): readonly [typeof Input, typeof Delete];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "Typing";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+}