RTL-Aware Mention Balloon

Implement a mention-enabled editing helper that keeps the suggestion dropdown anchored to the caret using contextual balloon positioning with right-to-left aware fallbacks. The helper should rely on the provided mention package rather than manual DOM math.

Capabilities

LTR caret anchoring

• When typing a marker in a left-to-right block, the mention dropdown opens just below the caret and, when there is not enough space beneath, flips above without drifting away from the caret horizontally. @test

RTL fallback alignment

• In right-to-left blocks, the dropdown mirrors the anchor horizontally (opening on the caret's right edge) and falls back to the opposite vertical side when the preferred slot is blocked. @test

Continuous repositioning

• As the user moves the caret, scrolls, or resizes the viewport while a lookup is active, the dropdown repositions to the new caret coordinates instead of using stale geometry. @test

Hide when inactive

• If the marker text is deleted, the feed yields no matches, or the editor loses focus, the dropdown hides and does not leave a floating balloon behind. @test

Implementation

@generates

API

export interface MentionFeedInput {
    marker: string;
    feed: string[] | ( ( query: string ) => Promise<Array<string | { id: string; text?: string }>> );
    minimumCharacters?: number;
    dropdownLimit?: number;
}

export interface MentionBalloonConfig {
    element: HTMLElement;
    feeds: MentionFeedInput[];
    enableRtl?: boolean;
}

export interface MentionBalloonController {
    destroy(): Promise<void>;
    /** Returns the last positioned balloon slot (e.g., 'below' or 'above') for testing. */
    getLastPosition(): string | undefined;
}

export async function setupMentionBalloon( config: MentionBalloonConfig ): Promise<MentionBalloonController>;

Dependencies { .dependencies }

@ckeditor/ckeditor5-mention { .dependency }

Provides mention detection, contextual balloon positioning, and dropdown interactions with RTL-aware fallbacks.