@ckeditor/ckeditor5-track-changes 48.2.0 → 48.3.0-alpha.1

package/dist/suggestiondescriptionfactory.d.ts

@@ -1,177 +1,177 @@
 /**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-import { type Locale, type PriorityString } from '@ckeditor/ckeditor5-utils';
-import type { ModelSchema, ModelElement } from '@ckeditor/ckeditor5-engine';
-import { type Suggestion } from './suggestion.js';
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
+import { type Locale, type PriorityString } from "@ckeditor/ckeditor5-utils";
+import type { ModelSchema, ModelElement } from "@ckeditor/ckeditor5-engine";
+import { type Suggestion } from "./suggestion.js";
 /**
- * Creates descriptions for suggestions and suggestions chains.
- *
- * The class manages everything related to generating descriptions for suggestions. Here, you register labels for elements,
- * attributes, or custom callback for non-regular cases.
- *
- * One or more suggestions that are grouped together (based ond various conditions) create "suggestion chain".
- * In such chain one suggestion may impact other suggestion when it comes to the description of the whole chain.
- * For example, insertion next to deletion results in "Replaced" description.
- */
+* Creates descriptions for suggestions and suggestions chains.
+*
+* The class manages everything related to generating descriptions for suggestions. Here, you register labels for elements,
+* attributes, or custom callback for non-regular cases.
+*
+* One or more suggestions that are grouped together (based ond various conditions) create "suggestion chain".
+* In such chain one suggestion may impact other suggestion when it comes to the description of the whole chain.
+* For example, insertion next to deletion results in "Replaced" description.
+*/
 export declare class SuggestionDescriptionFactory {
-    constructor(schema: ModelSchema, locale: Locale);
-    /**
-     * Returns descriptions for given suggestion chain.
-     *
-     * The structure of the descriptions array is as follows (explained on an example):
-     *
-     * ```ts
-     * [
-     *	 { type: 'insertion', content: '*Insert:* 2 paragraphs' },
-     *	 { type: 'insertion', content: '*Insert:* image },
-     *	 { type: 'replace', content: '*Replace:* "Foo" *with* "Bar"' }
-     * ]
-     * ```
-     *
-     * In above example there are three description instances (or lines). Two new (empty) paragraphs were added,
-     * an image was added and then "Foo" text was removed and "Bar" text was added. For example, above structure could be rendered as:
-     *
-     * ```html
-     * <p><strong>Insert:</strong> 2 paragraphs</p>
-     * <p><strong>Insert:</strong> image</p>
-     * <p><strong>Replace:</strong> "Foo" <strong>with</strong> "Bar"</p>
-     * ```
-     */
-    getDescriptions(suggestions: Array<Suggestion>): Array<SuggestionDescription>;
-    /**
-     * Registers a callback function that returns a custom description for a suggestion.
-     *
-     * Registered callback is fired for a suggestion whenever there is a need to generate a description for that suggestion.
-     *
-     * The callback takes the suggestion instance as a parameter and should return
-     * {@link module:track-changes/suggestiondescriptionfactory~SuggestionDescription description object} or a falsy value
-     * if the suggestion was not handled by the callback.
-     *
-     * Example of a description callback for the bold style:
-     *
-     * ```ts
-     * suggestionDescriptionFactory.registerDescriptionCallback( suggestion => {
-     *		const { data } = suggestion;
-     *
-     *		// Omit suggestions that are not bold style suggestions.
-     *		if ( !data || data.commandName !== 'bold' ) {
-     *			return;
-     *		}
-     *
-     *		const isSet = !!data.commandParams[ 0 ].forceValue;
-     *		const content = isSet ? '*Set format:* bold' : '*Remove format:* bold';
-     *
-     *		return {
-     *			type: 'format',
-     *			content
-     *		};
-     *	} );
-     * ```
-     */
-    registerDescriptionCallback(callback: SuggestionDescriptionCallback): void;
-    /**
-     * For given `elementName` registers how this element will be labeled in a description (for example when it is added
-     * or removed).
-     *
-     * Instead of a string name you may provide a matching function that takes item {@link module:engine/model/item~ModelItem} as an input
-     * and should return boolean value.
-     *
-     * Provided label callback takes one parameter, `quantity`, and is expected to return the label for the element as a string.
-     *
-     * A simple use case without using internationalization:
-     *
-     * ```ts
-     * suggestionDescriptionFactory.registerElementLabel(
-     *		'paragraph',
-     *		quantity => quantity == 1 ? 'paragraph' : quantity + ' paragraphs'
-     * );
-     * ```
-     *
-     * If you want your feature to be localized to other languages, use localization service:
-     *
-     * ```ts
-     * const t = editor.locale.t; // Remember that you have to use function named `t`.
-     *
-     * suggestionDescriptionFactory.registerElementLabel(
-     *		'paragraph',
-     *		quantity => t( { string: 'paragraph', plural: '%0 paragraphs', id: 'ELEMENT_PARAGRAPH' }, quantity )
-     * );
-     * ```
-     */
-    registerElementLabel(elementNameOrCallback: string | Function, labelCallback: SuggestionLabelCallback, priority?: PriorityString): void;
-    /**
-     * For given `attributeName` registers how this attribute will be labeled in a description (for example when it is added
-     * or removed).
-     *
-     * Example usage with internationalization:
-     *
-     * ```ts
-     * const t = editor.locale.t; // Remember that you have to use function named `t`.
-     *
-     * suggestionDescriptionFactory.registerAttributeLabel(
-     *		'bold',
-     *		t( 'bold' )
-     * );
-     * ```
-     */
-    registerAttributeLabel(attributeName: string, attributeLabel: string): void;
-    /**
-     * Returns label registered for given element or the element name if there is no label registered for it.
-     */
-    getItemLabel(element: ModelElement, quantity?: number): string;
+	constructor(schema: ModelSchema, locale: Locale);
+	/**
+	* Returns descriptions for given suggestion chain.
+	*
+	* The structure of the descriptions array is as follows (explained on an example):
+	*
+	* ```ts
+	* [
+	*	 { type: 'insertion', content: '*Insert:* 2 paragraphs' },
+	*	 { type: 'insertion', content: '*Insert:* image },
+	*	 { type: 'replace', content: '*Replace:* "Foo" *with* "Bar"' }
+	* ]
+	* ```
+	*
+	* In above example there are three description instances (or lines). Two new (empty) paragraphs were added,
+	* an image was added and then "Foo" text was removed and "Bar" text was added. For example, above structure could be rendered as:
+	*
+	* ```html
+	* <p><strong>Insert:</strong> 2 paragraphs</p>
+	* <p><strong>Insert:</strong> image</p>
+	* <p><strong>Replace:</strong> "Foo" <strong>with</strong> "Bar"</p>
+	* ```
+	*/
+	getDescriptions(suggestions: Array<Suggestion>): Array<SuggestionDescription>;
+	/**
+	* Registers a callback function that returns a custom description for a suggestion.
+	*
+	* Registered callback is fired for a suggestion whenever there is a need to generate a description for that suggestion.
+	*
+	* The callback takes the suggestion instance as a parameter and should return
+	* {@link module:track-changes/suggestiondescriptionfactory~SuggestionDescription description object} or a falsy value
+	* if the suggestion was not handled by the callback.
+	*
+	* Example of a description callback for the bold style:
+	*
+	* ```ts
+	* suggestionDescriptionFactory.registerDescriptionCallback( suggestion => {
+	*		const { data } = suggestion;
+	*
+	*		// Omit suggestions that are not bold style suggestions.
+	*		if ( !data || data.commandName !== 'bold' ) {
+	*			return;
+	*		}
+	*
+	*		const isSet = !!data.commandParams[ 0 ].forceValue;
+	*		const content = isSet ? '*Set format:* bold' : '*Remove format:* bold';
+	*
+	*		return {
+	*			type: 'format',
+	*			content
+	*		};
+	*	} );
+	* ```
+	*/
+	registerDescriptionCallback(callback: SuggestionDescriptionCallback): void;
+	/**
+	* For given `elementName` registers how this element will be labeled in a description (for example when it is added
+	* or removed).
+	*
+	* Instead of a string name you may provide a matching function that takes item {@link module:engine/model/item~ModelItem} as an input
+	* and should return boolean value.
+	*
+	* Provided label callback takes one parameter, `quantity`, and is expected to return the label for the element as a string.
+	*
+	* A simple use case without using internationalization:
+	*
+	* ```ts
+	* suggestionDescriptionFactory.registerElementLabel(
+	*		'paragraph',
+	*		quantity => quantity == 1 ? 'paragraph' : quantity + ' paragraphs'
+	* );
+	* ```
+	*
+	* If you want your feature to be localized to other languages, use localization service:
+	*
+	* ```ts
+	* const t = editor.locale.t; // Remember that you have to use function named `t`.
+	*
+	* suggestionDescriptionFactory.registerElementLabel(
+	*		'paragraph',
+	*		quantity => t( { string: 'paragraph', plural: '%0 paragraphs', id: 'ELEMENT_PARAGRAPH' }, quantity )
+	* );
+	* ```
+	*/
+	registerElementLabel(elementNameOrCallback: string | Function, labelCallback: SuggestionLabelCallback, priority?: PriorityString): void;
+	/**
+	* For given `attributeName` registers how this attribute will be labeled in a description (for example when it is added
+	* or removed).
+	*
+	* Example usage with internationalization:
+	*
+	* ```ts
+	* const t = editor.locale.t; // Remember that you have to use function named `t`.
+	*
+	* suggestionDescriptionFactory.registerAttributeLabel(
+	*		'bold',
+	*		t( 'bold' )
+	* );
+	* ```
+	*/
+	registerAttributeLabel(attributeName: string, attributeLabel: string): void;
+	/**
+	* Returns label registered for given element or the element name if there is no label registered for it.
+	*/
+	getItemLabel(element: ModelElement, quantity?: number): string;
 }
 /**
- * A description for the suggestion.
- *
- * ```ts
- * {
- *		type: 'format',
- *		label: '*Set format:* bold'
- * }
- * ```
- *
- * A description for the color-related suggestions like font color may specify the `color` property that will provide a better UX
- * by displaying a color box next to the suggestion.
- *
- * ```ts
- * {
- * 		type: 'format',
- * 		label: '*Set font color:*',
- * 		color: {
- * 			value: 'hsl( 60, 60%, 60% )',
- * 			title: 'yellow'
- * 		}
- * }
- * ```
- */
+* A description for the suggestion.
+*
+* ```ts
+* {
+*		type: 'format',
+*		label: '*Set format:* bold'
+* }
+* ```
+*
+* A description for the color-related suggestions like font color may specify the `color` property that will provide a better UX
+* by displaying a color box next to the suggestion.
+*
+* ```ts
+* {
+* 		type: 'format',
+* 		label: '*Set font color:*',
+* 		color: {
+* 			value: 'hsl( 60, 60%, 60% )',
+* 			title: 'yellow'
+* 		}
+* }
+* ```
+*/
 export interface SuggestionDescription {
-    type: 'insertion' | 'deletion' | 'replace' | 'format';
-    /**
-     * Description label. You may use `*` to bold part of the label.
-     */
-    content: string;
-    /**
-     * The optional `color` property used for color-related suggestions.
-     * The object should provide the `value` (for displaying the color) and `title` (for describing the color) fields.
-     */
-    color?: {
-        value: string;
-        title: string;
-    };
+	type: "insertion" | "deletion" | "replace" | "format";
+	/**
+	* Description label. You may use `*` to bold part of the label.
+	*/
+	content: string;
+	/**
+	* The optional `color` property used for color-related suggestions.
+	* The object should provide the `value` (for displaying the color) and `title` (for describing the color) fields.
+	*/
+	color?: {
+		value: string;
+		title: string;
+	};
 }
 export type SuggestionDescriptionCallback = (suggestion: Suggestion) => SuggestionDescription | SuggestionDescriptionItem | undefined;
 export type SuggestionLabelCallback = (quantity: number) => string;
 /**
- * An intermediate state which is easier to operate on when consecutive suggestion
- * ranges are traversed.
- */
+* An intermediate state which is easier to operate on when consecutive suggestion
+* ranges are traversed.
+*/
 export interface SuggestionDescriptionItem {
-    type: 'text' | 'addEmptyContainer' | 'addObject' | 'removeEmptyContainer' | 'removeObject' | 'addContainer' | 'removeContainer' | 'addFormat' | 'removeFormat';
-    add?: string;
-    remove?: string;
-    element?: ModelElement;
-    quantity?: number;
-    key?: string;
+	type: "text" | "addEmptyContainer" | "addObject" | "removeEmptyContainer" | "removeObject" | "addContainer" | "removeContainer" | "addFormat" | "removeFormat";
+	add?: string;
+	remove?: string;
+	element?: ModelElement;
+	quantity?: number;
+	key?: string;
 }