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 {
BalloonToolbar, BlockToolbar, ButtonView, DropdownView, type Editor, type FocusTracker,
ListItemGroupView, ListItemView, ListSeparatorView, ListView, Plugin, SearchTextView, SplitButtonView, SwitchButtonView,
type ToolbarConfig, type ToolbarConfigItem, ToolbarSeparatorView, type ToolbarView, type View,
WidgetToolbarRepository
} from "ckeditor5";
import ContextToolbar from "./context_toolbar.js";
import TextFormattingToolbar from "./text_formatting_toolbar.js";
declare module "ckeditor5" {
interface EditorConfig {
toolbarGroupMenu?: {
/** Creates the menu the toolbar groups marked `asMenu` open, once per editor. */
host(editor: Editor): ToolbarGroupMenuHost;
};
}
}
/** Draws the menu of a toolbar group marked `asMenu`. See {@link ToolbarGroupMenu}. */
export interface ToolbarGroupMenuHost {
show(request: ToolbarGroupMenuRequest): void;
hide(): void;
destroy(): void;
/**
* Whether the shown menu takes the place of the on-screen keyboard. Its button then gives that
* place back as it closes the menu, focusing the text in the same press, as a mobile browser
* raises the keyboard only for a focus a press makes.
*/
isInPlaceOfKeyboard?(): boolean;
}
/** What a {@link ToolbarGroupMenuHost} shows a menu for. */
export interface ToolbarGroupMenuRequest {
/** The group's button, which the menu opens under. */
anchor: HTMLElement;
items: ToolbarGroupMenuItem[];
/**
* `tiles` draws the entries as tiles, each its icon over its label, for a list of choices that
* a phone shows better side by side. Left out for rows.
*/
layout?: "tiles";
/**
* Receives the menu's element once it is in the page, and `null` as it leaves. The editor
* counts focus and presses inside that element as its own, so the toolbar holding the group
* stays open.
*/
setElement(element: HTMLElement | null): void;
/**
* Called as the menu closes without running an entry. `returnFocus` puts focus back on the
* group's button, for a menu closed with Escape rather than a press elsewhere.
*/
onClose(returnFocus: boolean): void;
}
export type ToolbarGroupMenuItem = { kind: "separator" } | { kind: "heading"; label: string } | ToolbarGroupMenuEntry;
export interface ToolbarGroupMenuEntry {
kind: "entry";
label: string;
/** The SVG of the icon of the toolbar item. */
icon?: string;
/** An icon-pack glyph as a class list, such as `bx bx-cog`, for an entry with no SVG. */
iconClass?: string;
isEnabled: boolean;
/**
* Whether the item is on, for a button that is on or off, as `bold` is or a row of the
* `heading` list. Left out for any other.
*/
isOn?: boolean;
/** Whether the item is a switch, as the "Header row" row of `tableRow` is, for the host to draw as one. */
isSwitch?: boolean;
/** The classes CKEditor gives the item, such as `ck-fontsize-option text-tiny`, for the host to style. */
className?: string;
/** Runs the toolbar item. An entry with `children` and no action only opens them. */
run?(): void;
children?: ToolbarGroupMenuItem[];
}
/** How a dropdown handed to {@link openListAsMenu} is shown. */
export interface ListMenuOptions {
/** See {@link ToolbarGroupMenuRequest.layout}. */
layout?: "tiles";
/**
* Describes the menu's entries on each open, for a dropdown whose content its views do not
* hold. `run` wraps an entry's action, so the menu hides before it runs.
*/
describe?(run: (action: () => void) => () => void): ToolbarGroupMenuItem[];
}
/** The dropdowns handed to {@link openListAsMenu}, with their options. */
const listMenuDropdowns = new WeakMap<DropdownView, ListMenuOptions>();
/**
* Has {@link ToolbarGroupMenu} open the list of `dropdown` as a menu of its rows, as it does a
* group marked `asMenu`, or the buttons of its toolbar for a dropdown that holds one, as
* `alignment` does. Without the plugin or a host, the dropdown opens its own panel.
*/
export function openListAsMenu(dropdown: DropdownView, options: ListMenuOptions = {}) {
listMenuDropdowns.set(dropdown, options);
}
/** Whether `dropdown` was handed to {@link openListAsMenu}. */
export function isListMenu(dropdown: DropdownView) {
return listMenuDropdowns.has(dropdown);
}
/**
* Opens a toolbar group as a menu drawn by the host application (`toolbarGroupMenu.host`), with a
* row of icon and label per entry, and a submenu for an entry that carries a list of its own.
*
* A group opts in with `asMenu: true` beside its `label` in the toolbar configuration, or with the
* {@link ListMenuOptions} of its menu, such as `asMenu: { layout: "tiles" }`.
* `ToolbarView#_createNestedToolbarDropdown()` builds those dropdowns and keeps no reference to the
* definition each came from, so the labels of the opted-in groups are read from the configuration
* and matched against the dropdown buttons. The dropdown never opens its own panel: the views
* CKEditor lays out in it are described to the host each time it would, and a row runs its view.
* A group holds buttons and dropdowns that list rows. A dropdown handed to {@link openListAsMenu}
* opens as a menu of its own list's rows.
*/
export default class ToolbarGroupMenu extends Plugin {
private watchedDropdowns = new WeakSet<DropdownView>();
private host: ToolbarGroupMenuHost | null = null;
/** The menu the host shows, with the dropdown it stands for, or `null`. */
private shown: { dropdown: DropdownView; request: ToolbarGroupMenuRequest } | null = null;
/** Set while the plugin opens a dropdown itself, to have CKEditor build its views. */
private building = false;
static get pluginName() {
return "ToolbarGroupMenu" as const;
}
afterInit() {
const editor = this.editor;
const groups = collectMenuGroups(
editor.config.get("toolbar"),
editor.config.get("balloonToolbar"),
editor.config.get("blockToolbar"),
editor.config.get("textFormattingToolbar")
);
const menuConfig = editor.config.get("toolbarGroupMenu");
if (!menuConfig) {
return;
}
const createHost = () => menuConfig.host(editor);
const watchToolbar = (toolbar: ToolbarView) => {
for (const item of toolbar.items) {
this.watchGroupDropdown(toolbar, item, groups, createHost);
}
this.listenTo(toolbar.items, "add", (evt, item: View) => {
this.watchGroupDropdown(toolbar, item, groups, createHost);
});
};
for (const toolbar of this.getToolbarViews()) {
watchToolbar(toolbar);
}
// The plugins that own a widget toolbar register it in their own `afterInit()`, which can
// run after this one, and `WidgetToolbarRepository` fills it the first time it shows it.
if (editor.plugins.has(WidgetToolbarRepository)) {
this.listenTo(editor, "ready", () => {
for (const toolbar of getWidgetToolbarViews(editor)) {
watchToolbar(toolbar);
}
});
}
}
destroy() {
super.destroy();
this.host?.destroy();
}
/**
* The toolbars an editor can hold: the fixed bar of a `DecoupledEditor`, the selection balloon
* of a `BalloonEditor`, the block toolbar either of them can carry, the `TextFormattingToolbar`
* and the `ContextToolbar`.
*/
private getToolbarViews() {
const editor = this.editor;
const toolbars: ToolbarView[] = [];
const { toolbar } = editor.ui.view as { toolbar?: ToolbarView };
if (toolbar) {
toolbars.push(toolbar);
}
if (editor.plugins.has(BalloonToolbar)) {
toolbars.push(editor.plugins.get(BalloonToolbar).toolbarView);
}
if (editor.plugins.has(BlockToolbar)) {
toolbars.push(editor.plugins.get(BlockToolbar).toolbarView);
}
if (editor.plugins.has(TextFormattingToolbar)) {
toolbars.push(editor.plugins.get(TextFormattingToolbar).toolbarView);
}
if (editor.plugins.has(ContextToolbar)) {
toolbars.push(editor.plugins.get(ContextToolbar).toolbarView);
}
return toolbars;
}
private watchGroupDropdown(
toolbar: ToolbarView, item: View, groups: Map<string, ListMenuOptions>,
createHost: () => ToolbarGroupMenuHost
) {
if (!(item instanceof DropdownView) || this.watchedDropdowns.has(item)) {
return;
}
const label = item.buttonView.label;
const options = listMenuDropdowns.get(item) ?? (label ? groups.get(label) : undefined);
if (!options) {
return;
}
this.watchedDropdowns.add(item);
// Every way of opening the dropdown sets `isOpen`, its button and the ▼ key alike, so the
// value is turned back here and the host's menu toggles instead.
this.listenTo<DropdownSetIsOpenEvent>(item, "set:isOpen", (evt, name, isOpen) => {
if (!isOpen || this.building) {
return;
}
evt.return = false;
if (this.shown?.dropdown === item) {
const toKeyboard = this.host?.isInPlaceOfKeyboard?.() ?? false;
this.hideMenu();
if (toKeyboard) {
this.editor.editing.view.focus();
}
} else {
this.showMenu(toolbar, item, options, createHost);
}
}, { priority: "high" });
}
private showMenu(
toolbar: ToolbarView, dropdown: DropdownView, options: ListMenuOptions,
createHost: () => ToolbarGroupMenuHost
) {
const editor = this.editor;
const anchor = dropdown.buttonView.element;
/* v8 ignore next 3 -- a dropdown is opened from its rendered button */
if (!anchor) {
return;
}
this.hideMenu();
const host = this.host ??= createHost();
// The toolbar's "Show more items" dropdown closes as focus or a press leaves it, so it
// counts the menu as its own too, while it holds the group.
const enclosing = [...toolbar.children].filter((child): child is DropdownView =>
child instanceof DropdownView && child !== dropdown
&& !!child.element?.contains(anchor));
const trackers = [editor.ui.focusTracker, ...enclosing.map((child) => child.focusTracker)];
const runAction = (action: () => void) => () => {
this.hideMenu();
for (const child of enclosing) {
child.isOpen = false;
}
editor.editing.view.focus();
action();
};
const run = (view: View) => runAction(() => view.fire("execute"));
let element: HTMLElement | null = null;
const { describe, ...menuOptions } = options;
let items: ToolbarGroupMenuItem[];
if (describe) {
items = describe(runAction);
} else if (listMenuDropdowns.has(dropdown)) {
items = this.describeList(dropdown, run);
} else {
items = describeItems(this.sourceItems(dropdown), run);
}
const request: ToolbarGroupMenuRequest = {
anchor,
items,
...menuOptions,
setElement: (next) => {
if (element) {
untrackElement(element, trackers);
}
element = next;
if (element) {
trackElement(element, trackers);
}
},
onClose: (returnFocus) => {
if (this.shown?.request !== request) {
return;
}
this.shown = null;
if (returnFocus) {
dropdown.buttonView.focus();
}
}
};
this.shown = { dropdown, request };
host.show(request);
}
private hideMenu() {
if (this.shown) {
this.shown = null;
this.host?.hide();
}
}
/** The rows of a dropdown handed to {@link openListAsMenu}. */
private describeList(dropdown: DropdownView, run: (view: View) => () => void) {
this.building = true;
// The dropdown builds its list or its toolbar the first time it opens.
if (!dropdown.listView && !dropdown.toolbarView) {
dropdown.isOpen = true;
dropdown.isOpen = false;
}
const rows = dropdown.toolbarView
? describeItems([...dropdown.toolbarView.items], run)
: describeListEntries(dropdown, run) ?? [];
this.building = false;
return rows;
}
/** The views CKEditor lays out in the group, which it builds the first time it is opened. */
private sourceItems(dropdown: DropdownView) {
if (!dropdown.toolbarView) {
this.building = true;
dropdown.isOpen = true;
dropdown.isOpen = false;
this.building = false;
}
/* v8 ignore next -- opening the dropdown builds its `toolbarView` */
return [...dropdown.toolbarView?.items ?? []];
}
}
type DropdownSetIsOpenEvent = {
name: "set:isOpen";
args: [name: string, value: boolean, oldValue: boolean];
return: boolean;
};
/** Stops presses in the menu from reaching CKEditor's `clickOutsideHandler()` on the document. */
function stopPress(e: Event) {
e.stopPropagation();
}
function trackElement(element: HTMLElement, trackers: FocusTracker[]) {
element.addEventListener("mousedown", stopPress);
for (const tracker of trackers) {
tracker.add(element);
}
}
function untrackElement(element: HTMLElement, trackers: FocusTracker[]) {
element.removeEventListener("mousedown", stopPress);
for (const tracker of trackers) {
tracker.remove(element);
}
}
/** The labels of the groups marked `asMenu`, with the options of their menus. */
function collectMenuGroups(...configs: (ToolbarConfig | undefined)[]) {
const groups = new Map<string, ListMenuOptions>();
for (const config of configs) {
collectFromItems(Array.isArray(config) ? config : config?.items, groups);
}
return groups;
}
function collectFromItems(items: ToolbarConfigItem[] | undefined, groups: Map<string, ListMenuOptions>) {
for (const item of items ?? []) {
if (typeof item === "string") {
continue;
}
const { asMenu } = item as { asMenu?: boolean | ListMenuOptions };
if (asMenu) {
groups.set(item.label, asMenu === true ? {} : asMenu);
}
collectFromItems(item.items, groups);
}
}
/**
* The toolbars registered with `WidgetToolbarRepository`, such as the one of an image. The
* repository keeps them in a private map, as `ContextToolbar` reads it too.
*/
function getWidgetToolbarViews(editor: Editor) {
const repository = editor.plugins.get(WidgetToolbarRepository) as unknown as {
_toolbarDefinitions: Map<string, { view: ToolbarView }>;
};
return [...repository._toolbarDefinitions.values()].map(({ view }) => view);
}
/**
* The entries `items` stand for, with a rule wherever the group has a separator between entries.
* A dropdown's list is read now, as `dateTime` fills its list with the time it is opened at.
*/
function describeItems(items: View[], run: (view: View) => () => void) {
const described: ToolbarGroupMenuItem[] = [];
for (const item of items) {
if (item instanceof ToolbarSeparatorView) {
addRule(described);
} else if (item instanceof ButtonView) {
described.push(describeButton(item, run(item)));
} else if (item instanceof DropdownView) {
const children = describeListEntries(item, run);
if (!children) {
continue;
}
// A list with no rows, such as the templates before there are any, is drawn disabled
// rather than left out, so the place of the entry does not change.
const opener = item.buttonView;
const split = opener instanceof SplitButtonView;
described.push({
kind: "entry",
label: opener.label ?? "",
icon: opener.icon,
isEnabled: item.isEnabled && (split || children.length > 0),
run: split ? run(opener) : undefined,
children: children.length ? children : undefined
});
}
}
trimRule(described);
return described;
}
/**
* The rows of the list `dropdown` holds, with a rule wherever the list has a separator, or
* `undefined` for a dropdown that holds no list.
*/
function describeListEntries(dropdown: DropdownView, run: (view: View) => () => void) {
const entries = listEntriesOf(dropdown);
if (!entries) {
return undefined;
}
const rows: ToolbarGroupMenuItem[] = [];
for (const entry of entries) {
if (entry instanceof ListSeparatorView) {
addRule(rows);
} else if (entry instanceof ListItemGroupView) {
rows.push({ kind: "heading", label: entry.label });
} else {
rows.push(describeButton(entry, run(entry)));
}
}
trimRule(rows);
return rows;
}
/** Adds a rule after the entries `items` holds, unless it would lead or double one. */
function addRule(items: ToolbarGroupMenuItem[]) {
if (items.length && items.at(-1)?.kind !== "separator") {
items.push({ kind: "separator" });
}
}
function trimRule(items: ToolbarGroupMenuItem[]) {
if (items.at(-1)?.kind === "separator") {
items.pop();
}
}
function describeButton(view: ButtonView, run: () => void): ToolbarGroupMenuEntry {
const entry: ToolbarGroupMenuEntry = {
kind: "entry", label: view.label ?? "", icon: view.icon, isEnabled: view.isEnabled, run
};
if (view instanceof SwitchButtonView) {
entry.isSwitch = true;
entry.isOn = view.isOn;
} else if (view.isToggleable || view.role === "menuitemradio" || view.role === "menuitemcheckbox") {
entry.isOn = view.isOn;
}
if (view.class) {
entry.className = view.class;
}
return entry;
}
/**
* The rows a dropdown's list holds, which it builds the first time it is opened: its own, or that
* of a search panel, as `insertTemplate` has.
*/
function listEntriesOf(dropdown: DropdownView) {
const wasOpen = dropdown.isOpen;
dropdown.isOpen = true;
dropdown.isOpen = wasOpen;
const listView = dropdown.listView ?? searchedListOf(dropdown);
if (!listView) {
return undefined;
}
return listItemEntries(listView.items);
}
/** The buttons and separators of a list's items, a group's label before its own. */
function listItemEntries(items: Iterable<View>) {
const entries: Array<ButtonView | ListSeparatorView | ListItemGroupView> = [];
for (const item of items) {
if (item instanceof ListSeparatorView) {
entries.push(item);
} else if (item instanceof ListItemGroupView) {
entries.push(item, ...listItemEntries(item.items));
} else if (item instanceof ListItemView && item.children.first instanceof ButtonView) {
entries.push(item.children.first);
}
}
return entries;
}
function searchedListOf(dropdown: DropdownView) {
for (const child of dropdown.panelView.children) {
if (child instanceof SearchTextView && child.filteredView instanceof ListView) {
return child.filteredView;
}
}
return undefined;
}