ckeditor5-elements-context-menu 0.0.0-stage → 49.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Kildyushov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# ckeditor5-elements-context-menu
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The element context menu of CKEditor 5 Elements: `ElementContextMenu` shows a menu of commands, submenus and separators
+for the right-clicked element, or the element at the cursor (the context menu key, Shift+F10).
+
+## Installation
+
+This package is part of `ckeditor5-elements`. Install the whole package to use it:
+
+```sh
+npm install ckeditor5 ckeditor5-elements
+```
+
+## Usage
+
+```ts
+import { ElementClipboard, ElementContextMenu } from 'ckeditor5-elements';
+import 'ckeditor5-elements/index.css';
+
+// In the editor config:
+plugins: [..., ElementContextMenu, ElementClipboard],
+elementContextMenu: (element, editor) => [editor.commands.get('copyElement'), editor.commands.get('cutElement')]
+```
+
+See the [Context menu guide](https://ivankild.github.io/ckeditor5-elements/guide/context-menu) of the documentation.
+
+## License
+
+MIT

package/dist/augmentation.d.ts

@@ -0,0 +1,15 @@
+import type { ElementMenuConfig } from 'ckeditor5-elements-core';
+import type { ElementContextMenu } from './index.js';
+declare module 'ckeditor5' {
+    interface PluginsMap {
+        [ElementContextMenu.pluginName]: ElementContextMenu;
+    }
+    interface EditorConfig {
+        /**
+         * Returns the items (commands, submenus and `'|'` separators) of the context menu of the right-clicked element.
+         * See {@link ElementContextMenu}.
+         */
+        elementContextMenu?: ElementMenuConfig;
+    }
+}
+//# sourceMappingURL=augmentation.d.ts.map

package/dist/augmentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"augmentation.d.ts","sourceRoot":"","sources":["../src/augmentation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,QAAQ,WAAW,CAAC;IAC1B,UAAU,UAAU;QACnB,CAAC,kBAAkB,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;KACpD;IAED,UAAU,YAAY;QACrB;;;WAGG;QACH,kBAAkB,CAAC,EAAE,iBAAiB,CAAC;KACvC;CACD"}

package/dist/augmentation.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=augmentation.js.map

package/dist/augmentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"augmentation.js","sourceRoot":"","sources":["../src/augmentation.ts"],"names":[],"mappings":""}

package/dist/contextMenuObserver.d.ts

@@ -0,0 +1,19 @@
+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'> {
+    get domEventType(): 'contextmenu';
+    /**
+     * Fires `contextmenu` on the view document for the DOM event.
+     */
+    onDomEvent(domEvent: MouseEvent): void;
+}
+/**
+ * Fired on the view document by the {@link ContextMenuObserver}.
+ */
+export interface ViewDocumentContextMenuEvent {
+    name: 'contextmenu';
+    args: [data: ViewDocumentDomEventData<MouseEvent>];
+}
+//# sourceMappingURL=contextMenuObserver.d.ts.map

package/dist/contextMenuObserver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextMenuObserver.d.ts","sourceRoot":"","sources":["../src/contextMenuObserver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAE5E;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAoB,SAAQ,gBAAgB,CAAC,aAAa,CAAC;IAG/E,IAAW,YAAY,IAAI,aAAa,CAEvC;IAED;;OAEG;IACI,UAAU,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI;CAG7C;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC5C,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,CAAC,IAAI,EAAE,wBAAwB,CAAC,UAAU,CAAC,CAAC,CAAC;CACnD"}

package/dist/contextMenuObserver.js

@@ -0,0 +1,18 @@
+import { DomEventObserver } 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 {
+    // 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
+    get domEventType() {
+        return 'contextmenu';
+    }
+    /**
+     * Fires `contextmenu` on the view document for the DOM event.
+     */
+    onDomEvent(domEvent) {
+        this.fire(domEvent.type, domEvent);
+    }
+}
+//# sourceMappingURL=contextMenuObserver.js.map

package/dist/contextMenuObserver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextMenuObserver.js","sourceRoot":"","sources":["../src/contextMenuObserver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAiC,MAAM,WAAW,CAAC;AAE5E;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAoB,SAAQ,gBAA+B;IAC/E,2EAA2E;IAC3E,2EAA2E;IAC3E,IAAW,YAAY;QACtB,OAAO,aAAa,CAAC;IACtB,CAAC;IAED;;OAEG;IACI,UAAU,CAAC,QAAoB;QACrC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACpC,CAAC;CACD"}

package/dist/elementContextMenu.d.ts

@@ -0,0 +1,34 @@
+import { Plugin, type ModelElement, type RectSource, type ViewElement } from 'ckeditor5';
+import { ElementMenu } from 'ckeditor5-elements-core';
+/**
+ * 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 {
+    static get requires(): readonly [typeof ElementMenu];
+    static get pluginName(): 'ElementContextMenu';
+    init(): void;
+    /**
+     * 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.
+     */
+    open(element: ModelElement, target: RectSource): boolean;
+    /**
+     * 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.
+     */
+    openAtSelection(): boolean;
+    /**
+     * Returns the closest model element mapped to the given view element or its ancestors, skipping the root.
+     */
+    getModelElement(viewElement: ViewElement): ModelElement | null;
+}
+//# sourceMappingURL=elementContextMenu.d.ts.map

package/dist/elementContextMenu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elementContextMenu.d.ts","sourceRoot":"","sources":["../src/elementContextMenu.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACzF,OAAO,EAAE,WAAW,EAAgB,MAAM,yBAAyB,CAAC;AAGpE;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,OAAO,kBAAmB,SAAQ,MAAM;IACrD,WAAkB,QAAQ,IAAI,SAAS,CAAC,OAAO,WAAW,CAAC,CAE1D;IAED,WAAkB,UAAU,IAAI,oBAAoB,CAEnD;IAEM,IAAI,IAAI,IAAI;IAmCnB;;;;;OAKG;IACI,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO;IAY/D;;;;;OAKG;IACI,eAAe,IAAI,OAAO;IAmBjC;;OAEG;IACI,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,YAAY,GAAG,IAAI;CAarE"}

package/dist/elementContextMenu.js

@@ -0,0 +1,98 @@
+import { Plugin } from 'ckeditor5';
+import { ElementMenu, isInDocument } from 'ckeditor5-elements-core';
+import ContextMenuObserver, {} 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 {
+    static get requires() {
+        return [ElementMenu];
+    }
+    static get pluginName() {
+        return 'ElementContextMenu';
+    }
+    init() {
+        const editor = this.editor;
+        const editingView = editor.editing.view;
+        editingView.addObserver(ContextMenuObserver);
+        this.listenTo(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.
+     */
+    open(element, target) {
+        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.
+     */
+    openAtSelection() {
+        const editing = this.editor.editing;
+        const selection = this.editor.model.document.selection;
+        const selectedElement = selection.getSelectedElement();
+        const parent = selection.getFirstPosition()?.parent;
+        const element = selectedElement ?? (parent?.is('element') && !parent.is('rootElement') ? parent : null);
+        const viewElement = selectedElement && editing.mapper.toViewElement(selectedElement);
+        const viewRange = editing.view.document.selection.getFirstRange();
+        const target = viewElement
+            ? editing.view.domConverter.mapViewToDom(viewElement)
+            : viewRange && editing.view.domConverter.viewRangeToDom(viewRange);
+        if (!element || !isInDocument(element) || !(target instanceof HTMLElement || target instanceof Range)) {
+            return false;
+        }
+        return this.open(element, target);
+    }
+    /**
+     * Returns the closest model element mapped to the given view element or its ancestors, skipping the root.
+     */
+    getModelElement(viewElement) {
+        const mapper = this.editor.editing.mapper;
+        for (let node = viewElement; node; node = node.parent?.is('element') ? node.parent : null) {
+            const element = mapper.toModelElement(node);
+            if (element) {
+                return element.is('rootElement') ? null : element;
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=elementContextMenu.js.map

package/dist/elementContextMenu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elementContextMenu.js","sourceRoot":"","sources":["../src/elementContextMenu.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The element context menu: right-clicking an element (or Shift+F10, or the menu key) opens the menu of the element,
+ * configured by the `elementContextMenu` option. The menus are shown by `ElementMenu` from `ckeditor5-elements-core`.
+ *
+ * @module ckeditor5-elements-context-menu
+ */
+export { default as ElementContextMenu } from './elementContextMenu.js';
+export { default as ContextMenuObserver, type ViewDocumentContextMenuEvent } from './contextMenuObserver.js';
+import './augmentation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGxE,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,KAAK,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAE7G,OAAO,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * The element context menu: right-clicking an element (or Shift+F10, or the menu key) opens the menu of the element,
+ * configured by the `elementContextMenu` option. The menus are shown by `ElementMenu` from `ckeditor5-elements-core`.
+ *
+ * @module ckeditor5-elements-context-menu
+ */
+// Plugins.
+export { default as ElementContextMenu } from './elementContextMenu.js';
+// Observer.
+export { default as ContextMenuObserver } from './contextMenuObserver.js';
+import './augmentation.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,WAAW;AACX,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAExE,YAAY;AACZ,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAqC,MAAM,0BAA0B,CAAC;AAE7G,OAAO,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "ckeditor5-elements-context-menu",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "49.0.0-alpha.0",
+  "description": "A context menu for CKEditor 5 elements: right-click an element, or press Shift+F10, to open a menu of commands for it.",
+  "keywords": [
+    "ckeditor",
+    "ckeditor5",
+    "ckeditor 5",
+    "ckeditor5-feature",
+    "ckeditor5-plugin"
+  ],
+  "license": "MIT",
+  "author": "Ivan Kildyushov",
+  "homepage": "https://ivankild.github.io/ckeditor5-elements/guide/context-menu",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ivankild/ckeditor5-elements.git",
+    "directory": "packages/ckeditor5-elements-context-menu"
+  },
+  "bugs": {
+    "url": "https://github.com/ivankild/ckeditor5-elements/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "ckeditor5-elements-core": "49.0.0-alpha.0"
+  },
+  "peerDependencies": {
+    "ckeditor5": ">=49.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build"
+  }
 }

package/src/augmentation.ts

@@ -0,0 +1,16 @@
+import type { ElementMenuConfig } from 'ckeditor5-elements-core';
+import type { ElementContextMenu } from './index.js';
+
+declare module 'ckeditor5' {
+	interface PluginsMap {
+		[ElementContextMenu.pluginName]: ElementContextMenu;
+	}
+
+	interface EditorConfig {
+		/**
+		 * Returns the items (commands, submenus and `'|'` separators) of the context menu of the right-clicked element.
+		 * See {@link ElementContextMenu}.
+		 */
+		elementContextMenu?: ElementMenuConfig;
+	}
+}

package/src/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/elementContextMenu.ts

@@ -0,0 +1,116 @@
+import { Plugin, type ModelElement, type RectSource, type ViewElement } from 'ckeditor5';
+import { ElementMenu, isInDocument } from 'ckeditor5-elements-core';
+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 editing = this.editor.editing;
+		const selection = this.editor.model.document.selection;
+		const selectedElement = selection.getSelectedElement();
+		const parent = selection.getFirstPosition()?.parent;
+		const element = selectedElement ?? (parent?.is('element') && !parent.is('rootElement') ? parent : null);
+		const viewElement = selectedElement && editing.mapper.toViewElement(selectedElement);
+		const viewRange = editing.view.document.selection.getFirstRange();
+		const target = viewElement
+			? editing.view.domConverter.mapViewToDom(viewElement)
+			: viewRange && editing.view.domConverter.viewRangeToDom(viewRange);
+
+		if (!element || !isInDocument(element) || !(target instanceof HTMLElement || target instanceof Range)) {
+			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 {
+		const mapper = this.editor.editing.mapper;
+
+		for (let node: ViewElement | null = viewElement; node; node = node.parent?.is('element') ? node.parent : null) {
+			const element = mapper.toModelElement(node);
+
+			if (element) {
+				return element.is('rootElement') ? null : element;
+			}
+		}
+
+		return null;
+	}
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * The element context menu: right-clicking an element (or Shift+F10, or the menu key) opens the menu of the element,
+ * configured by the `elementContextMenu` option. The menus are shown by `ElementMenu` from `ckeditor5-elements-core`.
+ *
+ * @module ckeditor5-elements-context-menu
+ */
+
+// Plugins.
+export { default as ElementContextMenu } from './elementContextMenu.js';
+
+// Observer.
+export { default as ContextMenuObserver, type ViewDocumentContextMenuEvent } from './contextMenuObserver.js';
+
+import './augmentation.js';