@ckeditor/ckeditor5-autoformat 40.0.0 → 40.2.0

package/src/blockautoformatediting.js

@@ -1,137 +1,137 @@
-/**
- * @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
- */
-import { LiveRange } from 'ckeditor5/src/engine';
-import { first } from 'ckeditor5/src/utils';
-/**
- * The block autoformatting engine. It allows to format various block patterns. For example,
- * it can be configured to turn a paragraph starting with `*` and followed by a space into a list item.
- *
- * The autoformatting operation is integrated with the undo manager,
- * so the autoformatting step can be undone if the user's intention was not to format the text.
- *
- * See the {@link module:autoformat/blockautoformatediting~blockAutoformatEditing `blockAutoformatEditing`} documentation
- * to learn how to create custom block autoformatters. You can also use
- * the {@link module:autoformat/autoformat~Autoformat} feature which enables a set of default autoformatters
- * (lists, headings, bold and italic).
- *
- * @module autoformat/blockautoformatediting
- */
-/**
- * Creates a listener triggered on {@link module:engine/model/document~Document#event:change:data `change:data`} event in the document.
- * Calls the callback when inserted text matches the regular expression or the command name
- * if provided instead of the callback.
- *
- * Examples of usage:
- *
- * To convert a paragraph into heading 1 when `- ` is typed, using just the command name:
- *
- * ```ts
- * blockAutoformatEditing( editor, plugin, /^\- $/, 'heading1' );
- * ```
- *
- * To convert a paragraph into heading 1 when `- ` is typed, using just the callback:
- *
- * ```ts
- * blockAutoformatEditing( editor, plugin, /^\- $/, ( context ) => {
- * 	const { match } = context;
- * 	const headingLevel = match[ 1 ].length;
- *
- * 	editor.execute( 'heading', {
- * 		formatId: `heading${ headingLevel }`
- * 	} );
- * } );
- * ```
- *
- * @param editor The editor instance.
- * @param plugin The autoformat plugin instance.
- * @param pattern The regular expression to execute on just inserted text. The regular expression is tested against the text
- * from the beginning until the caret position.
- * @param callbackOrCommand The callback to execute or the command to run when the text is matched.
- * In case of providing the callback, it receives the following parameter:
- * * match RegExp.exec() result of matching the pattern to inserted text.
- */
-export default function blockAutoformatEditing(editor, plugin, pattern, callbackOrCommand) {
-    let callback;
-    let command = null;
-    if (typeof callbackOrCommand == 'function') {
-        callback = callbackOrCommand;
-    }
-    else {
-        // We assume that the actual command name was provided.
-        command = editor.commands.get(callbackOrCommand);
-        callback = () => {
-            editor.execute(callbackOrCommand);
-        };
-    }
-    editor.model.document.on('change:data', (evt, batch) => {
-        if (command && !command.isEnabled || !plugin.isEnabled) {
-            return;
-        }
-        const range = first(editor.model.document.selection.getRanges());
-        if (!range.isCollapsed) {
-            return;
-        }
-        if (batch.isUndo || !batch.isLocal) {
-            return;
-        }
-        const changes = Array.from(editor.model.document.differ.getChanges());
-        const entry = changes[0];
-        // Typing is represented by only a single change.
-        if (changes.length != 1 || entry.type !== 'insert' || entry.name != '$text' || entry.length != 1) {
-            return;
-        }
-        const blockToFormat = entry.position.parent;
-        // Block formatting should be disabled in codeBlocks (#5800).
-        if (blockToFormat.is('element', 'codeBlock')) {
-            return;
-        }
-        // Only list commands and custom callbacks can be applied inside a list.
-        if (blockToFormat.is('element', 'listItem') &&
-            typeof callbackOrCommand !== 'function' &&
-            !['numberedList', 'bulletedList', 'todoList'].includes(callbackOrCommand)) {
-            return;
-        }
-        // In case a command is bound, do not re-execute it over an existing block style which would result in a style removal.
-        // Instead, just drop processing so that autoformat trigger text is not lost. E.g. writing "# " in a level 1 heading.
-        if (command && command.value === true) {
-            return;
-        }
-        const firstNode = blockToFormat.getChild(0);
-        const firstNodeRange = editor.model.createRangeOn(firstNode);
-        // Range is only expected to be within or at the very end of the first text node.
-        if (!firstNodeRange.containsRange(range) && !range.end.isEqual(firstNodeRange.end)) {
-            return;
-        }
-        const match = pattern.exec(firstNode.data.substr(0, range.end.offset));
-        // ...and this text node's data match the pattern.
-        if (!match) {
-            return;
-        }
-        // Use enqueueChange to create new batch to separate typing batch from the auto-format changes.
-        editor.model.enqueueChange(writer => {
-            // Matched range.
-            const start = writer.createPositionAt(blockToFormat, 0);
-            const end = writer.createPositionAt(blockToFormat, match[0].length);
-            const range = new LiveRange(start, end);
-            const wasChanged = callback({ match });
-            // Remove matched text.
-            if (wasChanged !== false) {
-                writer.remove(range);
-                const selectionRange = editor.model.document.selection.getFirstRange();
-                const blockRange = writer.createRangeIn(blockToFormat);
-                // If the block is empty and the document selection has been moved when
-                // applying formatting (e.g. is now in newly created block).
-                if (blockToFormat.isEmpty && !blockRange.isEqual(selectionRange) && !blockRange.containsRange(selectionRange, true)) {
-                    writer.remove(blockToFormat);
-                }
-            }
-            range.detach();
-            editor.model.enqueueChange(() => {
-                const deletePlugin = editor.plugins.get('Delete');
-                deletePlugin.requestUndoOnBackspace();
-            });
-        });
-    });
-}
+/**
+ * @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
+ */
+import { LiveRange } from 'ckeditor5/src/engine';
+import { first } from 'ckeditor5/src/utils';
+/**
+ * The block autoformatting engine. It allows to format various block patterns. For example,
+ * it can be configured to turn a paragraph starting with `*` and followed by a space into a list item.
+ *
+ * The autoformatting operation is integrated with the undo manager,
+ * so the autoformatting step can be undone if the user's intention was not to format the text.
+ *
+ * See the {@link module:autoformat/blockautoformatediting~blockAutoformatEditing `blockAutoformatEditing`} documentation
+ * to learn how to create custom block autoformatters. You can also use
+ * the {@link module:autoformat/autoformat~Autoformat} feature which enables a set of default autoformatters
+ * (lists, headings, bold and italic).
+ *
+ * @module autoformat/blockautoformatediting
+ */
+/**
+ * Creates a listener triggered on {@link module:engine/model/document~Document#event:change:data `change:data`} event in the document.
+ * Calls the callback when inserted text matches the regular expression or the command name
+ * if provided instead of the callback.
+ *
+ * Examples of usage:
+ *
+ * To convert a paragraph into heading 1 when `- ` is typed, using just the command name:
+ *
+ * ```ts
+ * blockAutoformatEditing( editor, plugin, /^\- $/, 'heading1' );
+ * ```
+ *
+ * To convert a paragraph into heading 1 when `- ` is typed, using just the callback:
+ *
+ * ```ts
+ * blockAutoformatEditing( editor, plugin, /^\- $/, ( context ) => {
+ * 	const { match } = context;
+ * 	const headingLevel = match[ 1 ].length;
+ *
+ * 	editor.execute( 'heading', {
+ * 		formatId: `heading${ headingLevel }`
+ * 	} );
+ * } );
+ * ```
+ *
+ * @param editor The editor instance.
+ * @param plugin The autoformat plugin instance.
+ * @param pattern The regular expression to execute on just inserted text. The regular expression is tested against the text
+ * from the beginning until the caret position.
+ * @param callbackOrCommand The callback to execute or the command to run when the text is matched.
+ * In case of providing the callback, it receives the following parameter:
+ * * match RegExp.exec() result of matching the pattern to inserted text.
+ */
+export default function blockAutoformatEditing(editor, plugin, pattern, callbackOrCommand) {
+    let callback;
+    let command = null;
+    if (typeof callbackOrCommand == 'function') {
+        callback = callbackOrCommand;
+    }
+    else {
+        // We assume that the actual command name was provided.
+        command = editor.commands.get(callbackOrCommand);
+        callback = () => {
+            editor.execute(callbackOrCommand);
+        };
+    }
+    editor.model.document.on('change:data', (evt, batch) => {
+        if (command && !command.isEnabled || !plugin.isEnabled) {
+            return;
+        }
+        const range = first(editor.model.document.selection.getRanges());
+        if (!range.isCollapsed) {
+            return;
+        }
+        if (batch.isUndo || !batch.isLocal) {
+            return;
+        }
+        const changes = Array.from(editor.model.document.differ.getChanges());
+        const entry = changes[0];
+        // Typing is represented by only a single change.
+        if (changes.length != 1 || entry.type !== 'insert' || entry.name != '$text' || entry.length != 1) {
+            return;
+        }
+        const blockToFormat = entry.position.parent;
+        // Block formatting should be disabled in codeBlocks (#5800).
+        if (blockToFormat.is('element', 'codeBlock')) {
+            return;
+        }
+        // Only list commands and custom callbacks can be applied inside a list.
+        if (blockToFormat.is('element', 'listItem') &&
+            typeof callbackOrCommand !== 'function' &&
+            !['numberedList', 'bulletedList', 'todoList'].includes(callbackOrCommand)) {
+            return;
+        }
+        // In case a command is bound, do not re-execute it over an existing block style which would result in a style removal.
+        // Instead, just drop processing so that autoformat trigger text is not lost. E.g. writing "# " in a level 1 heading.
+        if (command && command.value === true) {
+            return;
+        }
+        const firstNode = blockToFormat.getChild(0);
+        const firstNodeRange = editor.model.createRangeOn(firstNode);
+        // Range is only expected to be within or at the very end of the first text node.
+        if (!firstNodeRange.containsRange(range) && !range.end.isEqual(firstNodeRange.end)) {
+            return;
+        }
+        const match = pattern.exec(firstNode.data.substr(0, range.end.offset));
+        // ...and this text node's data match the pattern.
+        if (!match) {
+            return;
+        }
+        // Use enqueueChange to create new batch to separate typing batch from the auto-format changes.
+        editor.model.enqueueChange(writer => {
+            // Matched range.
+            const start = writer.createPositionAt(blockToFormat, 0);
+            const end = writer.createPositionAt(blockToFormat, match[0].length);
+            const range = new LiveRange(start, end);
+            const wasChanged = callback({ match });
+            // Remove matched text.
+            if (wasChanged !== false) {
+                writer.remove(range);
+                const selectionRange = editor.model.document.selection.getFirstRange();
+                const blockRange = writer.createRangeIn(blockToFormat);
+                // If the block is empty and the document selection has been moved when
+                // applying formatting (e.g. is now in newly created block).
+                if (blockToFormat.isEmpty && !blockRange.isEqual(selectionRange) && !blockRange.containsRange(selectionRange, true)) {
+                    writer.remove(blockToFormat);
+                }
+            }
+            range.detach();
+            editor.model.enqueueChange(() => {
+                const deletePlugin = editor.plugins.get('Delete');
+                deletePlugin.requestUndoOnBackspace();
+            });
+        });
+    });
+}

package/src/index.d.ts

@@ -1,9 +1,9 @@
-/**
- * @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 autoformat
- */
-export { default as Autoformat } from './autoformat';
-import './augmentation';
+/**
+ * @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 autoformat
+ */
+export { default as Autoformat } from './autoformat';
+import './augmentation';

package/src/index.js

@@ -1,9 +1,9 @@
-/**
- * @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 autoformat
- */
-export { default as Autoformat } from './autoformat';
-import './augmentation';
+/**
+ * @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 autoformat
+ */
+export { default as Autoformat } from './autoformat';
+import './augmentation';

package/src/inlineautoformatediting.d.ts

@@ -1,83 +1,83 @@
-/**
- * @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
- */
-/**
- * The inline autoformatting engine. It allows to format various inline patterns. For example,
- * it can be configured to make "foo" bold when typed `**foo**` (the `**` markers will be removed).
- *
- * The autoformatting operation is integrated with the undo manager,
- * so the autoformatting step can be undone if the user's intention was not to format the text.
- *
- * See the {@link module:autoformat/inlineautoformatediting~inlineAutoformatEditing `inlineAutoformatEditing`} documentation
- * to learn how to create custom inline autoformatters. You can also use
- * the {@link module:autoformat/autoformat~Autoformat} feature which enables a set of default autoformatters
- * (lists, headings, bold and italic).
- *
- * @module autoformat/inlineautoformatediting
- */
-import type { Editor } from 'ckeditor5/src/core';
-import type { Range, Writer } from 'ckeditor5/src/engine';
-import type Autoformat from './autoformat';
-export type TestCallback = (text: string) => {
-    remove: Array<Array<number>>;
-    format: Array<Array<number>>;
-};
-/**
- * Enables autoformatting mechanism for a given {@link module:core/editor/editor~Editor}.
- *
- * It formats the matched text by applying the given model attribute or by running the provided formatting callback.
- * On every {@link module:engine/model/document~Document#event:change:data data change} in the model document
- * the autoformatting engine checks the text on the left of the selection
- * and executes the provided action if the text matches given criteria (regular expression or callback).
- *
- * @param editor The editor instance.
- * @param plugin The autoformat plugin instance.
- * @param testRegexpOrCallback The regular expression or callback to execute on text.
- * Provided regular expression *must* have three capture groups. The first and the third capture group
- * should match opening and closing delimiters. The second capture group should match the text to format.
- *
- * ```ts
- * // Matches the `**bold text**` pattern.
- * // There are three capturing groups:
- * // - The first to match the starting `**` delimiter.
- * // - The second to match the text to format.
- * // - The third to match the ending `**` delimiter.
- * inlineAutoformatEditing( editor, plugin, /(\*\*)([^\*]+?)(\*\*)$/g, formatCallback );
- * ```
- *
- * When a function is provided instead of the regular expression, it will be executed with the text to match as a parameter.
- * The function should return proper "ranges" to delete and format.
- *
- * ```ts
- * {
- * 	remove: [
- * 		[ 0, 1 ],	// Remove the first letter from the given text.
- * 		[ 5, 6 ]	// Remove the 6th letter from the given text.
- * 	],
- * 	format: [
- * 		[ 1, 5 ]	// Format all letters from 2nd to 5th.
- * 	]
- * }
- * ```
- *
- * @param formatCallback A callback to apply actual formatting.
- * It should return `false` if changes should not be applied (e.g. if a command is disabled).
- *
- * ```ts
- * inlineAutoformatEditing( editor, plugin, /(\*\*)([^\*]+?)(\*\*)$/g, ( writer, rangesToFormat ) => {
- * 	const command = editor.commands.get( 'bold' );
- *
- * 	if ( !command.isEnabled ) {
- * 		return false;
- * 	}
- *
- * 	const validRanges = editor.model.schema.getValidRanges( rangesToFormat, 'bold' );
- *
- * 	for ( let range of validRanges ) {
- * 		writer.setAttribute( 'bold', true, range );
- * 	}
- * } );
- * ```
- */
-export default function inlineAutoformatEditing(editor: Editor, plugin: Autoformat, testRegexpOrCallback: RegExp | TestCallback, formatCallback: (writer: Writer, rangesToFormat: Array<Range>) => boolean | undefined): void;
+/**
+ * @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
+ */
+/**
+ * The inline autoformatting engine. It allows to format various inline patterns. For example,
+ * it can be configured to make "foo" bold when typed `**foo**` (the `**` markers will be removed).
+ *
+ * The autoformatting operation is integrated with the undo manager,
+ * so the autoformatting step can be undone if the user's intention was not to format the text.
+ *
+ * See the {@link module:autoformat/inlineautoformatediting~inlineAutoformatEditing `inlineAutoformatEditing`} documentation
+ * to learn how to create custom inline autoformatters. You can also use
+ * the {@link module:autoformat/autoformat~Autoformat} feature which enables a set of default autoformatters
+ * (lists, headings, bold and italic).
+ *
+ * @module autoformat/inlineautoformatediting
+ */
+import type { Editor } from 'ckeditor5/src/core';
+import type { Range, Writer } from 'ckeditor5/src/engine';
+import type Autoformat from './autoformat';
+export type TestCallback = (text: string) => {
+    remove: Array<Array<number>>;
+    format: Array<Array<number>>;
+};
+/**
+ * Enables autoformatting mechanism for a given {@link module:core/editor/editor~Editor}.
+ *
+ * It formats the matched text by applying the given model attribute or by running the provided formatting callback.
+ * On every {@link module:engine/model/document~Document#event:change:data data change} in the model document
+ * the autoformatting engine checks the text on the left of the selection
+ * and executes the provided action if the text matches given criteria (regular expression or callback).
+ *
+ * @param editor The editor instance.
+ * @param plugin The autoformat plugin instance.
+ * @param testRegexpOrCallback The regular expression or callback to execute on text.
+ * Provided regular expression *must* have three capture groups. The first and the third capture group
+ * should match opening and closing delimiters. The second capture group should match the text to format.
+ *
+ * ```ts
+ * // Matches the `**bold text**` pattern.
+ * // There are three capturing groups:
+ * // - The first to match the starting `**` delimiter.
+ * // - The second to match the text to format.
+ * // - The third to match the ending `**` delimiter.
+ * inlineAutoformatEditing( editor, plugin, /(\*\*)([^\*]+?)(\*\*)$/g, formatCallback );
+ * ```
+ *
+ * When a function is provided instead of the regular expression, it will be executed with the text to match as a parameter.
+ * The function should return proper "ranges" to delete and format.
+ *
+ * ```ts
+ * {
+ * 	remove: [
+ * 		[ 0, 1 ],	// Remove the first letter from the given text.
+ * 		[ 5, 6 ]	// Remove the 6th letter from the given text.
+ * 	],
+ * 	format: [
+ * 		[ 1, 5 ]	// Format all letters from 2nd to 5th.
+ * 	]
+ * }
+ * ```
+ *
+ * @param formatCallback A callback to apply actual formatting.
+ * It should return `false` if changes should not be applied (e.g. if a command is disabled).
+ *
+ * ```ts
+ * inlineAutoformatEditing( editor, plugin, /(\*\*)([^\*]+?)(\*\*)$/g, ( writer, rangesToFormat ) => {
+ * 	const command = editor.commands.get( 'bold' );
+ *
+ * 	if ( !command.isEnabled ) {
+ * 		return false;
+ * 	}
+ *
+ * 	const validRanges = editor.model.schema.getValidRanges( rangesToFormat, 'bold' );
+ *
+ * 	for ( let range of validRanges ) {
+ * 		writer.setAttribute( 'bold', true, range );
+ * 	}
+ * } );
+ * ```
+ */
+export default function inlineAutoformatEditing(editor: Editor, plugin: Autoformat, testRegexpOrCallback: RegExp | TestCallback, formatCallback: (writer: Writer, rangesToFormat: Array<Range>) => boolean | undefined): void;