Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
import {
ContextualBalloon, type Editor, KeystrokeHandler, type Locale, View, type ViewRange
} from "ckeditor5";
/**
* A balloon at the caret with content rendered by the host application. The editor places the
* balloon and takes it down; the host renders its own component into the balloon's element.
*
* The plugin that creates it must require `ContextualBalloon`.
*/
export default class HostedBalloon {
private readonly editor: Editor;
private readonly className: string;
private readonly balloon: ContextualBalloon;
private view: HostedBalloonView | null = null;
private release: (() => void) | null = null;
private resizeObserver: ResizeObserver | null = null;
private repositionFrame = 0;
/** `className` is set on the element the host renders into. */
constructor(editor: Editor, className: string) {
this.editor = editor;
this.className = className;
this.balloon = editor.plugins.get(ContextualBalloon);
// Esc reaches the editor only while the caret has focus, and the host's content takes
// focus away, so `HostedBalloonView` registers a handler of its own.
editor.keystrokes.set("Esc", (_data, cancel) => {
if (this.view) {
this.hide();
cancel();
}
});
}
/**
* Opens the balloon at the caret and calls `render` with the element to render into. `render`
* returns the function that removes the rendered content, or `null` when the host shows the
* content somewhere else, which closes the balloon again. Does nothing while it is open.
*/
show(render: (container: HTMLElement) => (() => void) | null) {
const editor = this.editor;
const editorEl = editor.editing.view.getDomRoot();
const shownAt = editor.editing.view.document.selection.getFirstRange();
if (this.view || !editorEl || !shownAt) {
return;
}
const view = new HostedBalloonView(editor.locale, this.className);
view.keystrokes.set("Esc", (_data, cancel) => {
this.hide();
editor.editing.view.focus();
cancel();
});
// Wired per view rather than once: the handler listens through the view, so destroying
// the view on the way out stops it. It listens in the capture phase because link previews
// and content embeds stop presses from bubbling, to keep them from CKEditor.
view.listenTo(document, "mousedown", (_evt, domEvent) => {
// The balloon renders its panel as the editor starts up.
const keepOpen = [
this.balloon.view.element as HTMLElement, ...getHostLayers(editor, editorEl)
];
if (!keepOpen.some((element) => element.contains(domEvent.target as Node))) {
this.hide();
}
}, { useCapture: true });
this.balloon.add({ view, position: getBalloonPosition(editor, shownAt) });
this.view = view;
const container = view.element;
/* v8 ignore next 4 -- the balloon renders the view as it adds it, so it has an element */
if (!container) {
this.hide();
return;
}
const release = render(container);
if (!release) {
this.hide();
return;
}
this.release = release;
// The host renders into the container only after `render` returns, and a balloon placed
// around an empty container puts its arrow half the content's width from the caret.
// Reposition on every size change, not just the first render. The reposition waits for
// the next frame because it can change the container's width, which Chrome reports as an
// observer loop.
this.resizeObserver = new ResizeObserver(() => {
cancelAnimationFrame(this.repositionFrame);
this.repositionFrame = requestAnimationFrame(() => {
/* v8 ignore next -- disconnecting the observer cancels the pending frames */
if (this.view) {
this.balloon.updatePosition();
}
});
});
this.resizeObserver.observe(container);
}
/** Removes the host's content and closes the balloon. Does nothing while it is closed. */
hide() {
const view = this.view;
this.view = null;
this.resizeObserver?.disconnect();
this.resizeObserver = null;
cancelAnimationFrame(this.repositionFrame);
this.release?.();
this.release = null;
if (!view) {
return;
}
/* v8 ignore next -- a view this balloon still references is one the balloon still has */
if (this.balloon.hasView(view)) {
this.balloon.remove(view);
}
view.destroy();
}
}
/**
* The view inside the balloon: an element for the host to render into, and nothing else.
*
* It has `ck-reset_all-excluded` because everything a balloon shows sits inside the body
* collection's `ck-reset_all`, which would strip the application's own styling from the content.
*/
class HostedBalloonView extends View {
public readonly keystrokes = new KeystrokeHandler();
constructor(locale: Locale, className: string) {
super(locale);
this.setTemplate({
tag: "div",
attributes: {
class: [ "ck-reset_all-excluded", className ]
}
});
}
public override render() {
super.render();
/* v8 ignore next 3 -- `render()` is what builds the element, so it is never absent here */
if (!this.element) {
return;
}
this.keystrokes.listenTo(this.element);
}
public override destroy() {
super.destroy();
this.keystrokes.destroy();
}
}
/**
* The elements matching `hostedBalloon.keepOpenSelector` that do not hold the editor, such as a
* list of suggestions that the host's content renders in the page's body.
*/
function getHostLayers(editor: Editor, editorEl: HTMLElement): Element[] {
const selector = editor.config.get("hostedBalloon")?.keepOpenSelector;
if (!selector) {
return [];
}
return [ ...document.querySelectorAll(selector) ].filter((layer) => !layer.contains(editorEl));
}
/** Where the balloon points: the caret, read again on every placement, as the emoji picker does. */
function getBalloonPosition(editor: Editor, shownAt: ViewRange) {
const view = editor.editing.view;
return {
target: () => {
/* v8 ignore next -- a rendered document always has a range for the caret */
const range = view.document.selection.getFirstRange() ?? shownAt;
return view.domConverter.viewRangeToDom(range);
}
};
}
declare module "ckeditor5" {
interface EditorConfig {
hostedBalloon?: {
/**
* Matches the host's floating layers, which render outside the balloon. A press in
* one keeps the balloon open, unless the layer holds the editor, as a dialog around it
* does.
*/
keepOpenSelector: string;
};
}
}