/**
* @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
*/
/**
* @module html-support/generalhtmlsupportconfig
*/
import type { MatcherObjectPattern } from "@ckeditor/ckeditor5-engine";
/**
* The configuration of the General HTML Support feature.
* The option is used by the {@link module:html-support/generalhtmlsupport~GeneralHtmlSupport} feature.
*
* ```ts
* ClassicEditor
* 	.create( {
* 		htmlSupport: ... // General HTML Support feature config.
* 	} )
* 	.then( ... )
* 	.catch( ... );
* ```
*
* See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
*/
export interface GeneralHtmlSupportConfig {
	/**
	* The configuration of allowed content rules used by General HTML Support.
	*
	* Setting this configuration option will enable HTML features that are not explicitly supported by any other
	* dedicated CKEditor 5 features.
	*
	* ```ts
	* const htmlSupportConfig.allow = [
	* 	{
	* 		name: 'div',                      // Enable 'div' element support,
	* 		classes: [ 'special-container' ], // allow 'special-container' class,
	* 		styles: 'background',             // allow 'background' style,
	* 		attributes: true                  // allow any attribute (can be empty).
	* 	},
	* 	{
	* 		name: 'p',                                   // Extend existing Paragraph feature,
	* 		classes: 'highlighted'                       // with 'highlighted' class,
	* 		attributes: [
	* 			{ key: 'data-i18n-context, value: true } // and i18n attribute.
	* 		]
	* 	}
	* ];
	* ```
	*/
	allow?: Array<MatcherObjectPattern>;
	/**
	* The configuration of disallowed content rules used by General HTML Support.
	*
	* Setting this configuration option will disable listed HTML features.
	*
	* ```ts
	* const htmlSupportConfig.disallow = [
	* 	{
	* 		name: /[\s\S]+/    // For every HTML feature,
	* 		attributes: {
	* 			key: /^on.*$/ // disable 'on*' attributes, like 'onClick', 'onError' etc.
	* 		}
	* 	}
	* ];
	* ```
	*/
	disallow?: Array<MatcherObjectPattern>;
	/**
	* The configuration of allowed empty inline elements that should not be removed.
	*
	* Note that you should also add an appropriate entry to {@link #allow} list.
	*
	* ```ts
	* const htmlSupportConfig.allowEmpty = [ 'i', 'span' ];
	* ```
	*/
	allowEmpty?: Array<string>;
	/**
	* Whether a filler text (non-breaking space entity — `&nbsp;`) will be inserted into empty block elements in HTML output.
	* This is used to render block elements properly with line-height.
	*
	* When set to `true`, empty blocks will be preserved in the editing view.
	* When `false` (default), empty blocks are only preserved in the data output.
	*
	* The option is used by the {@link module:html-support/emptyblock~EmptyBlock} feature.
	*
	* @default false
	*/
	preserveEmptyBlocksInEditingView?: boolean;
	/**
	* The configuration of the Full page editing feature.
	* The option is used by the {@link module:html-support/fullpage~FullPage} feature.
	*
	* ```ts
	* ClassicEditor
	* 	.create( {
	* 		htmlSupport: {
	* 			fullPage: ... // Full page feature config.
	* 		}
	* 	} )
	* 	.then( ... )
	* 	.catch( ... );
	* ```
	*/
	fullPage?: GHSFullPageConfig;
	/**
	* Controls the `sandbox` attribute on iframe elements by specifying allowed sandbox flags.
	*
	* **Note:** This option only affects the editing view and does not modify the data output.
	*
	* When set to `false`:
	*
	* * The sandbox attribute will not be modified or added to iframe elements.
	*
	* When set to `true`:
	*
	* * All restrictions are enforced by adding an empty `sandbox` attribute to iframe elements.
	*
	* When set to an array of strings:
	*
	* * Only the specified sandbox flags will be preserved on iframe elements.
	* * Any sandbox flags not in the list will be automatically removed.
	* * If an empty array is provided, the `sandbox` attribute will be added with no flags (enforcing all restrictions).
	*
	* ```ts
	* ClassicEditor
	* 	.create( {
	* 		htmlSupport: {
	* 			// All restrictions are enforced (empty sandbox attribute).
	* 			htmlIframeSandbox: true
	* 		}
	* 	} )
	* 	.then( ... )
	* 	.catch( ... );
	* ```
	*
	* @default true
	*/
	htmlIframeSandbox?: boolean | Array<string>;
}
/**
* The configuration of the Full page editing feature.
*/
export interface GHSFullPageConfig {
	/**
	* Whether the feature should allow the editor to render styles from the `<head>` section of editor data content.
	*
	* When set to `true`, the editor will render styles from the `<head>` section of editor data content.
	*
	* ```ts
	* ClassicEditor
	* 	.create( {
	* 		htmlSupport: {
	* 			fullPage: {
	* 				allowRenderStylesFromHead: true
	* 			}
	* 		}
	* 	} )
	* 	.then( ... )
	* 	.catch( ... );
	* ```
	*
	* @default false
	*/
	allowRenderStylesFromHead?: boolean;
	/**
	* Callback used to sanitize the CSS provided by the user in editor content
	* when option `htmlSupport.fullPage.allowRenderStylesFromHead` is set to `true`.
	*
	* We strongly recommend overwriting the default function to avoid XSS vulnerabilities.
	*
	* The function receives the CSS (as a string), and should return an object
	* that matches the {@link module:html-support/generalhtmlsupportconfig~GHSCssSanitizeOutput} interface.
	*
	* ```ts
	* ClassicEditor
	* 	.create( {
	* 		htmlSupport: {
	* 			fullPage: {
	* 				allowRenderStylesFromHead: true,
	*
	* 				sanitizeCss( CssString ) {
	* 					const sanitizedCss = sanitize( CssString );
	*
	* 					return {
	* 						css: sanitizedCss,
	* 						// true or false depending on whether the sanitizer stripped anything.
	* 						hasChanged: ...
	* 					};
	* 				}
	* 			}
	* 		}
	* 	} )
	* 	.then( ... )
	* 	.catch( ... );
	* ```
	*
	*/
	sanitizeCss?: (css: string) => GHSCssSanitizeOutput;
}
export interface GHSCssSanitizeOutput {
	/**
	* An output (safe) CSS that will be inserted into the document.
	*/
	css: string;
	/**
	* A flag that indicates whether the output CSS is different than the input value.
	*/
	hasChanged: boolean;
}