@ckeditor/ckeditor5-engine 42.0.2 → 43.0.0-alpha.1

package/src/model/schema.d.ts

@@ -37,6 +37,24 @@ export default class Schema extends /* #__PURE__ */ Schema_base {
      * A dictionary containing attribute properties.
      */
     private readonly _attributeProperties;
+    /**
+     * Stores additional callbacks registered for schema items, which are evaluated when {@link ~Schema#checkChild} is called.
+     *
+     * Keys are schema item names for which the callbacks are registered. Values are arrays with the callbacks.
+     *
+     * Some checks are added under {@link ~Schema#_genericCheckSymbol} key, these are evaluated for every {@link ~Schema#checkChild} call.
+     */
+    private readonly _customChildChecks;
+    /**
+     * Stores additional callbacks registered for attribute names, which are evaluated when {@link ~Schema#checkAttribute} is called.
+     *
+     * Keys are schema attribute names for which the callbacks are registered. Values are arrays with the callbacks.
+     *
+     * Some checks are added under {@link ~Schema#_genericCheckSymbol} key, these are evaluated for every
+     * {@link ~Schema#checkAttribute} call.
+     */
+    private readonly _customAttributeChecks;
+    private readonly _genericCheckSymbol;
     private _compiledDefinitions?;
     /**
      * Creates a schema instance.
@@ -213,7 +231,7 @@ export default class Schema extends /* #__PURE__ */ Schema_base {
      */
     isContent(item: string | Item | DocumentFragment | SchemaContextItem): boolean;
     /**
-     * Checks whether the given node (`child`) can be a child of the given context.
+     * Checks whether the given node can be a child of the given context.
      *
      * ```ts
      * schema.checkChild( model.document.getRoot(), paragraph ); // -> false
@@ -221,13 +239,20 @@ export default class Schema extends /* #__PURE__ */ Schema_base {
      * schema.register( 'paragraph', {
      * 	allowIn: '$root'
      * } );
+     *
      * schema.checkChild( model.document.getRoot(), paragraph ); // -> true
      * ```
      *
-     * Note: When verifying whether the given node can be a child of the given context, the
-     * schema also verifies the entire context – from its root to its last element. Therefore, it is possible
-     * for `checkChild()` to return `false` even though the context's last element can contain the checked child.
-     * It happens if one of the context's elements does not allow its child.
+     * Both {@link module:engine/model/schema~Schema#addChildCheck callback checks} and declarative rules (added when
+     * {@link module:engine/model/schema~Schema#register registering} and {@link module:engine/model/schema~Schema#extend extending} items)
+     * are evaluated when this method is called.
+     *
+     * Note that callback checks have bigger priority than declarative rules checks and may overwrite them.
+     *
+     * Note that when verifying whether the given node can be a child of the given context, the schema also verifies the entire
+     * context – from its root to its last element. Therefore, it is possible for `checkChild()` to return `false` even though
+     * the `context` last element can contain the checked child. It happens if one of the `context` elements does not allow its child.
+     * When `context` is verified, {@link module:engine/model/schema~Schema#addChildCheck custom checks} are considered as well.
      *
      * @fires checkChild
      * @param context The context in which the child will be checked.
@@ -235,8 +260,7 @@ export default class Schema extends /* #__PURE__ */ Schema_base {
      */
     checkChild(context: SchemaContextDefinition, def: string | Node | DocumentFragment): boolean;
     /**
-     * Checks whether the given attribute can be applied in the given context (on the last
-     * item of the context).
+     * Checks whether the given attribute can be applied in the given context (on the last item of the context).
      *
      * ```ts
      * schema.checkAttribute( textNode, 'bold' ); // -> false
@@ -244,116 +268,152 @@ export default class Schema extends /* #__PURE__ */ Schema_base {
      * schema.extend( '$text', {
      * 	allowAttributes: 'bold'
      * } );
+     *
      * schema.checkAttribute( textNode, 'bold' ); // -> true
      * ```
      *
+     * Both {@link module:engine/model/schema~Schema#addAttributeCheck callback checks} and declarative rules (added when
+     * {@link module:engine/model/schema~Schema#register registering} and {@link module:engine/model/schema~Schema#extend extending} items)
+     * are evaluated when this method is called.
+     *
+     * Note that callback checks have bigger priority than declarative rules checks and may overwrite them.
+     *
      * @fires checkAttribute
      * @param context The context in which the attribute will be checked.
+     * @param attributeName Name of attribute to check in the given context.
      */
     checkAttribute(context: SchemaContextDefinition, attributeName: string): boolean;
-    /**
-     * Checks whether the given element (`elementToMerge`) can be merged with the specified base element (`positionOrBaseElement`).
-     *
-     * In other words – whether `elementToMerge`'s children {@link #checkChild are allowed} in the `positionOrBaseElement`.
-     *
-     * This check ensures that elements merged with {@link module:engine/model/writer~Writer#merge `Writer#merge()`}
-     * will be valid.
-     *
-     * Instead of elements, you can pass the instance of the {@link module:engine/model/position~Position} class as the
-     * `positionOrBaseElement`. It means that the elements before and after the position will be checked whether they can be merged.
-     *
-     * @param positionOrBaseElement The position or base element to which the `elementToMerge` will be merged.
-     * @param elementToMerge The element to merge. Required if `positionOrBaseElement` is an element.
-     */
-    checkMerge(positionOrBaseElement: Position | Element, elementToMerge: Element): boolean;
+    checkMerge(position: Position): boolean;
+    checkMerge(baseElement: Element, elementToMerge: Element): boolean;
     /**
      * Allows registering a callback to the {@link #checkChild} method calls.
      *
      * Callbacks allow you to implement rules which are not otherwise possible to achieve
      * by using the declarative API of {@link module:engine/model/schema~SchemaItemDefinition}.
-     * For example, by using this method you can disallow elements in specific contexts.
      *
-     * This method is a shorthand for using the {@link #event:checkChild} event. For even better control,
-     * you can use that event instead.
+     * Note that callback checks have bigger priority than declarative rules checks and may overwrite them.
      *
-     * Example:
+     * For example, by using this method you can disallow elements in specific contexts:
      *
      * ```ts
-     * // Disallow heading1 directly inside a blockQuote.
+     * // Disallow `heading1` inside a `blockQuote` that is inside a table.
      * schema.addChildCheck( ( context, childDefinition ) => {
-     * 	if ( context.endsWith( 'blockQuote' ) && childDefinition.name == 'heading1' ) {
+     * 	if ( context.endsWith( 'tableCell blockQuote' ) ) {
      * 		return false;
      * 	}
+     * }, 'heading1' );
+     * ```
+     *
+     * You can skip the optional `itemName` parameter to evaluate the callback for every `checkChild()` call.
+     *
+     * ```ts
+     * // Inside specific custom element, allow only children, which allows for a specific attribute.
+     * schema.addChildCheck( ( context, childDefinition ) => {
+     * 	if ( context.endsWith( 'myElement' ) ) {
+     * 		return childDefinition.allowAttributes.includes( 'myAttribute' );
+     * 	}
      * } );
      * ```
      *
-     * Which translates to:
+     * Please note that the generic callbacks may affect the editor performance and should be avoided if possible.
+     *
+     * When one of the callbacks makes a decision (returns `true` or `false`) the processing is finished and other callbacks are not fired.
+     * Callbacks are fired in the order they were added, however generic callbacks are fired before callbacks added for a specified item.
+     *
+     * You can also use `checkChild` event, if you need even better control. The result from the example above could also be
+     * achieved with following event callback:
      *
      * ```ts
      * schema.on( 'checkChild', ( evt, args ) => {
      * 	const context = args[ 0 ];
      * 	const childDefinition = args[ 1 ];
      *
-     * 	if ( context.endsWith( 'blockQuote' ) && childDefinition && childDefinition.name == 'heading1' ) {
+     * 	if ( context.endsWith( 'myElement' ) ) {
      * 		// Prevent next listeners from being called.
      * 		evt.stop();
-     * 		// Set the checkChild()'s return value.
-     * 		evt.return = false;
+     * 		// Set the `checkChild()` return value.
+     * 		evt.return = childDefinition.allowAttributes.includes( 'myAttribute' );
      * 	}
      * }, { priority: 'high' } );
      * ```
      *
+     * Note that the callback checks and declarative rules checks are processed on `normal` priority.
+     *
+     * Adding callbacks this way can also negatively impact editor performance.
+     *
      * @param callback The callback to be called. It is called with two parameters:
      * {@link module:engine/model/schema~SchemaContext} (context) instance and
-     * {@link module:engine/model/schema~SchemaCompiledItemDefinition} (child-to-check definition).
-     * The callback may return `true/false` to override `checkChild()`'s return value. If it does not return
-     * a boolean value, the default algorithm (or other callbacks) will define `checkChild()`'s return value.
+     * {@link module:engine/model/schema~SchemaCompiledItemDefinition} (definition). The callback may return `true/false` to override
+     * `checkChild()`'s return value. If it does not return a boolean value, the default algorithm (or other callbacks) will define
+     * `checkChild()`'s return value.
+     * @param itemName Name of the schema item for which the callback is registered. If specified, the callback will be run only for
+     * `checkChild()` calls which `def` parameter matches the `itemName`. Otherwise, the callback will run for every `checkChild` call.
      */
-    addChildCheck(callback: SchemaChildCheckCallback): void;
+    addChildCheck(callback: SchemaChildCheckCallback, itemName?: string): void;
     /**
      * Allows registering a callback to the {@link #checkAttribute} method calls.
      *
      * Callbacks allow you to implement rules which are not otherwise possible to achieve
      * by using the declarative API of {@link module:engine/model/schema~SchemaItemDefinition}.
-     * For example, by using this method you can disallow attribute if node to which it is applied
-     * is contained within some other element (e.g. you want to disallow `bold` on `$text` within `heading1`).
      *
-     * This method is a shorthand for using the {@link #event:checkAttribute} event. For even better control,
-     * you can use that event instead.
+     * Note that callback checks have bigger priority than declarative rules checks and may overwrite them.
+     *
+     * For example, by using this method you can disallow setting attributes on nodes in specific contexts:
+     *
+     * ```ts
+     * // Disallow setting `bold` on text inside `heading1` element:
+     * schema.addAttributeCheck( context => {
+     * 	if ( context.endsWith( 'heading1 $text' ) ) {
+     * 		return false;
+     * 	}
+     * }, 'bold' );
+     * ```
      *
-     * Example:
+     * You can skip the optional `attributeName` parameter to evaluate the callback for every `checkAttribute()` call.
      *
      * ```ts
-     * // Disallow bold on $text inside heading1.
+     * // Disallow formatting attributes on text inside custom `myTitle` element:
      * schema.addAttributeCheck( ( context, attributeName ) => {
-     * 	if ( context.endsWith( 'heading1 $text' ) && attributeName == 'bold' ) {
+     * 	if ( context.endsWith( 'myTitle $text' ) && schema.getAttributeProperties( attributeName ).isFormatting ) {
      * 		return false;
      * 	}
      * } );
      * ```
      *
-     * Which translates to:
+     * Please note that the generic callbacks may affect the editor performance and should be avoided if possible.
+     *
+     * When one of the callbacks makes a decision (returns `true` or `false`) the processing is finished and other callbacks are not fired.
+     * Callbacks are fired in the order they were added, however generic callbacks are fired before callbacks added for a specified item.
+     *
+     * You can also use {@link #event:checkAttribute} event, if you need even better control. The result from the example above could also
+     * be achieved with following event callback:
      *
      * ```ts
      * schema.on( 'checkAttribute', ( evt, args ) => {
      * 	const context = args[ 0 ];
      * 	const attributeName = args[ 1 ];
      *
-     * 	if ( context.endsWith( 'heading1 $text' ) && attributeName == 'bold' ) {
+     * 	if ( context.endsWith( 'myTitle $text' ) && schema.getAttributeProperties( attributeName ).isFormatting ) {
      * 		// Prevent next listeners from being called.
      * 		evt.stop();
-     * 		// Set the checkAttribute()'s return value.
+     * 		// Set the `checkAttribute()` return value.
      * 		evt.return = false;
      * 	}
      * }, { priority: 'high' } );
      * ```
      *
+     * Note that the callback checks and declarative rules checks are processed on `normal` priority.
+     *
+     * Adding callbacks this way can also negatively impact editor performance.
+     *
      * @param callback The callback to be called. It is called with two parameters:
-     * {@link module:engine/model/schema~SchemaContext} (context) instance and attribute name.
-     * The callback may return `true/false` to override `checkAttribute()`'s return value. If it does not return
-     * a boolean value, the default algorithm (or other callbacks) will define `checkAttribute()`'s return value.
+     * {@link module:engine/model/schema~SchemaContext `context`} and attribute name. The callback may return `true` or `false`, to
+     * override `checkAttribute()`'s return value. If it does not return a boolean value, the default algorithm (or other callbacks)
+     * will define `checkAttribute()`'s return value.
+     * @param attributeName Name of the attribute for which the callback is registered. If specified, the callback will be run only for
+     * `checkAttribute()` calls with matching `attributeName`. Otherwise, the callback will run for every `checkAttribute()` call.
      */
-    addAttributeCheck(callback: SchemaAttributeCheckCallback): void;
+    addAttributeCheck(callback: SchemaAttributeCheckCallback, attributeName?: string): void;
     /**
      * This method allows assigning additional metadata to the model attributes. For example,
      * {@link module:engine/model/schema~AttributeProperties `AttributeProperties#isFormatting` property} is
@@ -496,6 +556,22 @@ export default class Schema extends /* #__PURE__ */ Schema_base {
     private _clearCache;
     private _compile;
     private _checkContextMatch;
+    /**
+     * Calls child check callbacks to decide whether `def` is allowed in `context`. It uses both generic and specific (defined for `def`
+     * item) callbacks. If neither callback makes a decision, `undefined` is returned.
+     *
+     * Note that the first callback that makes a decision "wins", i.e., if any callback returns `true` or `false`, then the processing
+     * is over and that result is returned.
+     */
+    private _evaluateChildChecks;
+    /**
+     * Calls attribute check callbacks to decide whether `attributeName` can be set on the last element of `context`. It uses both
+     * generic and specific (defined for `attributeName`) callbacks. If neither callback makes a decision, `undefined` is returned.
+     *
+     * Note that the first callback that makes a decision "wins", i.e., if any callback returns `true` or `false`, then the processing
+     * is over and that result is returned.
+     */
+    private _evaluateAttributeChecks;
     /**
      * Takes a flat range and an attribute name. Traverses the range recursively and deeply to find and return all ranges
      * inside the given range on which the attribute can be applied.
@@ -875,22 +951,32 @@ export interface SchemaItemDefinition {
     disallowAttributes?: string | Array<string>;
     /**
      * Inherits "allowed children" from other items.
+     *
+     * Note that the item's "own" rules take precedence over "inherited" rules and can overwrite them.
      */
     allowContentOf?: string | Array<string>;
     /**
      * Inherits "allowed in" from other items.
+     *
+     * Note that the item's "own" rules take precedence over "inherited" rules and can overwrite them.
      */
     allowWhere?: string | Array<string>;
     /**
      * Inherits "allowed attributes" from other items.
+     *
+     * Note that the item's "own" rules take precedence over "inherited" rules and can overwrite them.
      */
     allowAttributesOf?: string | Array<string>;
     /**
      * Inherits `is*` properties of other items.
+     *
+     * Note that the item's "own" rules take precedence over "inherited" rules and can overwrite them.
      */
     inheritTypesFrom?: string | Array<string>;
     /**
      * A shorthand for `allowContentOf`, `allowWhere`, `allowAttributesOf`, `inheritTypesFrom`.
+     *
+     * Note that the item's "own" rules take precedence over "inherited" rules and can overwrite them.
      */
     inheritAllFrom?: string;
     /**
@@ -1060,6 +1146,18 @@ export declare class SchemaContext implements Iterable<SchemaContextItem> {
      * @returns A new schema context instance with an additional item.
      */
     push(item: string | Node): SchemaContext;
+    /**
+     * Returns a new schema context that is based on this context but has the last item removed.
+     *
+     * ```ts
+     * const ctxParagraph = new SchemaContext( [ '$root', 'blockQuote', 'paragraph' ] );
+     * const ctxBlockQuote = ctxParagraph.trimLast(); // Items in `ctxBlockQuote` are: `$root` an `blockQuote`.
+     * const ctxRoot = ctxBlockQuote.trimLast(); // Items in `ctxRoot` are: `$root`.
+     * ```
+     *
+     * @returns A new reduced schema context instance.
+     */
+    trimLast(): SchemaContext;
     /**
      * Gets an item on the given index.
      */
@@ -1109,7 +1207,7 @@ export declare class SchemaContext implements Iterable<SchemaContextItem> {
  * * By defining an **array of node names** (potentially, mixed with real nodes) – The same as **name of node**
  * but it is possible to create a path.
  * * By defining a {@link module:engine/model/schema~SchemaContext} instance - in this case the same instance as provided
- * will be return.
+ * will be returned.
  *
  * Examples of context definitions passed to the {@link module:engine/model/schema~Schema#checkChild `Schema#checkChild()`}
  * method: