@ckeditor/ckeditor5-ai/src/aicore/utils/htmlstreamer.d.ts

AI features for CKEditor 5.

/**
 * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
 * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
 */
import { type Document } from './htmlparser.js';
/**
 * A class that streams arbitrary HTML content into a target DOM element in an incremental manner.
 *
 * It uses a virtual DOM to avoid flickering of images and other dynamic content.
 */
export declare class HTMLStreamer {
    /**
     * Creates an instance of HTMLStreamer.
     */
    constructor(options: HTMLStreamerOptions);
    /**
     * Incrementally streams the HTML string into provided target DOM element.
     *
     * **Note**: This method can be called repeatedly with a new document to continue the previous call. The new parsed document
     * must be an extension of the previous document (only growing, never shrinking).
     *
     * ## Basic example
     *
     * ```ts
     * const document = parse( '<p>foo bar</p>' );
     *
     * const htmlStreamer = new HTMLStreamer( {
     * 	targetElement,
     * 	textNodeStyle: 'animation: my-animation .5s'
     * } );
     *
     * await htmlStreamer.stream( { document } );
     * ```
     *
     * after 20ms will stream:
     *
     * ```html
     * <p></p>
     * ```
     *
     * and after 40ms:
     *
     * ```html
     * <p><span data-ck-html-streamer-word-chunk="" style="animation: my-animation .5s">foo </span></p>
     * ```
     *
     * and after 60ms:
     *
     * ```html
     * <p>
     * 	<span data-ck-html-streamer-word-chunk="" style="animation: my-animation .5s">foo </span>
     * 	<span data-ck-html-streamer-word-chunk="" style="animation: my-animation .5s">bar</span>
     * </p>
     * ```
     *
     * ## Using paths
     *
     * You can control the streaming process by providing a start and end path. The rest of the parsed document will not
     * be streamed.
     *
     * **Note**: The paths are indices of the nodes in the parsed document. The last segment of the path may be a character position
     * in a text node. Paths that start or end in a text node will be adjusted in such way that only the whole word will be streamed
     * to improve the user experience.
     *
     * ```ts
     * const parsedDocument = parse( '<blockquote><p>foo bar baz qux</p></blockquote>' );
     * 	const htmlStreamer = new HTMLStreamer( {
     * 	targetElement,
     * 	textNodeStyle: 'animation: my-animation .5s'
     * } );
     *
     * await htmlStreamer.stream( {
     * 	document: parsedDocument,
     * 	startPath: [ 0, 0, 0, 6 ], // <blockquote><p>foo ba[r baz qux</p></blockquote>
     * 	endPath: [ 0, 0, 0, 9 ],   // <blockquote><p>foo bar b]az qux</p></blockquote>
     * } );
     * ```
     *
     * will stream:
     *
     * ```html
     * <blockquote>
     * 	<p>
     * 		<span data-ck-html-streamer-word-chunk="" style="animation: my-animation .5s">bar </span>
     * 		<span data-ck-html-streamer-word-chunk="" style="animation: my-animation .5s">baz </span>
     * 	</p>
     * </blockquote>
     * ```
     */
    stream({ document, targetElement, abortSignal }: {
        document: Document;
        targetElement: HTMLElement;
        abortSignal?: AbortSignal;
    }): Promise<void>;
    /**
     * Cleans up the animation `<span>` elements from the configured target element with minimum DOM manipulation.
     */
    cleanUpAnimations({ targetElement }: {
        targetElement: HTMLElement;
    }): void;
    /**
     * Stops the streaming process.
     */
    stop(): void;
}
/**
 * Options for the HTMLStreamer.
 */
interface HTMLStreamerOptions {
    /**
     * Delay between `stream()` updates in milliseconds. Default is 20ms.
     */
    delay?: number;
    /**
     * The `style` attribute value for `<span>` elements that wrap text nodes.
     */
    textNodeStyle: string;
    /**
     * Callback to be called every time the stream is updated.
     */
    onStreamUpdate?: () => void;
}
export {};