ckeditor5-elements-core 49.0.0-alpha.2 → 49.0.0-alpha.4

package/src/elementMenu.ts

@@ -1,275 +0,0 @@
-import {
-	ContextualBalloon,
-	DropdownMenuRootListView,
-	KeystrokeHandler,
-	Notification,
-	Plugin,
-	clickOutsideHandler,
-	type Editor,
-	type FocusableView,
-	type ModelElement,
-	type RectSource
-} from 'ckeditor5';
-import ElementMenuView from './elementMenuView.js';
-import ElementOrPositionCommand from './elementOrPositionCommand.js';
-import { isInDocument } from './utils.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 `breadcrumbs.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 items = cleanItems(config(element, this.editor));
-
-		if (!items.length) {
-			return false;
-		}
-
-		const view = new ElementMenuView(this.editor.locale, this.editor.ui.view.body, items, element);
-
-		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 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)[]): ElementMenuItem[] {
-	const result: ElementMenuItem[] = [];
-
-	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): ElementSubmenu | null {
-	const items = cleanItems(submenu.items);
-
-	return items.length ? { ...submenu, items } : null;
-}
-
-/**
- * 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

@@ -1,164 +0,0 @@
-import {
-	DropdownMenuRootListView,
-	ListSeparatorView,
-	type BodyCollection,
-	type DropdownMenuDefinition,
-	type ListView,
-	type Locale
-} from 'ckeditor5';
-import { type ElementMenuItem, type ElementSubmenu } from './elementMenu.js';
-import { bindButtonToCommand } from './elementOrPositionButtonView.js';
-import ElementOrPositionCommand, { type ElementOrPosition } from './elementOrPositionCommand.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.
- *
- * 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;
-
-	private readonly _commands: Map<string, ElementOrPositionCommand>;
-	private readonly _submenus: Map<string, ElementSubmenu>;
-
-	/**
-	 * 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() };
-
-		super(locale, bodyCollection, createDefinitions(items, '', maps));
-
-		this.target = target;
-		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: ElementMenuItem): boolean {
-		if (item === '|') {
-			return false;
-		}
-
-		return item instanceof ElementOrPositionCommand
-			? item.getState(this.target).isEnabled
-			: item.items.some(child => !!child && this._isEnabled(child));
-	}
-}
-
-interface DefinitionMaps {
-	commands: Map<string, ElementOrPositionCommand>;
-	submenus: Map<string, ElementSubmenu>;
-	separators: Map<string, number[]>;
-}
-
-/**
- * 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 (ElementMenuItem | null | undefined)[],
-	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) {
-			continue;
-		}
-
-		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/theme/elementMenu.css

@@ -1,14 +0,0 @@
-/*
- * The menu of an element is CKEditor's dropdown menu, so CKEditor styles it. Only the alignment of labels is added.
- */
-
-/* In a menu with icons (or a nested menu of it), items without an icon get the space of one, so that all labels line up. */
-:is(.ck.ck-elements-menu, .ck.ck-elements-menu__panel > .ck-dropdown-menu-list):has(
-		> .ck-list__item > :is(.ck-button, .ck-dropdown-menu-list__nested-menu > .ck-button) > .ck-button__icon
-	)
-	> .ck-list__item
-	> :is(.ck-button, .ck-dropdown-menu-list__nested-menu > .ck-button):not(:has(> .ck-button__icon))
-	> .ck-button__label {
-	/* The width of an icon, and the gap after it. */
-	margin-inline-start: calc(var(--ck-icon-size) + var(--ck-button-icon-gap));
-}