@ckeditor/ckeditor5-engine
Advanced tools
@ckeditor/ckeditor5-engine - npm Package Compare versions
Comparing version 0.0.0-nightly-20240730.0 to 0.0.0-nightly-20240731.0
@@ -57,6 +57,7 @@ /** | ||
| export type { default as RootElement } from './model/rootelement.js'; | ||
| export type { default as Schema, SchemaAttributeCheckCallback, SchemaChildCheckCallback, AttributeProperties, SchemaItemDefinition } from './model/schema.js'; | ||
| export type { default as Schema, SchemaAttributeCheckCallback, SchemaChildCheckCallback, AttributeProperties, 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'; | ||
| export type { default as Writer } from './model/writer.js'; | ||
| export * from './model/utils/autoparagraphing.js'; | ||
| export type { DocumentChangeEvent } from './model/document.js'; | ||
@@ -63,0 +64,0 @@ export type { DocumentSelectionChangeEvent } from './model/documentselection.js'; |
@@ -44,2 +44,20 @@ /** | ||
| 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?; | ||
@@ -221,3 +239,3 @@ /** | ||
| /** | ||
| * 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. | ||
| * | ||
@@ -230,10 +248,17 @@ * ```ts | ||
| * } ); | ||
| * | ||
| * 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 | ||
@@ -245,4 +270,3 @@ * @param context The context in which the child will be checked. | ||
| /** | ||
| * 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). | ||
| * | ||
@@ -255,7 +279,15 @@ * ```ts | ||
| * } ); | ||
| * | ||
| * 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. | ||
| */ | ||
@@ -270,20 +302,35 @@ checkAttribute(context: SchemaContextDefinition, attributeName: string): boolean; | ||
| * 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 | ||
@@ -294,7 +341,7 @@ * schema.on( 'checkChild', ( evt, args ) => { | ||
| * | ||
| * 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' ); | ||
| * } | ||
@@ -304,9 +351,15 @@ * }, { 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; | ||
| /** | ||
@@ -317,14 +370,22 @@ * Allows registering a callback to the {@link #checkAttribute} method calls. | ||
| * 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. | ||
| * | ||
| * Example: | ||
| * For example, by using this method you can disallow setting attributes on nodes in specific contexts: | ||
| * | ||
| * ```ts | ||
| * // Disallow bold on $text inside heading1. | ||
| * // Disallow setting `bold` on text inside `heading1` element: | ||
| * schema.addAttributeCheck( context => { | ||
| * if ( context.endsWith( 'heading1 $text' ) ) { | ||
| * return false; | ||
| * } | ||
| * }, 'bold' ); | ||
| * ``` | ||
| * | ||
| * You can skip the optional `attributeName` parameter to evaluate the callback for every `checkAttribute()` call. | ||
| * | ||
| * ```ts | ||
| * // 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; | ||
@@ -335,4 +396,10 @@ * } | ||
| * | ||
| * 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 | ||
@@ -343,6 +410,6 @@ * schema.on( 'checkAttribute', ( evt, args ) => { | ||
| * | ||
| * 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; | ||
@@ -353,8 +420,14 @@ * } | ||
| * | ||
| * 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; | ||
| /** | ||
@@ -503,2 +576,18 @@ * This method allows assigning additional metadata to the model attributes. For example, | ||
| /** | ||
| * 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 | ||
@@ -882,2 +971,4 @@ * inside the given range on which the attribute can be applied. | ||
| * Inherits "allowed children" from other items. | ||
| * | ||
| * Note that the item's "own" rules take precedence over "inherited" rules and can overwrite them. | ||
| */ | ||
@@ -887,2 +978,4 @@ 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. | ||
| */ | ||
@@ -892,2 +985,4 @@ 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. | ||
| */ | ||
@@ -897,2 +992,4 @@ 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. | ||
| */ | ||
@@ -902,2 +999,4 @@ 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. | ||
| */ | ||
@@ -1073,2 +1172,14 @@ inheritAllFrom?: string; | ||
| /** | ||
| * 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. | ||
@@ -1122,3 +1233,3 @@ */ | ||
| * * By defining a {@link module:engine/model/schema~SchemaContext} instance - in this case the same instance as provided | ||
| * will be return. | ||
| * will be returned. | ||
| * | ||
@@ -1125,0 +1236,0 @@ * Examples of context definitions passed to the {@link module:engine/model/schema~Schema#checkChild `Schema#checkChild()`} |
| { | ||
| "name": "@ckeditor/ckeditor5-engine", | ||
| "version": "0.0.0-nightly-20240730.0", | ||
| "version": "0.0.0-nightly-20240731.0", | ||
| "description": "The editing engine of CKEditor 5 – the best browser-based rich text editor.", | ||
@@ -27,3 +27,3 @@ "keywords": [ | ||
| "dependencies": { | ||
| "@ckeditor/ckeditor5-utils": "0.0.0-nightly-20240730.0", | ||
| "@ckeditor/ckeditor5-utils": "0.0.0-nightly-20240731.0", | ||
| "lodash-es": "4.17.21" | ||
@@ -30,0 +30,0 @@ }, |
@@ -53,6 +53,7 @@ /** | ||
| export type { default as RootElement } from './model/rootelement.js'; | ||
| export type { default as Schema, SchemaAttributeCheckCallback, SchemaChildCheckCallback, AttributeProperties, SchemaItemDefinition } from './model/schema.js'; | ||
| export type { default as Schema, SchemaAttributeCheckCallback, SchemaChildCheckCallback, AttributeProperties, 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'; | ||
| export type { default as Writer } from './model/writer.js'; | ||
| export * from './model/utils/autoparagraphing.js'; | ||
| export type { DocumentChangeEvent } from './model/document.js'; | ||
@@ -59,0 +60,0 @@ export type { DocumentSelectionChangeEvent } from './model/documentselection.js'; |
@@ -41,2 +41,4 @@ /** | ||
| export { default as TextProxy } from './model/textproxy.js'; | ||
| // Model utils. | ||
| export * from './model/utils/autoparagraphing.js'; | ||
| // View. | ||
@@ -43,0 +45,0 @@ export { default as DataTransfer } from './view/datatransfer.js'; |
@@ -93,7 +93,3 @@ /** | ||
| this.schema.register('$marker'); | ||
| this.schema.addChildCheck((context, childDefinition) => { | ||
| if (childDefinition.name === '$marker') { | ||
| return true; | ||
| } | ||
| }); | ||
| this.schema.addChildCheck(() => true, '$marker'); // Allow everywhere. | ||
| injectSelectionPostFixer(this); | ||
@@ -100,0 +96,0 @@ // Post-fixer which takes care of adding empty paragraph elements to the empty roots. |
@@ -40,2 +40,20 @@ /** | ||
| 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?; | ||
@@ -217,3 +235,3 @@ /** | ||
| /** | ||
| * 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. | ||
| * | ||
@@ -226,10 +244,17 @@ * ```ts | ||
| * } ); | ||
| * | ||
| * 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 | ||
@@ -241,4 +266,3 @@ * @param context The context in which the child will be checked. | ||
| /** | ||
| * 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). | ||
| * | ||
@@ -251,7 +275,15 @@ * ```ts | ||
| * } ); | ||
| * | ||
| * 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. | ||
| */ | ||
@@ -266,20 +298,35 @@ checkAttribute(context: SchemaContextDefinition, attributeName: string): boolean; | ||
| * 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 | ||
@@ -290,7 +337,7 @@ * schema.on( 'checkChild', ( evt, args ) => { | ||
| * | ||
| * 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' ); | ||
| * } | ||
@@ -300,9 +347,15 @@ * }, { 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; | ||
| /** | ||
@@ -313,14 +366,22 @@ * Allows registering a callback to the {@link #checkAttribute} method calls. | ||
| * 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. | ||
| * | ||
| * Example: | ||
| * For example, by using this method you can disallow setting attributes on nodes in specific contexts: | ||
| * | ||
| * ```ts | ||
| * // Disallow bold on $text inside heading1. | ||
| * // Disallow setting `bold` on text inside `heading1` element: | ||
| * schema.addAttributeCheck( context => { | ||
| * if ( context.endsWith( 'heading1 $text' ) ) { | ||
| * return false; | ||
| * } | ||
| * }, 'bold' ); | ||
| * ``` | ||
| * | ||
| * You can skip the optional `attributeName` parameter to evaluate the callback for every `checkAttribute()` call. | ||
| * | ||
| * ```ts | ||
| * // 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; | ||
@@ -331,4 +392,10 @@ * } | ||
| * | ||
| * 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 | ||
@@ -339,6 +406,6 @@ * schema.on( 'checkAttribute', ( evt, args ) => { | ||
| * | ||
| * 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; | ||
@@ -349,8 +416,14 @@ * } | ||
| * | ||
| * 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; | ||
| /** | ||
@@ -499,2 +572,18 @@ * This method allows assigning additional metadata to the model attributes. For example, | ||
| /** | ||
| * 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 | ||
@@ -878,2 +967,4 @@ * inside the given range on which the attribute can be applied. | ||
| * Inherits "allowed children" from other items. | ||
| * | ||
| * Note that the item's "own" rules take precedence over "inherited" rules and can overwrite them. | ||
| */ | ||
@@ -883,2 +974,4 @@ 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. | ||
| */ | ||
@@ -888,2 +981,4 @@ 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. | ||
| */ | ||
@@ -893,2 +988,4 @@ 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. | ||
| */ | ||
@@ -898,2 +995,4 @@ 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. | ||
| */ | ||
@@ -1069,2 +1168,14 @@ inheritAllFrom?: string; | ||
| /** | ||
| * 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. | ||
@@ -1118,3 +1229,3 @@ */ | ||
| * * By defining a {@link module:engine/model/schema~SchemaContext} instance - in this case the same instance as provided | ||
| * will be return. | ||
| * will be returned. | ||
| * | ||
@@ -1121,0 +1232,0 @@ * Examples of context definitions passed to the {@link module:engine/model/schema~Schema#checkChild `Schema#checkChild()`} |
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is too big to display
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by0.47%
13427925
- Lines of code
- increased by0.37%
126423
Dependency changes
+ Added@ckeditor/ckeditor5-utils@0.0.0-nightly-20240731.0(transitive)
- Removed@ckeditor/ckeditor5-utils@0.0.0-nightly-20240730.0(transitive)