/**
* @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.
*/
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;
}
/**
* 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;
	};
}
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.
*/
export interface SuggestionDescriptionItem {
	type: "text" | "addEmptyContainer" | "addObject" | "removeEmptyContainer" | "removeObject" | "addContainer" | "removeContainer" | "addFormat" | "removeFormat";
	add?: string;
	remove?: string;
	element?: ModelElement;
	quantity?: number;
	key?: string;
}