/**
 * @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 paste-from-office-enhanced/normalizers/propagator/utils
 */
import type { ViewUpcastWriter, ViewElement } from '@ckeditor/ckeditor5-engine';
/**
 * The list of all `CSS` properties that need to be propagated.
 *
 * @protected
 */
export declare const CSS_PROPERTIES_TO_PROPAGATE: readonly ["color", "font-family", "font-size", "text-decoration", "text-decoration-line", "font-weight", "font-style", "vertical-align"];
/**
 * The list of `CSS` properties that needs to be propagated as an inline `<span>` element.
 *
 * It's a subset of `CSS_PROPERTIES_TO_PROPAGATE`.
 *
 * @protected
 */
export declare const CSS_PROPERTIES_TO_BE_SPANS: readonly ["color", "font-family", "font-size"];
export type CSSPropertyValueAssertion = (value: string) => boolean;
export type CSSPropertyValueToElementNameMap = readonly [string | CSSPropertyValueAssertion, string];
/**
 * The map of style to element propagate as a HTML elements
 * (e.g. `text-decoration` with the `underline` value is propagated to `<u>`,
 * or `font-weight` with the `bold` value is propagated to `<strong>`).
 *
 * @protected
 */
export declare const CSS_PROPERTIES_TO_BE_HTML_ELEMENTS: {
    [key in Exclude<typeof CSS_PROPERTIES_TO_PROPAGATE[number], typeof CSS_PROPERTIES_TO_BE_SPANS[number]>]: ReadonlyArray<CSSPropertyValueToElementNameMap>;
};
/**
 * Checks whether the given property should be propagated at all.
 *
 * @param property
 * @returns
 */
export declare function isPropertyToBePropagated(property: string): property is typeof CSS_PROPERTIES_TO_PROPAGATE[number];
/**
 * Checks whether the given property should be propagated as a span element.
 *
 * @param property
 * @returns
 */
export declare function isPropertyToBePropagatedAsSpan(property: string): property is typeof CSS_PROPERTIES_TO_BE_SPANS[number];
/**
 * Checks whether the given property should be propagated as an HTML element.
 *
 * @param property
 * @returns
 */
export declare function isPropertyToBePropagatedAsHTMLElement(property: string): property is keyof typeof CSS_PROPERTIES_TO_BE_HTML_ELEMENTS;
/**
 * Collects a list of styles to propagate from a block element.
 *
 * @param element The source `ViewElement`.
 * @returns List of valid CSS properties to propagate.
 */
export declare function getStylePropertyNamesToPropagate(element: ViewElement): Array<typeof CSS_PROPERTIES_TO_PROPAGATE[number]>;
/**
 * Executes styles propagation.
 *
 * @param element The source `ViewElement`.
 * @param writer `ViewUpcastWriter` instance.
 * @param propertiesToPropagate List of valid CSS properties to propagate.
 */
export declare function propagateStyleProperties(element: ViewElement, writer: ViewUpcastWriter, propertiesToPropagate: Array<string>): void;
/**
 * Creates an `HTML` structure based on styles propagated from parent block element.
 *
 * @param element The source `ViewElement`.
 * @param writer `ViewUpcastWriter` instance.
 * @param stylesToBeHtmlElements List of styles properties to be propagated as a HTML elements.
 */
export declare function propagateStylesAsHTMLElements(element: ViewElement, writer: ViewUpcastWriter, stylesToBeHtmlElements: Partial<typeof CSS_PROPERTIES_TO_BE_HTML_ELEMENTS>): void;
/**
 * Propagates span styles from a block element to its existing direct `<span>` children, instead of
 * creating a new wrapper `<span>`. Use this for list-item paragraphs where adding a wrapper would
 * shift the span depth and break `findListMarkerNode()` bullet detection. See #6129.
 *
 * HTML-element style properties (`font-weight`, `font-style`, and similar) are intentionally not
 * propagated here — promoting them would require wrapping children in `<strong>`, `<em>`, etc.,
 * which shifts span depth just as much as `propagateStylesAsSpan()` and defeats the purpose.
 *
 * In practice this is safe because Word does not emit `font-weight` / `font-style` / `text-decoration`
 * directly on list-item `<p>` elements — those styles live on inner `<span>` character-style wrappers,
 * which are preserved untouched. They could only land on the `<p>` via a class-based rule like
 * `p.MsoListParagraph { font-weight: bold }` promoted by `MSOfficeStylesInliner`, which standard
 * Word HTML does not produce.
 *
 * @param element The source `ViewElement`.
 * @param writer `ViewUpcastWriter` instance.
 * @param propertiesToPropagate List of valid CSS properties to propagate.
 */
export declare function propagateSpanStylesToExistingChildren(element: ViewElement, writer: ViewUpcastWriter, propertiesToPropagate: Array<string>): void;
/**
 * Creates a `span` as a first child of the `element` with styles propagated from parent block element.
 *
 * @param element The source `ViewElement`.
 * @param writer `ViewUpcastWriter` instance.
 * @param spanStyles List of styles properties to propagate.
 */
export declare function propagateStylesAsSpan(element: ViewElement, writer: ViewUpcastWriter, spanStyles: Partial<Record<typeof CSS_PROPERTIES_TO_BE_SPANS[number], string>>): void;
/**
 * Collects and filters element styles into proper objects for further propagation.
 *
 * @param element The source `ViewElement`.
 * @param propertiesToPropagate The array of style properties to propagate.
 * @returns An object with properties to propagate filtered into styles that will be propagated onto `span` and as a HTML elements.
 */
export declare function getStylesToPropagate(element: ViewElement, propertiesToPropagate: Array<string>): {
    spanStyles: Partial<Record<typeof CSS_PROPERTIES_TO_BE_SPANS[number], string>>;
    stylesToBeHtmlElements: Partial<typeof CSS_PROPERTIES_TO_BE_HTML_ELEMENTS>;
};