@ckeditor/ckeditor5-export-word 48.2.0 → 48.3.0-alpha.1

package/dist/exportword.d.ts

@@ -1,360 +1,360 @@
 /**
- * @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
- */
+* @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 export-word/exportword
- * @publicApi
- */
-import { Plugin, type Editor } from '@ckeditor/ckeditor5-core';
-import { Notification } from '@ckeditor/ckeditor5-ui';
-import { CloudServices, type InitializedToken, type TokenUrl } from '@ckeditor/ckeditor5-cloud-services';
-import { ExportWordUI } from './exportwordui.js';
+* @module export-word/exportword
+* @publicApi
+*/
+import { Plugin, type Editor, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { Notification } from "@ckeditor/ckeditor5-ui";
+import { CloudServices, type InitializedToken, type TokenUrl } from "@ckeditor/ckeditor5-cloud-services";
+import { ExportWordUI } from "./exportwordui.js";
 /**
- * The export to Word feature.
- *
- * It allows you to generate a Word file directly from the editor content.
- *
- * For a detailed overview, check the {@glink features/converters/export-word export to Word} feature documentation.
- */
+* The export to Word feature.
+*
+* It allows you to generate a Word file directly from the editor content.
+*
+* For a detailed overview, check the {@glink features/converters/export-word export to Word} feature documentation.
+*/
 export declare class ExportWord extends Plugin {
-    /**
-     * @inheritDoc
-     */
-    static get pluginName(): "ExportWord";
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin(): true;
-    /**
-     * @inheritDoc
-     */
-    static get isPremiumPlugin(): true;
-    /**
-     * @inheritDoc
-     */
-    static get requires(): readonly [typeof CloudServices, typeof Notification, typeof ExportWordUI];
-    /**
-     * @inheritDoc
-     */
-    init(): void;
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "ExportWord";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static override get isPremiumPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static get requires(): PluginDependenciesOf<[CloudServices, Notification, ExportWordUI]>;
+	/**
+	* @inheritDoc
+	*/
+	init(): void;
 }
 /**
- * The configuration of the export to Word feature. It is used by the Word export features from
- * the `@ckeditor/ckeditor5-export-word` package.
- *
- * ```ts
- * ClassicEditor
- * 	.create( {
- * 		exportWord: ... // Export to Word feature options.
- * 	} )
- * 	.then( ... )
- * 	.catch( ... );
- * ```
- *
- * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
- */
+* The configuration of the export to Word feature. It is used by the Word export features from
+* the `@ckeditor/ckeditor5-export-word` package.
+*
+* ```ts
+* ClassicEditor
+* 	.create( {
+* 		exportWord: ... // Export to Word feature options.
+* 	} )
+* 	.then( ... )
+* 	.catch( ... );
+* ```
+*
+* See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+*/
 export interface ExportWordConfig {
-    /**
-     * Paths to the `.css` files containing additional styling for the editor's content (**the order of provided items matters**).
-     *
-     * ```ts
-     * const exportWordConfig = {
-     * 	stylesheets: [ './path/to/custom-style.css' ]
-     * }
-     * ```
-     *
-     * **Default editor's content styles**:
-     * {@glink getting-started/setup/css The default editor content styles}
-     * are applied to the generated Word file thanks to the `'EDITOR_STYLES'` token, which is provided to the `stylesheets` by default.
-     * If you don't want them to be applied, you have to omit the token:
-     *
-     * **NOTE:** The `'EDITOR_STYLES'` string is only supported in legacy custom builds with webpack or DLLs.
-     * In other setups you always need to pass the stylesheets.
-     *
-     * ```ts
-     * const exportWordConfig = {
-     * 	stylesheets: [ './path/to/custom-editor-styles.css' ]
-     * }
-     * ```
-     *
-     * **Custom styling:** For more advanced styling, your configuration should look like this:
-     *
-     * ```ts
-     * const exportWordConfig = {
-     * 	stylesheets: [
-     * 		'./path/to/editor-styles.css',
-     * 		'./path/to/custom-styles.css'
-     * 	]
-     * }
-     * ```
-     *
-     * @default `[ 'EDITOR_STYLES' ]`
-     */
-    stylesheets?: Array<string>;
-    /**
-     * The name of the generated Word file.
-     *
-     * ```ts
-     * // Static file name.
-     * const exportWordConfig = {
-     * 	fileName: 'my-document.docx'
-     * }
-     *
-     *
-     * // Dynamic file name.
-     * const exportWordConfig = {
-     * 	fileName: () => {
-     * 		const articleTitle = document.querySelector( '#title' );
-     *
-     * 		return `${ articleTitle.value }.docx`;
-     * 	}
-     * }
-     * ```
-     *
-     * **NOTE:** The file name must contain the `.docx` extension.
-     * Otherwise your operating system or device may have trouble identifying the file type.
-     *
-     * @default 'document.docx'
-     */
-    fileName?: string | (() => string);
-    /**
-     * A URL to the Docx converter.
-     *
-     * ```ts
-     * const exportWordConfig = {
-     * 	converterUrl: 'https://myconverter.com/v2/'
-     * }
-     * ```
-     *
-     * **NOTE:** The plugin uses the default HTML to Word converter delivered by CKEditor Cloud Services.
-     * You can provide a URL to an on-premises converter instead.
-     *
-     * @default 'https://docx-converter.cke-cs.com/v2/convert/html-docx'
-     */
-    converterUrl?: string;
-    /**
-     * The CKEditor Cloud Services HTML to DOCX Converter [configuration options](https://docx-converter.cke-cs.com/docs#section/Options).
-     *
-     * **NOTE:** Configuring the plugin is not mandatory.
-     *
-     * ```ts
-     * const exportWordConfig = {
-     * 	converterOptions: {
-     * 		...
-     * 	}
-     * }
-     * ```
-     *
-     * @default `{
-     *  document: {
-     * 		size: 'A4',
-     * 		orientation: 'portrait',
-     * 		language: editor.locale.contentLanguage,
-     * 		margin: {
-     * 			top: '1in',
-     * 			bottom: '1in',
-     * 			right: '1in',
-     * 			left: '1in'
-     * 		}
-     * 	}
-     * 	headers: undefined,
-     * 	footers: undefined,
-     * 	auto_pagination: false,
-     * 	base_url: undefined,
-     * 	extra_http_headers: undefined
-     * }`
-     */
-    converterOptions?: ExportWordConverterOptions | ExportWordConverterOptionsV2;
-    /**
-     * A function to gather the HTML to be converted to Word.
-     *
-     * **NOTE:** This option may be useful when the editor does not have a `getData()` method,
-     * or if the HTML to be converted should be different than the edited one.
-     *
-     * ```ts
-     * const exportWordConfig = {
-     * 	dataCallback: ( editor ) => {
-     * 		return `
-     * 			<header id="header">${ editor.data.get( { rootName: 'header' } ) }</header>
-     * 			<div id="content">${ editor.data.get( { rootName: 'content' } ) }</div>
-     * 		`;
-     * 	}
-     * }
-     * ```
-     *
-     * @default `( editor ) => editor.getData( { pagination: true } )
-     *
-     * If using the {@glink features/pagination/pagination pagination} feature, the `pagination:true` option inserts additional markers into
-     * editor's data. Thanks to that, the Docx converter creates a Word document similar to what is displayed in the editor.
-     */
-    dataCallback?: (editor: Editor) => string;
-    /**
-     * A token URL or a token request function. This field is optional and should be used only when a different `tokenUrl` is required for
-     * the export to Word feature.
-     *
-     * **Note:** The token can be disabled with the `false` value provided.
-     *
-     * See: {@link module:cloud-services/cloudservicesconfig~CloudServicesConfig#tokenUrl}
-     */
-    tokenUrl?: TokenUrl | false;
-    /**
-     * The authentication token.
-     *
-     * See: {@link module:cloud-services/cloudservices~CloudServices#token}
-     */
-    token?: InitializedToken;
-    /**
-     * The version of `Export to Word` API.
-     *
-     * @default '2'
-     */
-    version?: 1 | 2;
-    /**
-     * The watermark configuration.
-     *
-     * ```ts
-     * 	converterOptions: {
-     *		watermark: {
-     *			source: 'https://placehold.co/200',
-     *			width: '500px',
-     *			height: '600px',
-     *			washout: 'false'
-     *		}
-     *	}
-     * ```
-     *
-     * The watermark configuration is represented as an object containing 4 properties:
-     *
-     * - `source`: A source of the image used for the watermark.
-     * - `width`: A string value representing the width of the watermark.
-     * - `height`: A string value representing the height of the watermark.
-     * - `washout`: Determines whether the washout effect should be applied. Optional - the default value is `false`.
-     *
-     */
-    watermark?: ExportWordConverterWatermarkV2;
+	/**
+	* Paths to the `.css` files containing additional styling for the editor's content (**the order of provided items matters**).
+	*
+	* ```ts
+	* const exportWordConfig = {
+	* 	stylesheets: [ './path/to/custom-style.css' ]
+	* }
+	* ```
+	*
+	* **Default editor's content styles**:
+	* {@glink getting-started/setup/css The default editor content styles}
+	* are applied to the generated Word file thanks to the `'EDITOR_STYLES'` token, which is provided to the `stylesheets` by default.
+	* If you don't want them to be applied, you have to omit the token:
+	*
+	* **NOTE:** The `'EDITOR_STYLES'` string is only supported in legacy custom builds with webpack or DLLs.
+	* In other setups you always need to pass the stylesheets.
+	*
+	* ```ts
+	* const exportWordConfig = {
+	* 	stylesheets: [ './path/to/custom-editor-styles.css' ]
+	* }
+	* ```
+	*
+	* **Custom styling:** For more advanced styling, your configuration should look like this:
+	*
+	* ```ts
+	* const exportWordConfig = {
+	* 	stylesheets: [
+	* 		'./path/to/editor-styles.css',
+	* 		'./path/to/custom-styles.css'
+	* 	]
+	* }
+	* ```
+	*
+	* @default `[ 'EDITOR_STYLES' ]`
+	*/
+	stylesheets?: Array<string>;
+	/**
+	* The name of the generated Word file.
+	*
+	* ```ts
+	* // Static file name.
+	* const exportWordConfig = {
+	* 	fileName: 'my-document.docx'
+	* }
+	*
+	*
+	* // Dynamic file name.
+	* const exportWordConfig = {
+	* 	fileName: () => {
+	* 		const articleTitle = document.querySelector( '#title' );
+	*
+	* 		return `${ articleTitle.value }.docx`;
+	* 	}
+	* }
+	* ```
+	*
+	* **NOTE:** The file name must contain the `.docx` extension.
+	* Otherwise your operating system or device may have trouble identifying the file type.
+	*
+	* @default 'document.docx'
+	*/
+	fileName?: string | (() => string);
+	/**
+	* A URL to the Docx converter.
+	*
+	* ```ts
+	* const exportWordConfig = {
+	* 	converterUrl: 'https://myconverter.com/v2/'
+	* }
+	* ```
+	*
+	* **NOTE:** The plugin uses the default HTML to Word converter delivered by CKEditor Cloud Services.
+	* You can provide a URL to an on-premises converter instead.
+	*
+	* @default 'https://docx-converter.cke-cs.com/v2/convert/html-docx'
+	*/
+	converterUrl?: string;
+	/**
+	* The CKEditor Cloud Services HTML to DOCX Converter [configuration options](https://docx-converter.cke-cs.com/docs#section/Options).
+	*
+	* **NOTE:** Configuring the plugin is not mandatory.
+	*
+	* ```ts
+	* const exportWordConfig = {
+	* 	converterOptions: {
+	* 		...
+	* 	}
+	* }
+	* ```
+	*
+	* @default `{
+	*  document: {
+	* 		size: 'A4',
+	* 		orientation: 'portrait',
+	* 		language: editor.locale.contentLanguage,
+	* 		margin: {
+	* 			top: '1in',
+	* 			bottom: '1in',
+	* 			right: '1in',
+	* 			left: '1in'
+	* 		}
+	* 	}
+	* 	headers: undefined,
+	* 	footers: undefined,
+	* 	auto_pagination: false,
+	* 	base_url: undefined,
+	* 	extra_http_headers: undefined
+	* }`
+	*/
+	converterOptions?: ExportWordConverterOptions | ExportWordConverterOptionsV2;
+	/**
+	* A function to gather the HTML to be converted to Word.
+	*
+	* **NOTE:** This option may be useful when the editor does not have a `getData()` method,
+	* or if the HTML to be converted should be different than the edited one.
+	*
+	* ```ts
+	* const exportWordConfig = {
+	* 	dataCallback: ( editor ) => {
+	* 		return `
+	* 			<header id="header">${ editor.data.get( { rootName: 'header' } ) }</header>
+	* 			<div id="content">${ editor.data.get( { rootName: 'content' } ) }</div>
+	* 		`;
+	* 	}
+	* }
+	* ```
+	*
+	* @default `( editor ) => editor.getData( { pagination: true } )
+	*
+	* If using the {@glink features/pagination/pagination pagination} feature, the `pagination:true` option inserts additional markers into
+	* editor's data. Thanks to that, the Docx converter creates a Word document similar to what is displayed in the editor.
+	*/
+	dataCallback?: (editor: Editor) => string;
+	/**
+	* A token URL or a token request function. This field is optional and should be used only when a different `tokenUrl` is required for
+	* the export to Word feature.
+	*
+	* **Note:** The token can be disabled with the `false` value provided.
+	*
+	* See: {@link module:cloud-services/cloudservicesconfig~CloudServicesConfig#tokenUrl}
+	*/
+	tokenUrl?: TokenUrl | false;
+	/**
+	* The authentication token.
+	*
+	* See: {@link module:cloud-services/cloudservices~CloudServices#token}
+	*/
+	token?: InitializedToken;
+	/**
+	* The version of `Export to Word` API.
+	*
+	* @default '2'
+	*/
+	version?: 1 | 2;
+	/**
+	* The watermark configuration.
+	*
+	* ```ts
+	* 	converterOptions: {
+	*		watermark: {
+	*			source: 'https://placehold.co/200',
+	*			width: '500px',
+	*			height: '600px',
+	*			washout: 'false'
+	*		}
+	*	}
+	* ```
+	*
+	* The watermark configuration is represented as an object containing 4 properties:
+	*
+	* - `source`: A source of the image used for the watermark.
+	* - `width`: A string value representing the width of the watermark.
+	* - `height`: A string value representing the height of the watermark.
+	* - `washout`: Determines whether the washout effect should be applied. Optional - the default value is `false`.
+	*
+	*/
+	watermark?: ExportWordConverterWatermarkV2;
 }
 export type ExportWordConverterOptions = {
-    format?: ExportWordConverterFormatOption;
-    margin_top?: string;
-    margin_bottom?: string;
-    margin_right?: string;
-    margin_left?: string;
-    header?: ExportWordConverterHeaderFooterOption;
-    footer?: ExportWordConverterHeaderFooterOption;
-    comments?: ExportWordConverterCommentsOption;
-    suggestions?: ExportWordConverterSuggestionsOption;
-    orientation?: ExportWordConverterOrientationOption;
-    auto_pagination?: boolean;
-    base_url?: string;
+	format?: ExportWordConverterFormatOption;
+	margin_top?: string;
+	margin_bottom?: string;
+	margin_right?: string;
+	margin_left?: string;
+	header?: ExportWordConverterHeaderFooterOption;
+	footer?: ExportWordConverterHeaderFooterOption;
+	comments?: ExportWordConverterCommentsOption;
+	suggestions?: ExportWordConverterSuggestionsOption;
+	orientation?: ExportWordConverterOrientationOption;
+	auto_pagination?: boolean;
+	base_url?: string;
 };
-export type ExportWordConverterFormatOption = 'Letter' | 'Legal' | 'Tabloid' | 'Statement' | 'Executive' | 'A3' | 'A4' | 'A5' | 'A6' | 'B4' | 'B5' | string & Record<never, never>;
-export type ExportWordConverterOrientationOption = 'portrait' | 'landscape' | string & Record<never, never>;
+export type ExportWordConverterFormatOption = "Letter" | "Legal" | "Tabloid" | "Statement" | "Executive" | "A3" | "A4" | "A5" | "A6" | "B4" | "B5" | string & Record<never, never>;
+export type ExportWordConverterOrientationOption = "portrait" | "landscape" | string & Record<never, never>;
 export type ExportWordConverterHeaderFooterOption = Array<{
-    html?: string;
-    css?: string;
-    type?: 'default' | 'even' | 'odd' | 'first' | string & Record<never, never>;
+	html?: string;
+	css?: string;
+	type?: "default" | "even" | "odd" | "first" | string & Record<never, never>;
 }>;
 export type ExportWordConverterCommentsOption = {
-    [id: string]: Array<{
-        author: string;
-        created: Date;
-        content?: string;
-        is_resolved: boolean;
-    }>;
+	[id: string]: Array<{
+		author: string;
+		created: Date;
+		content?: string;
+		is_resolved: boolean;
+	}>;
 };
 export type ExportWordConverterSuggestionsOption = {
-    [id: string]: {
-        author: string;
-        created: Date | null;
-    };
+	[id: string]: {
+		author: string;
+		created: Date | null;
+	};
 };
 export type ExportWordConverterOptionsV2 = {
-    document?: ExportWordConverterDocumentOptionsV2;
-    headers?: ExportWordConverterHeaderFooterOptionsV2;
-    footers?: ExportWordConverterHeaderFooterOptionsV2;
-    extra_http_headers?: ExportWordConverterExtraHttpHeaders;
-    base_url?: string;
-    auto_pagination?: boolean;
-    watermark?: ExportWordConverterWatermarkV2;
+	document?: ExportWordConverterDocumentOptionsV2;
+	headers?: ExportWordConverterHeaderFooterOptionsV2;
+	footers?: ExportWordConverterHeaderFooterOptionsV2;
+	extra_http_headers?: ExportWordConverterExtraHttpHeaders;
+	base_url?: string;
+	auto_pagination?: boolean;
+	watermark?: ExportWordConverterWatermarkV2;
 };
 export type ExportWordConverterDocumentOptionsV2 = {
-    margins?: ExportWordConverterMarginsOptionsV2;
-    size?: ExportWordConverterFormatOptionsV2;
-    orientation?: ExportWordConverterOrientationOptionsV2;
-    language?: string;
+	margins?: ExportWordConverterMarginsOptionsV2;
+	size?: ExportWordConverterFormatOptionsV2;
+	orientation?: ExportWordConverterOrientationOptionsV2;
+	language?: string;
 };
 export type ExportWordConverterMarginsOptionsV2 = {
-    top?: string;
-    right?: string;
-    bottom?: string;
-    left?: string;
+	top?: string;
+	right?: string;
+	bottom?: string;
+	left?: string;
 };
 export type ExportWordConverterHeaderFooterOptionsV2 = {
-    first?: ExportWordConverterHeaderFooterItemOptionsV2;
-    odd?: ExportWordConverterHeaderFooterItemOptionsV2;
-    even?: ExportWordConverterHeaderFooterItemOptionsV2;
-    default?: ExportWordConverterHeaderFooterItemOptionsV2;
+	first?: ExportWordConverterHeaderFooterItemOptionsV2;
+	odd?: ExportWordConverterHeaderFooterItemOptionsV2;
+	even?: ExportWordConverterHeaderFooterItemOptionsV2;
+	default?: ExportWordConverterHeaderFooterItemOptionsV2;
 };
 export type ExportWordConverterWatermarkV2 = {
-    source?: string;
-    width?: string;
-    height?: string;
-    washout?: boolean;
+	source?: string;
+	width?: string;
+	height?: string;
+	washout?: boolean;
 };
 /**
- * If fetching some resources (e.g. images) used in a generated Word requires passing an additional
- * authorization factor in the form of additional HTTP headers:
- *
- * ```
- * extra_http_headers: {
- * 		'https://ckeditor.com': {
- * 			authorization: 'Bearer xxx'
- * 		},
- * 		'https://example.com': {
- * 			authorization: 'Bearer xxx'
- * 		},
- * }
- * ```
- */
+* If fetching some resources (e.g. images) used in a generated Word requires passing an additional
+* authorization factor in the form of additional HTTP headers:
+*
+* ```
+* extra_http_headers: {
+* 		'https://ckeditor.com': {
+* 			authorization: 'Bearer xxx'
+* 		},
+* 		'https://example.com': {
+* 			authorization: 'Bearer xxx'
+* 		},
+* }
+* ```
+*/
 export type ExportWordConverterExtraHttpHeaders = {
-    [domain: string]: ExportWordConverterExtraHttpHeadersHeader;
+	[domain: string]: ExportWordConverterExtraHttpHeadersHeader;
 };
 export type ExportWordConverterExtraHttpHeadersHeader = {
-    [header: string]: string;
+	[header: string]: string;
 };
 export type ExportWordConverterHeaderFooterItemOptionsV2 = {
-    html?: string;
-    css?: string;
+	html?: string;
+	css?: string;
 };
-export type ExportWordConverterOrientationOptionsV2 = 'portrait' | 'landscape' | string & Record<never, never>;
+export type ExportWordConverterOrientationOptionsV2 = "portrait" | "landscape" | string & Record<never, never>;
 export type ExportWordConverterFormatOptionsV2 = ExportWordConverterPredifinedFormatOptionsV2 | ExportWordConverterCustomFormatOptionsV2;
-export type ExportWordConverterPredifinedFormatOptionsV2 = 'Letter' | 'Legal' | 'Tabloid' | 'Statement' | 'Executive' | 'A3' | 'A4' | 'A5' | 'A6' | 'B4' | 'B5' | string & Record<never, never>;
+export type ExportWordConverterPredifinedFormatOptionsV2 = "Letter" | "Legal" | "Tabloid" | "Statement" | "Executive" | "A3" | "A4" | "A5" | "A6" | "B4" | "B5" | string & Record<never, never>;
 export type ExportWordConverterCustomFormatOptionsV2 = {
-    width?: string;
-    height?: string;
+	width?: string;
+	height?: string;
 };
 export type ExportWordConverterCollaborationFeaturesOptionsV2 = {
-    comment_threads?: ExportWordConverterCommentsThreadOptionsV2;
-    suggestions?: ExportWordConverterSuggestionsOptionsV2;
+	comment_threads?: ExportWordConverterCommentsThreadOptionsV2;
+	suggestions?: ExportWordConverterSuggestionsOptionsV2;
 };
 export type ExportWordConverterCommentsThreadOptionsV2 = Array<{
-    thread_id: string;
-    is_resolved: boolean;
-    comments: ExportWordConverterCommentsV2;
+	thread_id: string;
+	is_resolved: boolean;
+	comments: ExportWordConverterCommentsV2;
 }>;
 export type ExportWordConverterCommentsV2 = Array<{
-    author: string;
-    created_at: Date;
-    content: string;
+	author: string;
+	created_at: Date;
+	content: string;
 }>;
 export type ExportWordConverterSuggestionsOptionsV2 = Array<{
-    id: string;
-    author: string;
-    created_at: Date | null;
+	id: string;
+	author: string;
+	created_at: Date | null;
 }>;
 export type ExportWordConverterMergeFieldsOptionsV2 = {
-    prefix: string;
-    suffix: string;
-    data?: Record<string, string>;
+	prefix: string;
+	suffix: string;
+	data?: Record<string, string>;
 };