Merge pull request #15959 from ckeditor/ck/15834

Feature (engine): `Schema#addChildCheck()` and `Schema#addAttributeCheck()` can now register a callback for a specific item or attribute, which should improve performance when using custom callback checks. Callback checks should be added only for specific item or attribute if possible. See the API reference. Closes #15834.

Fix (engine): `Schema#checkChild()` will now correctly check custom callback checks for each item in the context.

Other (engine): Introduced `Schema#trimLast()`.

Internal: Used specific callback checks in some of the features.

Docs (engine): Improved schema deep dive guide and added missing section related to attributes custom callback checks.

MINOR BREAKING CHANGE: `Schema` callbacks added through `addChildCheck()` will no longer add event listeners with `high` priority and will no longer stop `checkChild` event. Instead, these callbacks are now handled on `normal` priority, as a part of the default `checkChild()` call. This also means that listeners added to `checkChild` event on `high` priority will fire before any callbacks added by `checkChild()`. Earlier they would fire in registration order. This may impact you if you implemented custom schema callback using both `addChildCheck()` and direct listener to `checkChild` event. All above is also true for `addAttributeCheck()` and `checkAttribute` event and callbacks.

packages/ckeditor5-ckbox/src/ckboxediting.ts

@@ -140,13 +140,12 @@ export default class CKBoxEditing extends Plugin {
 			schema.extend( 'imageInline', { allowAttributes: [ 'ckboxImageId', 'ckboxLinkId' ] } );
 		}
 
-		schema.addAttributeCheck( ( context, attributeName ) => {
-			const isLink = !!context.last.getAttribute( 'linkHref' );
-
-			if ( !isLink && attributeName === 'ckboxLinkId' ) {
+		schema.addAttributeCheck( context => {
+			// Don't allow `ckboxLinkId` on elements which do not have `linkHref` attribute.
+			if ( !context.last.getAttribute( 'linkHref' ) ) {
 				return false;
 			}
-		} );
+		}, 'ckboxLinkId' );
 	}
 
 	/**

packages/ckeditor5-engine/docs/framework/deep-dive/schema.md

@@ -675,31 +675,88 @@ Which, in turn, has these [semantics](#defining-additional-semantics):
 </$root>
 ```
 
-## Defining advanced rules in `checkChild()` callbacks
+## Defining advanced rules using callbacks
 
-The {@link module:engine/model/schema~Schema#checkChild `Schema#checkChild()`} method which is the a base method used to check whether some element is allowed in a given structure is {@link module:utils/observablemixin~Observable#decorate a decorated method}. It means that you can add listeners to implement your specific rules which are not limited by the {@link module:engine/model/schema~SchemaItemDefinition declarative `SchemaItemDefinition` API}.
+The base {@link module:engine/model/schema~SchemaItemDefinition declarative `SchemaItemDefinition` API} is by its nature limited, and some custom rules might not be possible to be implemented this way.
 
-These listeners can be added either by listening directly to the {@link module:engine/model/schema~Schema#event:checkChild} event or by using the handy {@link module:engine/model/schema~Schema#addChildCheck `Schema#addChildCheck()`} method.
+For this reason, it is also possible to define schema checks by providing callbacks. This gives you flexibility to implement any logic that you need.
 
-For instance, to disallow nested `<blockQuote>` structures, you can define such a listener:
+These callbacks can be set both for child checks (model structure checks) and attribute checks.
+
+Note that the callbacks take precedence over the rules defined through the declarative API and can overwrite these rules.
+
+### Child checks (structure checks)
+
+Using {@link module:engine/model/schema~Schema#addChildCheck `Schema#addChildCheck()`} you can provide function callbacks in order to implement specific advanced rules for checking the model structure.
+
+You can provide callbacks that are fired only when a specific child is checked, or generic callbacks fired for all checks performed by the schema.
+
+Below is an example of a specific callback, that disallows inline images inside code blocks:
+
+```js
+schema.addChildCheck( context => {
+	if ( context.endsWith( 'codeBlock' ) ) {
+		return false;
+	}
+}, 'imageInline' );
+```
+
+The second parameter (`'imageInline'`) specifies that the callback will be used only if `imageInline` is being checked.
+
+You can also use a callback to force given item to be allowed. For example, allow special `$marker` item to be allowed everywhere:
+
+```js
+schema.addChildCheck( () => true, '$marker' );
+```
+
+Note that a callback may return `true`, `false`, or no value (`undefined`). If `true` or `false` is returned, the decision was made and further callbacks or declarative rules will not be checked. The item will be allowed or disallowed. If no value is returned, further checks will decide whether the item is allowed or not. 
+
+In some cases, you may need to define a generic listener that will be fired on every schema check.
+
+For instance, to disallow all block objects (e.g. tables) inside a block quotes, you can define following callback:
 
 ```js
 schema.addChildCheck( ( context, childDefinition ) => {
-	// Note that the context is automatically normalized to a SchemaContext instance and
-	// the child to its definition (SchemaCompiledItemDefinition).
+	if ( context.endsWith( 'blockQuote' ) && childDefinition.isBlock && childDefinition.isObject ) {
+		return false;
+	}
+} );
+```
+
+The above will trigger on every `checkChild()` call giving you more flexibility. However, please keep in mind that using multiple generic callbacks might negatively impact the editor performance.
+
+### Attribute checks
+
+Similarly, you can define callbacks to check whether given attribute is or is not allowed on given item.
 
-	// If checkChild() is called with a context that ends with blockQuote and blockQuote as a child
-	// to check, make the checkChild() method return false.
-	if ( context.endsWith( 'blockQuote' ) && childDefinition.name == 'blockQuote' ) {
+This time, you will use {@link module:engine/model/schema~Schema#addAttributeCheck `Schema#addAttributeCheck()`} to provide the callback.
+
+For example, allow custom attribute `headingMarker` on all headings:
+
+```js
+schema.addAttributeCheck( ( context, attributeName ) => {
+	const isHeading = context.last.name.startsWith( 'heading' );
+
+	if ( isHeading ) {
+		return true;
+	}
+}, 'headingMarker' );
+```
+
+Generic callbacks are available too. For example, disallow formatting attributes (like bold or italic) on text inside all headings:
+
+```js
+schema.addAttributeCheck( ( context, attributeName ) => {
+	const parent = context.getItem( context.length - 2 );
+	const insideHeading = parent && parent.name.startsWith( 'heading' );
+
+	if ( insideHeading && context.endsWith( '$text' ) && schema.getAttributeProperties( attributeName ).isFormatting ) {
 		return false;
 	}
 } );
 ```
-<!--
-## Defining attributes
 
-TODO
--->
+All notes related to child check callbacks apply to attribute callbacks as well.
 
 ## Implementing additional constraints
 

packages/ckeditor5-engine/src/index.ts

@@ -105,7 +105,8 @@ export type {
 	SchemaAttributeCheckCallback,
 	SchemaChildCheckCallback,
 	AttributeProperties,
-	SchemaItemDefinition
+	SchemaItemDefinition,
+	SchemaContext
 } from './model/schema.js';
 export type { default as Selection, Selectable } from './model/selection.js';
 export type { default as TypeCheckable } from './model/typecheckable.js';

packages/ckeditor5-engine/src/model/model.ts

@@ -146,11 +146,7 @@ export default class Model extends /* #__PURE__ */ ObservableMixin() {
 		// at the end of the conversion. `UpcastDispatcher` or at least `Conversion` class looks like a
 		// better place for this registration but both know nothing about `Schema`.
 		this.schema.register( '$marker' );
-		this.schema.addChildCheck( ( context, childDefinition ) => {
-			if ( childDefinition.name === '$marker' ) {
-				return true;
-			}
-		} );
+		this.schema.addChildCheck( () => true, '$marker' ); // Allow everywhere.
 
 		injectSelectionPostFixer( this );