ckeditor5-elements-menu 0.0.0-stage → 49.0.0

package/src/elementMenu.ts

@@ -0,0 +1,249 @@
+import {
+	ContextualBalloon,
+	DropdownMenuRootListView,
+	KeystrokeHandler,
+	Notification,
+	Plugin,
+	clickOutsideHandler,
+	type Editor,
+	type FocusableView,
+	type ModelElement,
+	type RectSource
+} from 'ckeditor5';
+import { isInDocument, type ElementOrPositionCommand } from 'ckeditor5-elements-core';
+import ElementMenuView from './elementMenuView.js';
+
+/**
+ * A submenu of an element menu. Missing items are skipped, as in the menu.
+ */
+export interface ElementSubmenu {
+	title: string;
+
+	/**
+	 * The icon (SVG string) shown next to the title.
+	 */
+	icon?: string;
+
+	items: (ElementMenuItem | null | undefined)[];
+}
+
+/**
+ * An item of an element menu:
+ *
+ * * a command, shown as a button with its `title` and `icon`, enabled and "on" according to its
+ *   {@link ElementOrPositionCommand#getState state} for the element,
+ * * a submenu,
+ * * `'|'`, a separator. Separators at the start or the end of a menu, and repeated ones, are not shown, so a group of
+ *   items can start with one.
+ */
+export type ElementMenuItem = ElementOrPositionCommand | ElementSubmenu | '|';
+
+/**
+ * Returns the items of the menu of the given element, e.g. as the `elementContextMenu` or `elementBreadcrumbs.menu` editor
+ * config option. Missing items (e.g. commands that are not registered) are skipped. No items means no menu.
+ */
+export type ElementMenuConfig = (element: ModelElement, editor: Editor) => (ElementMenuItem | null | undefined)[];
+
+/**
+ * The options of {@link ElementMenu#open} and {@link ElementMenu#show}.
+ */
+export interface ElementMenuShowOptions {
+	/**
+	 * The accessible name of the menu of an element (see {@link ElementMenu#open}). Defaults to "Element menu".
+	 */
+	label?: string;
+
+	/**
+	 * Called when the document data changes while the menu is open. When it returns `true`, the menu closes, e.g.
+	 * because the element it is for was removed.
+	 */
+	isObsolete?: () => boolean;
+
+	/**
+	 * What gets the focus when the menu is closed with Esc, e.g. the button that opened the menu. Defaults to the editor.
+	 */
+	returnFocusTo?: { focus(): void };
+
+	/**
+	 * Called when the menu closes, for any reason: Esc, a click outside, an executed item, or another menu replacing it.
+	 */
+	onHide?: () => void;
+}
+
+/**
+ * Shows menus in a balloon: the menu of an element, built from commands, submenus and separators (see {@link open}),
+ * or any view, e.g. the quick insert search (see {@link show}).
+ *
+ * The element context menu, the breadcrumbs and quick insert show their menus with it. The menu of an element is
+ * CKEditor's dropdown menu (see {@link ElementMenuView}).
+ *
+ * Executing an item closes the menu. Esc and clicking outside close it too; Esc returns the focus to the editor, or to
+ * {@link ElementMenuShowOptions.returnFocusTo}.
+ */
+export default class ElementMenu extends Plugin {
+	/**
+	 * The view in the open menu, if any.
+	 */
+	public view: FocusableView | null = null;
+
+	private _keystrokes: KeystrokeHandler | null = null;
+	private _isObsolete: (() => boolean) | null = null;
+	private _onHide: (() => void) | null = null;
+
+	public static get requires(): readonly [typeof ContextualBalloon, typeof Notification] {
+		// The buttons of the menu report failed commands with notifications.
+		return [ContextualBalloon, Notification] as const;
+	}
+
+	public static get pluginName(): 'ElementMenu' {
+		return 'ElementMenu' as const;
+	}
+
+	public init(): void {
+		this.listenTo(this.editor.model.document, 'change:data', () => {
+			if (this._isObsolete?.()) {
+				this.hide();
+			}
+		});
+	}
+
+	/**
+	 * Opens the menu of the element next to the target (e.g. a button, or a `DOMRect` in viewport coordinates), with
+	 * the items from the config callback. The menu closes when the element is removed.
+	 *
+	 * Returns `false` when there are no items.
+	 */
+	public open(
+		element: ModelElement,
+		target: RectSource,
+		config: ElementMenuConfig,
+		{ label = this.editor.t('Element menu'), isObsolete, ...options }: ElementMenuShowOptions = {}
+	): boolean {
+		const view = new ElementMenuView(
+			this.editor.locale,
+			this.editor.ui.view.body,
+			config(element, this.editor),
+			element
+		);
+
+		if (view.isEmpty) {
+			view.destroy();
+
+			return false;
+		}
+
+		view.ariaLabel = label;
+
+		this.show(view, target, {
+			...options,
+			isObsolete: () => !isInDocument(element) || !!isObsolete?.()
+		});
+
+		return true;
+	}
+
+	/**
+	 * Shows the view (e.g. a menu) next to the target (e.g. a button, or a `DOMRect` in viewport coordinates), and
+	 * focuses it. The menu closes when the view, or an item of CKEditor's dropdown menu in it, fires `execute`.
+	 */
+	public show(
+		view: FocusableView,
+		target: RectSource,
+		{ isObsolete, returnFocusTo, onHide }: ElementMenuShowOptions = {}
+	): void {
+		this.hide();
+
+		const close = (): void => {
+			// The item may have opened another menu already (e.g. "Insert before" opens quick insert).
+			if (this.view === view) {
+				this.hide();
+			}
+		};
+
+		this.listenTo(view, 'execute', close);
+		this.listenTo(view, 'menu:execute', close);
+
+		clickOutsideHandler({
+			emitter: view,
+			activator: () => this._balloon.visibleView === view,
+			// The open nested menus are in panels outside the balloon.
+			contextElements: () => [this._balloon.view.element, ...getOpenPanels(view)].filter(element => !!element),
+			callback: () => {
+				this.hide();
+			}
+		});
+
+		this._balloon.add({
+			view,
+			position: { target },
+			withArrow: false,
+			singleViewMode: true,
+			// Views that other plugins add to the balloon meanwhile (e.g. an element toolbar, when the selection moves
+			// into its element) go to their own stack, so they do not cover the menu.
+			stackId: 'elementMenu'
+		});
+
+		const keystrokes = new KeystrokeHandler();
+
+		// Esc in a nested menu closes only that menu.
+		keystrokes.set('Esc', (data, cancel) => {
+			this.hide();
+			(returnFocusTo ?? this.editor.editing.view).focus();
+			cancel();
+		});
+
+		if (view.element) {
+			keystrokes.listenTo(view.element);
+		}
+
+		this.view = view;
+		this._keystrokes = keystrokes;
+		this._isObsolete = isObsolete ?? null;
+		this._onHide = onHide ?? null;
+		view.focus();
+	}
+
+	/**
+	 * Hides the open menu, if any.
+	 */
+	public hide(): void {
+		const view = this.view;
+		const onHide = this._onHide;
+
+		if (!view) {
+			return;
+		}
+
+		this._keystrokes?.destroy();
+		this.view = null;
+		this._keystrokes = null;
+		this._isObsolete = null;
+		this._onHide = null;
+		this.stopListening(view);
+
+		if (this._balloon.hasView(view)) {
+			this._balloon.remove(view);
+		}
+
+		view.destroy();
+		onHide?.();
+	}
+
+	public override destroy(): void {
+		this.hide();
+		super.destroy();
+	}
+
+	private get _balloon(): ContextualBalloon {
+		return this.editor.plugins.get(ContextualBalloon);
+	}
+}
+
+/**
+ * Returns the panels of the open nested menus of CKEditor's dropdown menu.
+ */
+function getOpenPanels(view: FocusableView): (HTMLElement | null)[] {
+	return view instanceof DropdownMenuRootListView
+		? view.menus.filter(menu => menu.isOpen).map(menu => menu.panelView.element)
+		: [];
+}

package/src/elementMenuView.ts

@@ -0,0 +1,202 @@
+import {
+	DropdownMenuRootListView,
+	ListSeparatorView,
+	type BodyCollection,
+	type DropdownMenuDefinition,
+	type ListView,
+	type Locale
+} from 'ckeditor5';
+import { ElementOrPositionCommand, bindButtonToCommand, type ElementOrPosition } from 'ckeditor5-elements-core';
+import { type ElementMenuItem, type ElementSubmenu } from './elementMenu.js';
+
+/**
+ * The menu of an element: CKEditor's dropdown menu (`DropdownMenuRootListView`), built from commands, submenus and
+ * separators.
+ *
+ * CKEditor builds the menu and handles it: the nested menus (opened on click, hover, or the right arrow; placed where
+ * they fit), the keyboard, and right-to-left languages. This view only connects the buttons to the commands: they
+ * reflect the command title, icon and {@link ElementOrPositionCommand#getState state} for the target, and execute the
+ * command for it. It also adds the separators, which CKEditor's menu definitions do not have.
+ *
+ * Missing items are skipped, and submenus without items, and separators at the start or the end, or repeated ones.
+ * Submenus are enabled when one of their items is. Right-clicking the menu does not open the native context menu.
+ */
+export default class ElementMenuView extends DropdownMenuRootListView {
+	/**
+	 * The element or position the commands are executed for.
+	 */
+	public readonly target: ElementOrPosition;
+
+	/**
+	 * Whether the menu has no items: all were missing.
+	 */
+	public readonly isEmpty: boolean;
+
+	private readonly _commands: Map<string, ElementOrPositionCommand>;
+	private readonly _submenus: Map<string, MenuSubmenu>;
+
+	/**
+	 * The positions of the separators in each list, by the id of the submenu (`''` for the menu itself).
+	 */
+	private readonly _separators: Map<string, number[]>;
+
+	constructor(
+		locale: Locale,
+		bodyCollection: BodyCollection,
+		items: readonly (ElementMenuItem | null | undefined)[],
+		target: ElementOrPosition
+	) {
+		const maps: DefinitionMaps = { commands: new Map(), submenus: new Map(), separators: new Map() };
+		const menuItems = cleanItems(items);
+
+		super(locale, bodyCollection, createDefinitions(menuItems, '', maps));
+
+		this.target = target;
+		this.isEmpty = !menuItems.length;
+		this._commands = maps.commands;
+		this._submenus = maps.submenus;
+		this._separators = maps.separators;
+		this.menuPanelClass = 'ck-elements-menu__panel';
+
+		this.extendTemplate({
+			attributes: { class: 'ck-elements-menu' },
+			on: { contextmenu: this.bindTemplate.to(preventDefault) }
+		});
+	}
+
+	/**
+	 * Renders the menu: CKEditor builds it from the definitions; then the buttons are connected to the commands, and the
+	 * separators are added.
+	 */
+	public override render(): void {
+		super.render();
+
+		for (const button of this.buttons) {
+			const command = this._commands.get(button.id);
+
+			if (command) {
+				bindButtonToCommand(button, command, { withText: true, target: this.target });
+
+				// A toggleable button with a checkable role tells assistive technology whether it is "on" with `aria-checked`.
+				button.role = command.isToggleable ? 'menuitemcheckbox' : 'menuitem';
+			}
+		}
+
+		for (const menu of this.menus) {
+			const submenu = this._submenus.get(menu.id);
+
+			if (submenu) {
+				menu.buttonView.icon = submenu.icon;
+				menu.isEnabled = this._isEnabled(submenu);
+			}
+
+			// The panels of nested menus are not inside the menu.
+			if (menu.panelView.element) {
+				this.listenTo(menu.panelView.element, 'contextmenu', (evt, domEvent: Event) => {
+					preventDefault(domEvent);
+				});
+			}
+		}
+
+		this._addSeparators('', this);
+
+		for (const menu of this.menus) {
+			this._addSeparators(menu.id, menu.listView);
+		}
+	}
+
+	private _addSeparators(id: string, list: ListView): void {
+		for (const position of this._separators.get(id) ?? []) {
+			const separator = new ListSeparatorView(this.locale);
+
+			separator.extendTemplate({ attributes: { role: 'separator' } });
+			list.items.add(separator, position);
+		}
+	}
+
+	private _isEnabled(item: MenuItem): boolean {
+		if (item === '|') {
+			return false;
+		}
+
+		return item instanceof ElementOrPositionCommand
+			? item.getState(this.target).isEnabled
+			: item.items.some(child => this._isEnabled(child));
+	}
+}
+
+/**
+ * An item of the menu, as it is shown: none is missing.
+ */
+type MenuItem = ElementOrPositionCommand | MenuSubmenu | '|';
+
+interface MenuSubmenu extends Omit<ElementSubmenu, 'items'> {
+	items: MenuItem[];
+}
+
+interface DefinitionMaps {
+	commands: Map<string, ElementOrPositionCommand>;
+	submenus: Map<string, MenuSubmenu>;
+	separators: Map<string, number[]>;
+}
+
+/**
+ * Returns the items without missing ones, submenus without items, and separators at the start or the end, or
+ * repeated ones.
+ */
+function cleanItems(items: readonly (ElementMenuItem | null | undefined)[]): MenuItem[] {
+	const result: MenuItem[] = [];
+
+	for (const item of items) {
+		const cleaned = item === '|' || item instanceof ElementOrPositionCommand || !item ? item : cleanSubmenu(item);
+
+		if (!cleaned || (cleaned === '|' && (!result.length || result.at(-1) === '|'))) {
+			continue;
+		}
+
+		result.push(cleaned);
+	}
+
+	if (result.at(-1) === '|') {
+		result.pop();
+	}
+
+	return result;
+}
+
+function cleanSubmenu(submenu: ElementSubmenu): MenuSubmenu | null {
+	const items = cleanItems(submenu.items);
+
+	return items.length ? { ...submenu, items } : null;
+}
+
+/**
+ * Creates CKEditor's menu definitions for the items. The ids are paths of positions (e.g. `'2.0'`). Collects the
+ * commands and submenus by id, and the positions of the separators by the id of their submenu.
+ */
+function createDefinitions(items: readonly MenuItem[], parentId: string, maps: DefinitionMaps): DropdownMenuDefinition {
+	const definitions: DropdownMenuDefinition = [];
+	let position = 0;
+
+	for (const item of items) {
+		const id = parentId ? `${parentId}.${String(position)}` : String(position);
+
+		if (item === '|') {
+			maps.separators.set(parentId, [...(maps.separators.get(parentId) ?? []), position]);
+		} else if (item instanceof ElementOrPositionCommand) {
+			maps.commands.set(id, item);
+			definitions.push({ id, label: item.title });
+		} else {
+			maps.submenus.set(id, item);
+			definitions.push({ id, menu: item.title, children: createDefinitions(item.items, id, maps) });
+		}
+
+		position++;
+	}
+
+	return definitions;
+}
+
+function preventDefault(domEvent: Event): void {
+	domEvent.preventDefault();
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Element menus: `ElementMenu` shows the menu of an element, built from commands, submenus and separators, and the
+ * features that open it: the element context menu (a right-click, Shift+F10 or the menu key), the breadcrumbs (the
+ * element path at the selection, clickable with a menu) and quick insert (search and insert the elements allowed at a
+ * position).
+ *
+ * @module ckeditor5-elements-menu
+ */
+
+// Plugins.
+export {
+	default as ElementMenu,
+	type ElementMenuConfig,
+	type ElementMenuItem,
+	type ElementMenuShowOptions,
+	type ElementSubmenu
+} from './elementMenu.js';
+export { default as ElementContextMenu } from './contextMenu/elementContextMenu.js';
+export { default as ElementBreadcrumbs, type ElementBreadcrumbsConfig } from './breadcrumbs/elementBreadcrumbs.js';
+export { default as ElementQuickInsert, type ElementQuickInsertConfig } from './quickInsert/elementQuickInsert.js';
+
+// Commands.
+export { default as QuickInsertCommand } from './quickInsert/quickInsertCommand.js';
+export {
+	default as QuickInsertPositionCommand,
+	type QuickInsertPlacement
+} from './quickInsert/quickInsertPositionCommand.js';
+
+// Views.
+export { default as ElementMenuView } from './elementMenuView.js';
+export {
+	default as BreadcrumbsView,
+	type BreadcrumbsViewExecuteEvent,
+	type BreadcrumbsViewOptions
+} from './breadcrumbs/breadcrumbsView.js';
+export {
+	default as BreadcrumbItemView,
+	type BreadcrumbItem,
+	type BreadcrumbItemViewOptions
+} from './breadcrumbs/breadcrumbItemView.js';
+export { default as BreadcrumbLabelView } from './breadcrumbs/breadcrumbLabelView.js';
+export { default as QuickInsertView } from './quickInsert/quickInsertView.js';
+export { default as QuickInsertListView, type QuickInsertItem } from './quickInsert/quickInsertListView.js';
+
+// Observers.
+export {
+	default as ContextMenuObserver,
+	type ViewDocumentContextMenuEvent
+} from './contextMenu/contextMenuObserver.js';
+
+// Icons.
+export { insertAfterIcon, insertBeforeIcon, insertIcon } from './quickInsert/icons.js';
+
+import './augmentation.js';

package/src/quickInsert/elementQuickInsert.ts

@@ -0,0 +1,135 @@
+import { Plugin, type Editor, type FilteredViewExecuteEvent, type RectSource } from 'ckeditor5';
+import type { ElementOrPosition } from 'ckeditor5-elements-core';
+import { getDomTarget } from '../domTarget.js';
+import ElementMenu from '../elementMenu.js';
+import QuickInsertCommand from './quickInsertCommand.js';
+import QuickInsertPositionCommand from './quickInsertPositionCommand.js';
+import { type QuickInsertItem } from './quickInsertListView.js';
+import QuickInsertView from './quickInsertView.js';
+
+/**
+ * The configuration of the {@link ElementQuickInsert} plugin.
+ */
+export interface ElementQuickInsertConfig {
+	/**
+	 * Labels of the elements, by model name. Elements without a label are listed by their model name.
+	 */
+	labels?: Record<string, string>;
+
+	/**
+	 * Model names of the elements that are never listed.
+	 */
+	exclude?: string[];
+
+	/**
+	 * The keystroke that opens the menu at the selection, e.g. `'Ctrl+Space'`. Defaults to `'Alt+Enter'`
+	 * (Option+Enter on macOS). `false` registers no keystroke.
+	 */
+	keystroke?: string | false;
+}
+
+/**
+ * Opens a menu with a search field and the elements allowed at the selection, on Alt+Enter (Option+Enter on macOS; see
+ * {@link ElementQuickInsertConfig.keystroke}). Choosing an element inserts it with the `quickInsert` command.
+ *
+ * The menu is shown by the `ElementMenu` plugin. The `quickInsertBefore` and `quickInsertAfter` commands (see
+ * {@link QuickInsertPositionCommand}) open it for the position before or after an element; list them in the
+ * `elementContextMenu` config, e.g. as an "Insert" submenu.
+ *
+ * The menu closes when the document changes while it is open, so it never inserts at an outdated position.
+ */
+export default class ElementQuickInsert extends Plugin {
+	public static get requires(): readonly [typeof ElementMenu] {
+		return [ElementMenu] as const;
+	}
+
+	public static get pluginName(): 'ElementQuickInsert' {
+		return 'ElementQuickInsert' as const;
+	}
+
+	constructor(editor: Editor) {
+		super(editor);
+
+		editor.config.define('elementQuickInsert', { labels: {}, exclude: [], keystroke: 'Alt+Enter' });
+	}
+
+	public init(): void {
+		const editor = this.editor;
+		const keystroke = editor.config.get('elementQuickInsert')?.keystroke;
+
+		editor.commands.add('quickInsert', new QuickInsertCommand(editor));
+		editor.commands.add('quickInsertBefore', new QuickInsertPositionCommand(editor, 'before', this));
+		editor.commands.add('quickInsertAfter', new QuickInsertPositionCommand(editor, 'after', this));
+
+		if (keystroke) {
+			editor.keystrokes.set(keystroke, (data, cancel) => {
+				if (this.open()) {
+					cancel();
+				}
+			});
+
+			editor.accessibility.addKeystrokeInfos({
+				keystrokes: [{ label: editor.t('Insert an element at the cursor'), keystroke }]
+			});
+		}
+	}
+
+	/**
+	 * Returns the elements that can be inserted at the target (a position, the position before an element, or the
+	 * selection), with their labels.
+	 */
+	public getItems(elementOrPosition?: ElementOrPosition): QuickInsertItem[] {
+		const config = this.editor.config.get('elementQuickInsert');
+		const labels = config?.labels ?? {};
+		const command = this.editor.commands.get('quickInsert');
+
+		return (command?.getAllowedElements(elementOrPosition, config?.exclude) ?? []).map(name => ({
+			name,
+			label: labels[name] ?? name
+		}));
+	}
+
+	/**
+	 * Whether an element can be inserted at the target (a position, the position before an element, or the selection),
+	 * as {@link getItems} lists them: it stops at the first one, e.g. for whether a command is enabled.
+	 */
+	public hasItems(elementOrPosition?: ElementOrPosition): boolean {
+		const command = this.editor.commands.get('quickInsert');
+
+		return !!command?.hasAllowedElements(elementOrPosition, this.editor.config.get('elementQuickInsert')?.exclude);
+	}
+
+	/**
+	 * Opens the menu for inserting at the target (a position, the position before an element, or the selection), next
+	 * to the given DOM target. By default, the menu is next to the element, or the selection.
+	 *
+	 * Returns `false` when nothing can be inserted at the target because it cannot be edited, or there is nothing to
+	 * show the menu next to.
+	 */
+	public open(elementOrPosition?: ElementOrPosition, domTarget?: RectSource): boolean {
+		const editor = this.editor;
+		const command = editor.commands.get('quickInsert');
+		const position = command?.getInsertPosition(elementOrPosition);
+		const menuTarget = domTarget ?? getDomTarget(editor, elementOrPosition);
+
+		if (!command || !position || !menuTarget || !command.getState(position).isEnabled) {
+			return false;
+		}
+
+		const view = new QuickInsertView(editor.locale, this.getItems(position));
+
+		view.on<FilteredViewExecuteEvent>('execute', (evt, { value }) => {
+			// Focus first: focusing reads the DOM selection, which would override the selection set by the command.
+			editor.editing.view.focus();
+			command.executeFor(position, value);
+		});
+
+		// The search field is labelled "Insert element".
+		editor.plugins.get(ElementMenu).show(view, menuTarget, {
+			// The position would be outdated after any change, e.g. by another user.
+			isObsolete: () => true
+		});
+
+		return true;
+	}
+}

package/src/quickInsert/icons.ts

@@ -0,0 +1,26 @@
+import { IconPlus } from 'ckeditor5';
+
+/**
+ * The icons of the quick insert commands, in the style of the CKEditor 5 icons (20×20).
+ */
+
+/**
+ * Insert element: CKEditor's own plus icon.
+ */
+export const insertIcon = IconPlus;
+
+/**
+ * Insert before: a plus above a block.
+ */
+export const insertBeforeIcon =
+	'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path fill-rule="evenodd" d="' +
+	'M9.25 1.5h1.5v2.75h2.75v1.5h-2.75V8.5h-1.5V5.75H6.5v-1.5h2.75zM3.5 11h13a1 1 0 0 1 1 1v5a1 1 0 0 1-1 1h-13a1 1 0 0 ' +
+	'1-1-1v-5a1 1 0 0 1 1-1zm.5 1.5v4h12v-4z"/></svg>';
+
+/**
+ * Insert after: a block above a plus.
+ */
+export const insertAfterIcon =
+	'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path fill-rule="evenodd" d="' +
+	'M3.5 2h13a1 1 0 0 1 1 1v5a1 1 0 0 1-1 1h-13a1 1 0 0 1-1-1V3a1 1 0 0 1 1-1zm.5 1.5v4h12v-4zM9.25 11h1.5v2.75h2.75v1.5' +
+	'h-2.75V18h-1.5v-2.75H6.5v-1.5h2.75z"/></svg>';