ckeditor5-elements-menu 0.0.0-stage → 49.0.0

package/src/breadcrumbs/breadcrumbsView.ts

@@ -0,0 +1,176 @@
+import { KeystrokeHandler, View, ViewCollection, type Locale } from 'ckeditor5';
+import BreadcrumbItemView, { type BreadcrumbItem } from './breadcrumbItemView.js';
+import BreadcrumbLabelView from './breadcrumbLabelView.js';
+
+/**
+ * The options of {@link BreadcrumbsView}.
+ */
+export interface BreadcrumbsViewOptions {
+	/**
+	 * Whether the items are buttons that can be clicked, or labels. Defaults to `false`.
+	 */
+	isClickable?: boolean;
+}
+
+/**
+ * Shows a path of elements, from the outermost to the innermost one, as a list (`<ol>`) in a `<nav>` landmark: buttons
+ * when the items can be clicked, labels otherwise. Items without a model element (list items) are labels too. The
+ * innermost item is marked with `aria-current="location"`.
+ *
+ * The left and right arrows move the focus between the items; past the first or the last one, they are left to the
+ * toolbar the view is in. Fires `execute` with the item when one of the buttons is clicked.
+ */
+export default class BreadcrumbsView extends View {
+	/**
+	 * The breadcrumb items: the buttons or labels, from the outermost to the innermost one.
+	 */
+	public readonly items = new ViewCollection<BreadcrumbItemView | BreadcrumbLabelView>();
+
+	/**
+	 * Whether the items are buttons that can be clicked, or labels.
+	 */
+	public readonly isClickable: boolean;
+
+	/**
+	 * Handles the keystrokes within the breadcrumbs.
+	 */
+	public readonly keystrokes = new KeystrokeHandler();
+
+	/**
+	 * The list items (`<li>`) that hold the {@link items}.
+	 */
+	private readonly _listItems: ViewCollection<BreadcrumbsListItemView>;
+
+	constructor(locale?: Locale, { isClickable = false }: BreadcrumbsViewOptions = {}) {
+		super(locale);
+
+		this._listItems = this.createCollection();
+		this.isClickable = isClickable;
+
+		const isRtl = locale?.uiLanguageDirection === 'rtl';
+
+		this.keystrokes.set(isRtl ? 'arrowright' : 'arrowleft', (data, cancel) => {
+			if (this._focusSibling(-1)) {
+				cancel();
+			}
+		});
+
+		this.keystrokes.set(isRtl ? 'arrowleft' : 'arrowright', (data, cancel) => {
+			if (this._focusSibling(1)) {
+				cancel();
+			}
+		});
+
+		this.setTemplate({
+			tag: 'nav',
+			attributes: {
+				class: ['ck', 'ck-elements-breadcrumbs'],
+				'aria-label': locale?.t('Element path') ?? 'Element path'
+			},
+			children: [
+				{
+					tag: 'ol',
+					attributes: {
+						class: ['ck', 'ck-elements-breadcrumbs__list']
+					},
+					children: this._listItems
+				}
+			]
+		});
+	}
+
+	/**
+	 * Replaces the items.
+	 */
+	public setItems(items: readonly BreadcrumbItem[]): void {
+		for (const listItem of this._listItems) {
+			listItem.destroy();
+		}
+
+		this._listItems.clear();
+		this.items.clear();
+
+		items.forEach((item, index) => {
+			const isCurrent = index === items.length - 1;
+			const view =
+				this.isClickable && item.modelElement
+					? new BreadcrumbItemView(this.locale, item, { isCurrent })
+					: new BreadcrumbLabelView(this.locale, item, { isCurrent });
+
+			if (view instanceof BreadcrumbItemView) {
+				view.on('execute', () => {
+					this.fire<BreadcrumbsViewExecuteEvent>('execute', view);
+				});
+			}
+
+			this.items.add(view);
+			this._listItems.add(new BreadcrumbsListItemView(this.locale, view));
+		});
+	}
+
+	/**
+	 * Renders the view and starts handling the keystrokes.
+	 */
+	public override render(): void {
+		super.render();
+
+		if (this.element) {
+			this.keystrokes.listenTo(this.element);
+		}
+	}
+
+	/**
+	 * Focuses an item: the first one when the focus moves forward (`1`, e.g. from the previous toolbar item), the
+	 * innermost one otherwise.
+	 */
+	public focus(direction?: 1 | -1): void {
+		(direction === 1 ? this.items.first : this.items.last)?.focus();
+	}
+
+	/**
+	 * Destroys the view and its keystroke handler.
+	 */
+	public override destroy(): void {
+		super.destroy();
+		this.keystrokes.destroy();
+	}
+
+	/**
+	 * Focuses the item before (`-1`) or after (`1`) the focused one. Returns `false` when there is none.
+	 */
+	private _focusSibling(step: 1 | -1): boolean {
+		const items = Array.from(this.items);
+		const index = items.findIndex(item => item.element === document.activeElement);
+		const sibling = index === -1 ? undefined : items[index + step];
+
+		sibling?.focus();
+
+		return !!sibling;
+	}
+}
+
+/**
+ * Fired by {@link BreadcrumbsView} when one of its buttons is clicked.
+ */
+export interface BreadcrumbsViewExecuteEvent {
+	name: 'execute';
+	args: [item: BreadcrumbItemView];
+}
+
+/**
+ * A list item (`<li>`) of the breadcrumbs, holding a button or a label.
+ */
+class BreadcrumbsListItemView extends View {
+	constructor(locale: Locale | undefined, item: BreadcrumbItemView | BreadcrumbLabelView) {
+		super(locale);
+
+		// Rendering registers the item as a child, so it is destroyed with the list item.
+		this.setTemplate({
+			tag: 'li',
+			attributes: {
+				class: ['ck', 'ck-elements-breadcrumbs__list-item']
+			},
+			children: [item]
+		});
+	}
+}

package/src/breadcrumbs/elementBreadcrumbs.ts

@@ -0,0 +1,323 @@
+import {
+	Plugin,
+	type DifferItem,
+	type Editor,
+	type Locale,
+	type ModelDocumentChangeEvent,
+	type ModelDocumentFragment,
+	type ModelElement,
+	type ModelRootElement,
+	type ViewDocumentFragment,
+	type ViewElement,
+	type ViewNode
+} from 'ckeditor5';
+import { isInDocument } from 'ckeditor5-elements-core';
+import ElementMenu, { type ElementMenuConfig } from '../elementMenu.js';
+import { type BreadcrumbItem, type default as BreadcrumbItemView } from './breadcrumbItemView.js';
+import BreadcrumbsView, { type BreadcrumbsViewExecuteEvent } from './breadcrumbsView.js';
+
+/**
+ * Converting the data view of a large document takes a while. When the last conversion took longer than this (in
+ * milliseconds), the next one waits for {@link THROTTLE_TIME}, so editing elements quickly does not convert every time.
+ */
+const SLOW_CONVERSION_TIME = 10;
+const THROTTLE_TIME = 250;
+
+/**
+ * The configuration of the {@link ElementBreadcrumbs} plugin.
+ */
+export interface ElementBreadcrumbsConfig {
+	/**
+	 * Returns the items of the menu that opens when a breadcrumb is clicked, for the element of the breadcrumb: the
+	 * same items as in the `elementContextMenu` option (commands, submenus and `'|'` separators), so one callback can
+	 * serve both. Without this option, breadcrumbs are labels, and cannot be clicked.
+	 */
+	menu?: ElementMenuConfig;
+}
+
+/**
+ * The data view of a root, with the model elements mapped to their view elements and back.
+ */
+interface DataView {
+	root: ModelRootElement;
+	viewElements: WeakMap<ModelElement, ViewElement>;
+	modelElements: WeakMap<ViewElement, ModelElement>;
+}
+
+/**
+ * Shows the data view structure at the current selection (the elements of the editor data, as in `getData()`), e.g.
+ * `aside.note › p`, `ul › li` or `figure.table › table › tbody › tr › td`.
+ *
+ * Inline elements are items, as any element. CKEditor's text attributes, marks on the text such as its `<strong>`, are
+ * skipped. The selected element, e.g. an image, is the innermost item.
+ *
+ * Place them in a toolbar as the `breadcrumbs` component, or anywhere else using a view from {@link createView}.
+ *
+ * Clicking is configured only by the `elementBreadcrumbs.menu` editor config option (see {@link ElementBreadcrumbsConfig}): with it,
+ * the items are buttons that open the menu of their element, with `ElementMenu`, as the context menu does; without it,
+ * they are labels.
+ *
+ * The data view is converted again only when elements change, not when typing or moving the cursor. For a large
+ * document, that happens at most every 250 ms.
+ */
+export default class ElementBreadcrumbs extends Plugin {
+	/**
+	 * The elements at the current selection, from the outermost to the innermost one.
+	 *
+	 * @observable
+	 */
+	declare public items: readonly BreadcrumbItem[];
+
+	private _dataView: DataView | null = null;
+	private _isDataViewOutdated = true;
+	private _isConversionSlow = false;
+	private _conversionTimeout: ReturnType<typeof setTimeout> | null = null;
+
+	public static get pluginName(): 'ElementBreadcrumbs' {
+		return 'ElementBreadcrumbs' as const;
+	}
+
+	public static get requires(): readonly [typeof ElementMenu] {
+		return [ElementMenu] as const;
+	}
+
+	constructor(editor: Editor) {
+		super(editor);
+
+		this.set('items', []);
+	}
+
+	public init(): void {
+		const editor = this.editor;
+
+		editor.ui.componentFactory.add('breadcrumbs', locale => this.createView(locale));
+
+		this.listenTo(editor.ui, 'ready', () => {
+			this.refresh();
+		});
+
+		// Both selection and data changes.
+		this.listenTo<ModelDocumentChangeEvent>(editor.model.document, 'change', () => {
+			if (hasElementChanges(editor.model.document.differ.getChanges())) {
+				this._isDataViewOutdated = true;
+			}
+
+			this._update();
+		});
+	}
+
+	/**
+	 * Creates a breadcrumbs view that follows {@link items}.
+	 */
+	public createView(locale: Locale = this.editor.locale): BreadcrumbsView {
+		const isClickable = typeof this.editor.config.get('elementBreadcrumbs')?.menu === 'function';
+		const view = new BreadcrumbsView(locale, { isClickable });
+
+		view.setItems(this.items);
+		view.listenTo(this, 'change:items', () => {
+			view.setItems(this.items);
+		});
+
+		view.on<BreadcrumbsViewExecuteEvent>('execute', (evt, item) => {
+			this._openMenu(item);
+		});
+
+		return view;
+	}
+
+	/**
+	 * Updates {@link items} from the current selection, converting the data view first when elements changed.
+	 */
+	public refresh(): void {
+		const root = this.editor.model.document.selection.getFirstPosition()?.root;
+
+		if (root?.is('rootElement') && (this._isDataViewOutdated || root !== this._dataView?.root)) {
+			this._convert(root);
+		}
+
+		const items = this._getItems();
+
+		if (!areEqual(items, this.items)) {
+			this.items = items;
+		}
+	}
+
+	public override destroy(): void {
+		this._cancelConversion();
+		super.destroy();
+	}
+
+	/**
+	 * Refreshes the items after a change. When converting is slow, the data view is converted later, and the items
+	 * follow the outdated data view until then.
+	 */
+	private _update(): void {
+		const root = this.editor.model.document.selection.getFirstPosition()?.root;
+
+		if (this._isDataViewOutdated && this._isConversionSlow && root === this._dataView?.root) {
+			this._conversionTimeout ??= setTimeout(() => {
+				this._conversionTimeout = null;
+				this.refresh();
+			}, THROTTLE_TIME);
+		}
+
+		if (this._conversionTimeout) {
+			const items = this._getItems();
+
+			if (!areEqual(items, this.items)) {
+				this.items = items;
+			}
+		} else {
+			this.refresh();
+		}
+	}
+
+	/**
+	 * Converts the root to the data view, and maps its model elements to their view elements.
+	 */
+	private _convert(root: ModelRootElement): void {
+		const data = this.editor.data;
+		const start = performance.now();
+		const viewElements = new WeakMap<ModelElement, ViewElement>();
+		const modelElements = new WeakMap<ViewElement, ModelElement>();
+
+		// The mapper of the data pipeline is cleared by the next conversion (e.g. `getData()`), so keep the mapping.
+		data.toView(root);
+
+		for (const { item } of this.editor.model.createRangeIn(root)) {
+			const viewElement = item.is('element') ? data.mapper.toViewElement(item) : undefined;
+
+			if (item.is('element') && viewElement) {
+				viewElements.set(item, viewElement);
+				modelElements.set(viewElement, item);
+			}
+		}
+
+		this._dataView = { root, viewElements, modelElements };
+		this._isDataViewOutdated = false;
+		this._isConversionSlow = performance.now() - start > SLOW_CONVERSION_TIME;
+		this._cancelConversion();
+	}
+
+	private _cancelConversion(): void {
+		if (this._conversionTimeout) {
+			clearTimeout(this._conversionTimeout);
+			this._conversionTimeout = null;
+		}
+	}
+
+	/**
+	 * Returns the data view elements at the selection: the view element of the selected element, or of the innermost
+	 * element with the selection, and its ancestors.
+	 */
+	private _getItems(): BreadcrumbItem[] {
+		const dataView = this._dataView;
+		const selection = this.editor.model.document.selection;
+		const position = selection.getFirstPosition();
+
+		if (!dataView || position?.root !== dataView.root) {
+			return [];
+		}
+
+		// Elements created since the last conversion are not mapped yet; their closest mapped ancestor is used meanwhile.
+		let viewElement: ViewElement | undefined;
+
+		for (
+			let element: ModelElement | ModelDocumentFragment | null =
+				selection.getSelectedElement() ?? position.parent;
+			element?.is('element') && !element.is('rootElement') && !viewElement;
+			element = element.parent
+		) {
+			viewElement = dataView.viewElements.get(element);
+		}
+
+		return viewElement ? getPath(viewElement).map(node => createItem(node, dataView)) : [];
+	}
+
+	private _openMenu(item: BreadcrumbItemView): void {
+		const menuItems = this.editor.config.get('elementBreadcrumbs')?.menu;
+		const element = item.modelElement;
+
+		if (!menuItems || !item.element || !element || !isInDocument(element)) {
+			return;
+		}
+
+		item.isExpanded = this.editor.plugins.get(ElementMenu).open(element, item.element, menuItems, {
+			// The breadcrumbs may have been replaced while the menu was open.
+			returnFocusTo: {
+				focus: () => {
+					if (item.element?.isConnected) {
+						item.focus();
+					} else {
+						this.editor.editing.view.focus();
+					}
+				}
+			},
+			onHide: () => {
+				item.isExpanded = false;
+			}
+		});
+	}
+}
+
+/**
+ * Whether the changes add, remove or change elements. Typing (text changes) does not change the data view structure.
+ */
+function hasElementChanges(changes: readonly DifferItem[]): boolean {
+	return changes.some(change =>
+		change.type === 'attribute'
+			? Array.from(change.range.getItems({ shallow: true })).some(item => item.is('element'))
+			: change.name !== '$text'
+	);
+}
+
+/**
+ * Returns the view element and its ancestors, outermost first, without:
+ *
+ * * text attributes (attribute elements without a block inside, such as `<strong>` or `<a>`); list items (`<ul>`,
+ *   `<li>`) are attribute elements too, but wrap blocks,
+ * * elements that are not rendered in the data, such as the paragraph in a list item or a table cell that has only
+ *   one paragraph.
+ */
+function getPath(viewElement: ViewElement): ViewElement[] {
+	const path: ViewElement[] = [];
+	let hasBlock = false;
+
+	for (let node: ViewNode | ViewDocumentFragment | null = viewElement; node?.is('element'); node = node.parent) {
+		const isTextAttribute = node.is('attributeElement') && !hasBlock;
+
+		if (!isTextAttribute && !node.getCustomProperty('dataPipeline:transparentRendering')) {
+			path.unshift(node);
+		}
+
+		hasBlock ||= node.is('containerElement');
+	}
+
+	return path;
+}
+
+/**
+ * Creates the item of a view element. Its model element is the mapped one, or the closest mapped ancestor of a part of
+ * a structure (e.g. a `tbody` is a part of a table). List items have none: they come from the attributes of the blocks
+ * in them, not from an element.
+ */
+function createItem(viewElement: ViewElement, dataView: DataView): BreadcrumbItem {
+	let modelElement: ModelElement | null = null;
+
+	for (
+		let node: ViewNode | ViewDocumentFragment | null = viewElement;
+		node?.is('element') && !modelElement && !node.is('attributeElement');
+		node = node.parent
+	) {
+		modelElement = dataView.modelElements.get(node) ?? null;
+	}
+
+	return { label: [viewElement.name, ...viewElement.getClassNames()].join('.'), viewElement, modelElement };
+}
+
+function areEqual(a: readonly BreadcrumbItem[], b: readonly BreadcrumbItem[]): boolean {
+	return (
+		a.length === b.length &&
+		a.every((item, index) => item.label === b[index]?.label && item.modelElement === b[index].modelElement)
+	);
+}

package/src/contextMenu/contextMenuObserver.ts

@@ -0,0 +1,27 @@
+import { DomEventObserver, type ViewDocumentDomEventData } from 'ckeditor5';
+
+/**
+ * Fires the `contextmenu` event on the view document when the user opens the native context menu in an editable.
+ */
+export default class ContextMenuObserver extends DomEventObserver<'contextmenu'> {
+	// The base class declares it as an accessor, so it cannot be a field here.
+	// eslint-disable-next-line @typescript-eslint/class-literal-property-style
+	public get domEventType(): 'contextmenu' {
+		return 'contextmenu';
+	}
+
+	/**
+	 * Fires `contextmenu` on the view document for the DOM event.
+	 */
+	public onDomEvent(domEvent: MouseEvent): void {
+		this.fire(domEvent.type, domEvent);
+	}
+}
+
+/**
+ * Fired on the view document by the {@link ContextMenuObserver}.
+ */
+export interface ViewDocumentContextMenuEvent {
+	name: 'contextmenu';
+	args: [data: ViewDocumentDomEventData<MouseEvent>];
+}

package/src/contextMenu/elementContextMenu.ts

@@ -0,0 +1,104 @@
+import { Plugin, type ModelElement, type RectSource, type ViewElement } from 'ckeditor5';
+import { getElementAtSelection, getElementsAround, isInDocument } from 'ckeditor5-elements-core';
+import { getDomTarget } from '../domTarget.js';
+import ElementMenu from '../elementMenu.js';
+import ContextMenuObserver, { type ViewDocumentContextMenuEvent } from './contextMenuObserver.js';
+
+/**
+ * Shows the menu of an element when the user right-clicks it, or opens the context menu with the keyboard (the menu
+ * key, or Shift+F10) while the cursor is in it.
+ *
+ * The items come from the `elementContextMenu` editor config option only (see `ElementMenuConfig`): commands, submenus
+ * and `'|'` separators. Without it, or when it returns no items for an
+ * element, the native context menu shows. The menu itself is shown by the `ElementMenu` plugin.
+ */
+export default class ElementContextMenu extends Plugin {
+	public static get requires(): readonly [typeof ElementMenu] {
+		return [ElementMenu] as const;
+	}
+
+	public static get pluginName(): 'ElementContextMenu' {
+		return 'ElementContextMenu' as const;
+	}
+
+	public init(): void {
+		const editor = this.editor;
+		const editingView = editor.editing.view;
+
+		editingView.addObserver(ContextMenuObserver);
+
+		this.listenTo<ViewDocumentContextMenuEvent>(editingView.document, 'contextmenu', (evt, data) => {
+			const { domEvent } = data;
+			const element = this.getModelElement(data.target);
+
+			// A context menu opened with the keyboard (the menu key, or Shift+F10 in some browsers) targets the editable
+			// itself, not the element at the cursor. A right-click outside any element keeps the native menu.
+			const isOpen = element
+				? this.open(element, new DOMRect(domEvent.clientX, domEvent.clientY, 0, 0))
+				: domEvent.button !== 2 && this.openAtSelection();
+
+			if (isOpen) {
+				data.preventDefault();
+			}
+		});
+
+		// Not every browser opens the context menu on Shift+F10 (e.g. on macOS), so handle it in all of them.
+		editor.keystrokes.set('Shift+F10', (data, cancel) => {
+			if (this.openAtSelection()) {
+				cancel();
+			}
+		});
+
+		if (typeof editor.config.get('elementContextMenu') === 'function') {
+			editor.accessibility.addKeystrokeInfos({
+				keystrokes: [{ label: editor.t('Open the menu of the element at the cursor'), keystroke: 'Shift+F10' }]
+			});
+		}
+	}
+
+	/**
+	 * 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 `elementContextMenu` config option.
+	 *
+	 * Returns `false` when there are no items, so the caller can let the native context menu show instead.
+	 */
+	public open(element: ModelElement, target: RectSource): boolean {
+		const config = this.editor.config.get('elementContextMenu');
+
+		if (typeof config !== 'function') {
+			return false;
+		}
+
+		return this.editor.plugins
+			.get(ElementMenu)
+			.open(element, target, config, { label: this.editor.t('Element menu') });
+	}
+
+	/**
+	 * Opens the menu of the element at the selection (the selected element, or the element with the cursor), next to
+	 * the selection.
+	 *
+	 * Returns `false` when there is no such element or no items.
+	 */
+	public openAtSelection(): boolean {
+		const element = getElementAtSelection(this.editor.model.document.selection);
+		const target = getDomTarget(this.editor);
+
+		if (!element || !isInDocument(element) || !target) {
+			return false;
+		}
+
+		return this.open(element, target);
+	}
+
+	/**
+	 * Returns the closest model element mapped to the given view element or its ancestors, skipping the root.
+	 */
+	public getModelElement(viewElement: ViewElement): ModelElement | null {
+		for (const { element } of getElementsAround(this.editor.editing.mapper, viewElement)) {
+			return element;
+		}
+
+		return null;
+	}
+}

package/src/domTarget.ts

@@ -0,0 +1,27 @@
+import { ModelPosition, type Editor } from 'ckeditor5';
+import type { ElementOrPosition } from 'ckeditor5-elements-core';
+
+/**
+ * Returns what a menu for the target is shown next to: the DOM element of an element, or the DOM range of a position.
+ * Without a target, the ones of the selection: its selected element, or its range. `null` when it is not rendered.
+ */
+export function getDomTarget(editor: Editor, target?: ElementOrPosition): HTMLElement | Range | null {
+	const { mapper, view } = editor.editing;
+
+	if (target instanceof ModelPosition) {
+		return view.domConverter.viewRangeToDom(view.createRange(mapper.toViewPosition(target)));
+	}
+
+	const element = target ?? editor.model.document.selection.getSelectedElement();
+
+	if (element) {
+		const viewElement = mapper.toViewElement(element);
+		const domElement = viewElement && view.domConverter.mapViewToDom(viewElement);
+
+		return domElement instanceof HTMLElement ? domElement : null;
+	}
+
+	const viewRange = view.document.selection.getFirstRange();
+
+	return viewRange ? view.domConverter.viewRangeToDom(viewRange) : null;
+}