/**
 * TextSplitter helpers — non-destructive split upgrades plus the mask-wrapper
 * and gradient-text post-processing passes.
 *
 * These operate on an existing SplitResult / ElementSplitState and never touch
 * the module-level splitStateMap directly (state is passed in by the class).
 */
import type { MaskPadding } from '../../types';
import type { SplitType, SplitOptions, SplitResult, ElementSplitState } from './types';
/**
 * Attempt to upgrade an existing split to satisfy a new type request without
 * destroying existing DOM references.
 *
 * Returns the appropriate span array on success, or null if the upgrade is
 * not possible (caller must fall back to a full revert + re-split).
 */
export declare function tryUpgrade(element: HTMLElement, state: ElementSplitState, type: SplitType, options?: SplitOptions): HTMLElement[] | null;
/**
 * Return the appropriate span array from a SplitResult for the requested type.
 * Chars have highest priority, then words, then lines.
 */
export declare function getSpansForType(result: SplitResult, type: string): HTMLElement[];
/**
 * Build a combined data-split attribute value from existing and requested types,
 * ordered as: lines, words, chars (broadest → most granular).
 */
export declare function buildTypeString(existingTypes: string[], requestedTypes: string[]): string;
/**
 * Walk a word span's text nodes and replace them with individual char spans,
 * appending each new span to the provided `chars` array.
 *
 * Used when upgrading an existing 'words' split to include 'chars'.
 * The word span itself is NOT moved or recreated — only its text node
 * children are swapped out, so existing references to the word span remain valid.
 */
export declare function nestCharsInElement(parent: HTMLElement, chars: HTMLElement[]): void;
/**
 * Wrap each split element in a parent with overflow:hidden for clip-reveal.
 * The wrapper clips content so animating y:'100%' creates a reveal effect.
 *
 * Display and cursive fonts often draw ink outside the glyph advance box.
 * The balanced padding/margin pair expands the clipping area without changing
 * the element's occupied inline layout.
 */
export declare function applyMaskWrappers(result: SplitResult, maskPadding?: MaskPadding): void;
/**
 * Detect if the split element uses `background-clip: text` (gradient text)
 * and propagate the gradient through all generated spans so text stays visible.
 *
 * Without this, inline-block split spans inherit `-webkit-text-fill-color: transparent`
 * but NOT the parent's gradient background, making the text invisible.
 *
 * IMPORTANT: We copy the computed background-image directly instead of using
 * `background: inherit` because `background` is NOT an inherited CSS property.
 * When the split element contains intermediate wrapper elements (e.g.
 * `<h1><span class="line"><span class="accent">word</span></span></h1>`),
 * `inherit` resolves to `none` at each intermediate element, breaking the chain.
 * Copying the resolved value ensures the gradient reaches every split span
 * regardless of DOM depth.
 */
export declare function propagateGradientText(element: HTMLElement, result: SplitResult): void;