Piotrek Koszuliński 9 anni fa
parent
commit
8fb087a66c

+ 33 - 4
packages/ckeditor5-autoformat/src/autoformat.js

@@ -12,10 +12,36 @@ import BoldEngine from '../basic-styles/boldengine.js';
 import ItalicEngine from '../basic-styles/italicengine.js';
 
 /**
- * Includes set of predefined Autoformatting actions:
- * * Bulleted list,
- * * Numbered list,
- * * Headings.
+ * Includes a set of predefined autoformatting actions.
+ *
+ * ## Bulleted list
+ *
+ * You can create a bulleted list by staring a line with:
+ *
+ * * `* `
+ * * `- `
+ *
+ * ## Numbered list
+ *
+ * You can create a numbered list by staring a line with:
+ *
+ * * `1. `
+ * * `1) `
+ *
+ * ## Headings
+ *
+ * You can create a heading by starting a line with:
+ *
+ * `# ` – will create Heading 1,
+ * `## ` – will create Heading 2,
+ * `### ` – will create Heading 3.
+ *
+ * ## Bold and italic
+ *
+ * You can apply bold or italic to a text by typing Markdown formatting:
+ *
+ * * `**foo bar**` or `__foo bar__` – will bold the text,
+ * * `*foo bar*` or `_foo bar_` – will italicize the text,
  *
  * @memberOf autoformat
  * @extends core.Feature
@@ -83,6 +109,9 @@ export default class Autoformat extends Feature {
 	_addInlineAutoformats() {
 		new InlineAutoformatEngine( this.editor, /(\*\*)([^\*]+)(\*\*)$/g, 'bold' );
 		new InlineAutoformatEngine( this.editor, /(__)([^_]+)(__)$/g, 'bold' );
+
+		// The italic autoformatter cannot be triggered by the bold markers, so we need to check the
+		// text before the pattern (e.g. `(?:^|[^\*])`).
 		new InlineAutoformatEngine( this.editor, /(?:^|[^\*])(\*)([^\*_]+)(\*)$/g, 'italic' );
 		new InlineAutoformatEngine( this.editor, /(?:^|[^_])(_)([^_]+)(_)$/g, 'italic' );
 	}

+ 16 - 4
packages/ckeditor5-autoformat/src/blockautoformatengine.js

@@ -6,7 +6,19 @@
 import Range from '../engine/model/range.js';
 import TextProxy from '../engine/model/textproxy.js';
 
-export default class AutoformatEngine {
+/**
+ * The block autoformatting engine. Allows to format various block patterns. For example,
+ * it can be configured to make a paragraph starting with "* " a list item.
+ *
+ * The autoformatting operation is integrated with the undo manager,
+ * so the autoformatting step can be undone, if the user's intention wasn't to format the text.
+ *
+ * See the constructors documentation to learn how to create custom inline autoformatters. You can also use
+ * the {@link autoformat.Autoformat} feature which enables a set of default autoformatters (lists, headings, bold and italic).
+ *
+ * @memberOf autoformat
+ */
+export default class BlockAutoformatEngine {
 	/**
 	 * Creates listener triggered on `change` event in document.
 	 * Calls callback when inserted text matches regular expression or command name
@@ -16,11 +28,11 @@ export default class AutoformatEngine {
 	 *
 	 * To convert paragraph to heading1 when `- ` is typed, using just commmand name:
 	 *
-	 *		createAutoformat( editor, /^\- $/, 'heading1');
+	 *		new BlockAutoformatEngine( editor, /^\- $/, 'heading1' );
 	 *
 	 * To convert paragraph to heading1 when `- ` is typed, using just callback:
 	 *
-	 *		createAutoformat( editor, /^\- $/, ( context ) => {
+	 *		new BlockAutoformatEngine( editor, /^\- $/, ( context ) => {
 	 *			const { batch, match } = context;
 	 *			const headingLevel = match[ 1 ].length;
 	 *
@@ -31,7 +43,7 @@ export default class AutoformatEngine {
 	 * 		} );
 	 *
 	 * @param {core.editor.Editor} editor Editor instance.
-	 * @param {Regex} pattern Regular expression to exec on just inserted text.
+	 * @param {RegExp} pattern Regular expression to exec on just inserted text.
 	 * @param {Function|String} callbackOrCommand Callback to execute or command to run when text is matched.
 	 * In case of providing callback it receives following parameters:
 	 * * {engine.model.Batch} batch Newly created batch for autoformat changes.

+ 17 - 10
packages/ckeditor5-autoformat/src/inlineautoformatengine.js

@@ -7,18 +7,22 @@ import LiveRange from '../engine/model/liverange.js';
 import getSchemaValidRanges from '../core/command/helpers/getschemavalidranges.js';
 
 /**
- * A paragraph feature for editor.
- * Introduces `<paragraph>` element in the model which renders as `<p>` in the DOM and data.
+ * The inline autoformatting engine. Allows to format various inline patterns. For example,
+ * it can be configured to make "foo" bold when typed `**foo**` (the `**` markers will be removed).
  *
- * @memberOf paragraph
- * @extends ckeditor5.Feature
+ * The autoformatting operation is integrated with the undo manager,
+ * so the autoformatting step can be undone, if the user's intention wasn't to format the text.
+ *
+ * See the constructors documentation to learn how to create custom inline autoformatters. You can also use
+ * the {@link autoformat.Autoformat} feature which enables a set of default autoformatters (lists, headings, bold and italic).
+ *
+ * @memberOf autoformat
  */
 export default class InlineAutoformatEngine {
 	/**
+	 * Enables autoformatting mechanism on a given {@link core.editor.Editor}.
 	 *
-	 * Enables mechanism on given {@link core.editor.Editor} instance to watch for specified pattern (either by executing
-	 * given RegExp or by passing the text to provided callback).
-	 * It formats found text by applying proper attribute or by running provided formatting callback.
+	 * It formats the matched text by applying given model attribute or by running the provided formatting callback.
 	 * Each time data model changes text from given node (from the beginning of the current node to the collapsed
 	 * selection location) will be tested.
 	 *
@@ -28,7 +32,7 @@ export default class InlineAutoformatEngine {
 	 * should match opening/closing delimiters. Second capture group should match text to format.
 	 *
 	 *		// Matches `**bold text**` pattern.
-	 *		// There are three matching groups:
+	 *		// There are three capturing groups:
 	 *		// - first to match starting `**` delimiter,
 	 *		// - second to match text to format,
 	 *		// - third to match ending `**` delimiter.
@@ -39,8 +43,8 @@ export default class InlineAutoformatEngine {
 	 *
 	 *		{
 	 *			remove: [
-	 *				[ 0, 1 ],	// Remove first letter from given text.
-	 *				[ 5, 6 ]	// Remove 6th letter from given text.
+	 *				[ 0, 1 ],	// Remove first letter from the given text.
+	 *				[ 5, 6 ]	// Remove 6th letter from the given text.
 	 *			],
 	 *			format: [
 	 *				[ 1, 5 ]	// Format all letters from 2nd to 5th.
@@ -153,6 +157,7 @@ export default class InlineAutoformatEngine {
 				if ( range[ 0 ] === undefined || range[ 1 ] === undefined ) {
 					return;
 				}
+
 				rangesToFormat.push( LiveRange.createFromParentsAndOffsets(
 					block, range[ 0 ],
 					block, range[ 1 ]
@@ -160,6 +165,7 @@ export default class InlineAutoformatEngine {
 			} );
 
 			const rangesToRemove = [];
+
 			// Reverse order to not mix the offsets while removing.
 			ranges.remove.slice().reverse().forEach( ( range ) => {
 				if ( range[ 0 ] === undefined || range[ 1 ] === undefined ) {
@@ -177,6 +183,7 @@ export default class InlineAutoformatEngine {
 			}
 
 			const batch = editor.document.batch();
+
 			editor.document.enqueueChanges( () => {
 				const validRanges = getSchemaValidRanges( command, rangesToFormat, editor.document.schema );