ckeditor5-elements-quick-insert 0.0.0-stage → 49.0.0-alpha.0

package/dist/quickInsertPositionCommand.js

@@ -0,0 +1,54 @@
+import {} from 'ckeditor5';
+import { ElementOrPositionCommand } from 'ckeditor5-elements-core';
+import { insertAfterIcon, insertBeforeIcon } from './icons.js';
+/**
+ * Opens the quick insert menu for the position before or after an element, next to that element.
+ *
+ * The element is the given one, the parent of the given position, or the selected element or the parent of the
+ * selection (see {@link ElementOrPositionCommand}). Enabled when something can be inserted at that position.
+ *
+ * Requires the `QuickInsert` plugin, which registers it as `quickInsertBefore` and `quickInsertAfter`.
+ */
+export default class QuickInsertPositionCommand extends ElementOrPositionCommand {
+    /**
+     * Where the quick insert menu inserts, relative to the element.
+     */
+    placement;
+    constructor(editor, placement) {
+        super(editor);
+        this.placement = placement;
+        this.title = placement === 'before' ? editor.t('Insert before') : editor.t('Insert after');
+        this.icon = placement === 'before' ? insertBeforeIcon : insertAfterIcon;
+    }
+    /**
+     * Opens the quick insert menu for the position before or after the element, next to the element.
+     */
+    execute(elementOrPosition) {
+        const editor = this.editor;
+        const element = this._getElement(elementOrPosition);
+        const position = this._getInsertPosition(elementOrPosition);
+        if (!element || !position) {
+            return;
+        }
+        const viewElement = editor.editing.mapper.toViewElement(element);
+        const domElement = viewElement && editor.editing.view.domConverter.mapViewToDom(viewElement);
+        editor.plugins.get('QuickInsert').open(position, domElement ?? undefined);
+    }
+    _isEnabledFor(elementOrPosition) {
+        const position = this._getInsertPosition(elementOrPosition);
+        const plugins = this.editor.plugins;
+        return (!!position &&
+            this.editor.model.canEditAt(position) &&
+            plugins.has('QuickInsert') &&
+            plugins.get('QuickInsert').getItems(position).length > 0);
+    }
+    _getInsertPosition(elementOrPosition) {
+        const element = this._getElement(elementOrPosition);
+        const model = this.editor.model;
+        if (!element) {
+            return null;
+        }
+        return this.placement === 'before' ? model.createPositionBefore(element) : model.createPositionAfter(element);
+    }
+}
+//# sourceMappingURL=quickInsertPositionCommand.js.map

package/dist/quickInsertPositionCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickInsertPositionCommand.js","sourceRoot":"","sources":["../src/quickInsertPositionCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAA0B,MAAM,yBAAyB,CAAC;AAC3F,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAO/D;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,OAAO,0BAA2B,SAAQ,wBAAwB;IAC/E;;OAEG;IACa,SAAS,CAAuB;IAEhD,YAAY,MAAc,EAAE,SAA+B;QAC1D,KAAK,CAAC,MAAM,CAAC,CAAC;QAEd,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;QAC3F,IAAI,CAAC,IAAI,GAAG,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,eAAe,CAAC;IACzE,CAAC;IAED;;OAEG;IACa,OAAO,CAAC,iBAAqC;QAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAC;QAE5D,IAAI,CAAC,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC3B,OAAO;QACR,CAAC;QAED,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QACjE,MAAM,UAAU,GAAG,WAAW,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;QAE7F,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,IAAI,SAAS,CAAC,CAAC;IAC3E,CAAC;IAEkB,aAAa,CAAC,iBAAqC;QACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAC;QAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;QAEpC,OAAO,CACN,CAAC,CAAC,QAAQ;YACV,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC;YACrC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;YAC1B,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,CACxD,CAAC;IACH,CAAC;IAEO,kBAAkB,CAAC,iBAAqC;QAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;QAEhC,IAAI,CAAC,OAAO,EAAE,CAAC;YACd,OAAO,IAAI,CAAC;QACb,CAAC;QAED,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC/G,CAAC;CACD"}

package/dist/quickInsertView.d.ts

@@ -0,0 +1,20 @@
+import { SearchTextView, type Locale } from 'ckeditor5';
+import QuickInsertListView, { type QuickInsertItem } from './quickInsertListView.js';
+/**
+ * A search field with a filtered list of insertable elements.
+ *
+ * In the search field, Enter chooses the first matching item and the down arrow moves the focus to the list.
+ * Fires `execute` with `{ value: name }` when an item is chosen.
+ */
+export default class QuickInsertView extends SearchTextView {
+    /**
+     * The list of elements.
+     */
+    readonly listView: QuickInsertListView;
+    constructor(locale: Locale, items: readonly QuickInsertItem[]);
+    /**
+     * Renders the view and sets up Enter (choose the first match) and the down arrow (go to the list) in the search field.
+     */
+    render(): void;
+}
+//# sourceMappingURL=quickInsertView.d.ts.map

package/dist/quickInsertView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickInsertView.d.ts","sourceRoot":"","sources":["../src/quickInsertView.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAiC,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AACvF,OAAO,mBAAmB,EAAE,EAAE,KAAK,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAErF;;;;;GAKG;AACH,MAAM,CAAC,OAAO,OAAO,eAAgB,SAAQ,cAAc;IAC1D;;OAEG;IACH,SAAgB,QAAQ,EAAE,mBAAmB,CAAC;gBAElC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,eAAe,EAAE;IAoB7D;;OAEG;IACa,MAAM,IAAI,IAAI;CAyB9B"}

package/dist/quickInsertView.js

@@ -0,0 +1,52 @@
+import { SearchTextView } from 'ckeditor5';
+import QuickInsertListView, {} from './quickInsertListView.js';
+/**
+ * A search field with a filtered list of insertable elements.
+ *
+ * In the search field, Enter chooses the first matching item and the down arrow moves the focus to the list.
+ * Fires `execute` with `{ value: name }` when an item is chosen.
+ */
+export default class QuickInsertView extends SearchTextView {
+    /**
+     * The list of elements.
+     */
+    listView;
+    constructor(locale, items) {
+        const listView = new QuickInsertListView(locale, items);
+        const t = locale.t;
+        super(locale, {
+            queryView: { label: t('Insert element') },
+            filteredView: listView,
+            infoView: {
+                text: {
+                    notFound: { primary: t('No matching elements') },
+                    noSearchableItems: { primary: t('No elements can be inserted here') }
+                }
+            },
+            class: 'ck-elements-quick-insert'
+        });
+        this.listView = listView;
+        listView.delegate('execute').to(this);
+    }
+    /**
+     * Renders the view and sets up Enter (choose the first match) and the down arrow (go to the list) in the search field.
+     */
+    render() {
+        super.render();
+        const isInQueryField = () => this.focusTracker.focusedElement === this.queryView.element;
+        this.keystrokes.set('enter', (data, cancel) => {
+            const item = isInQueryField() ? this.listView.getFirstVisibleItem() : null;
+            if (item) {
+                this.fire('execute', { value: item.name });
+                cancel();
+            }
+        });
+        this.keystrokes.set('arrowdown', (data, cancel) => {
+            if (isInQueryField()) {
+                this.listView.focusFirst();
+                cancel();
+            }
+        }, { priority: 'high' });
+    }
+}
+//# sourceMappingURL=quickInsertView.js.map

package/dist/quickInsertView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickInsertView.js","sourceRoot":"","sources":["../src/quickInsertView.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAA8C,MAAM,WAAW,CAAC;AACvF,OAAO,mBAAmB,EAAE,EAAwB,MAAM,0BAA0B,CAAC;AAErF;;;;;GAKG;AACH,MAAM,CAAC,OAAO,OAAO,eAAgB,SAAQ,cAAc;IAC1D;;OAEG;IACa,QAAQ,CAAsB;IAE9C,YAAY,MAAc,EAAE,KAAiC;QAC5D,MAAM,QAAQ,GAAG,IAAI,mBAAmB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACxD,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;QAEnB,KAAK,CAAC,MAAM,EAAE;YACb,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,gBAAgB,CAAC,EAAE;YACzC,YAAY,EAAE,QAAQ;YACtB,QAAQ,EAAE;gBACT,IAAI,EAAE;oBACL,QAAQ,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,sBAAsB,CAAC,EAAE;oBAChD,iBAAiB,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,kCAAkC,CAAC,EAAE;iBACrE;aACD;YACD,KAAK,EAAE,0BAA0B;SACjC,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACa,MAAM;QACrB,KAAK,CAAC,MAAM,EAAE,CAAC;QAEf,MAAM,cAAc,GAAG,GAAY,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,cAAc,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QAElG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YAC7C,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;YAE3E,IAAI,IAAI,EAAE,CAAC;gBACV,IAAI,CAAC,IAAI,CAA2B,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;gBACrE,MAAM,EAAE,CAAC;YACV,CAAC;QACF,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,UAAU,CAAC,GAAG,CAClB,WAAW,EACX,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YAChB,IAAI,cAAc,EAAE,EAAE,CAAC;gBACtB,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;gBAC3B,MAAM,EAAE,CAAC;YACV,CAAC;QACF,CAAC,EACD,EAAE,QAAQ,EAAE,MAAM,EAAE,CACpB,CAAC;IACH,CAAC;CACD"}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "ckeditor5-elements-quick-insert",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "49.0.0-alpha.0",
+  "description": "Quick insert for CKEditor 5: search and insert the elements allowed at a position (Alt+Enter, or the context menu).",
+  "keywords": [
+    "ckeditor",
+    "ckeditor5",
+    "ckeditor 5",
+    "ckeditor5-feature",
+    "ckeditor5-plugin"
+  ],
+  "license": "MIT",
+  "author": "Ivan Kildyushov",
+  "homepage": "https://ivankild.github.io/ckeditor5-elements/guide/quick-insert",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ivankild/ckeditor5-elements.git",
+    "directory": "packages/ckeditor5-elements-quick-insert"
+  },
+  "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"
+    },
+    "./index.css": "./theme/quickInsert.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "theme",
+    "README.md"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "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,20 @@
+import type { QuickInsert, QuickInsertCommand, QuickInsertConfig, QuickInsertPositionCommand } from './index.js';
+
+declare module 'ckeditor5' {
+	interface PluginsMap {
+		[QuickInsert.pluginName]: QuickInsert;
+	}
+
+	interface CommandsMap {
+		quickInsert: QuickInsertCommand;
+		quickInsertBefore: QuickInsertPositionCommand;
+		quickInsertAfter: QuickInsertPositionCommand;
+	}
+
+	interface EditorConfig {
+		/**
+		 * The configuration of the {@link QuickInsert} plugin.
+		 */
+		quickInsert?: QuickInsertConfig;
+	}
+}

package/src/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>';

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Quick insert: search and insert the elements allowed at a position.
+ *
+ * @module ckeditor5-elements-quick-insert
+ */
+
+// Plugins.
+export { default as QuickInsert, type QuickInsertConfig } from './quickInsert.js';
+
+// Commands.
+export { default as QuickInsertCommand } from './quickInsertCommand.js';
+export { default as QuickInsertPositionCommand, type QuickInsertPlacement } from './quickInsertPositionCommand.js';
+
+// Views.
+export { default as QuickInsertView } from './quickInsertView.js';
+export { default as QuickInsertListView, type QuickInsertItem } from './quickInsertListView.js';
+
+// Icons.
+export { insertAfterIcon, insertBeforeIcon, insertIcon } from './icons.js';
+
+import './augmentation.js';

package/src/quickInsert.ts

@@ -0,0 +1,148 @@
+import { Plugin, type Editor, type FilteredViewExecuteEvent, type ModelElement, type RectSource } from 'ckeditor5';
+import { ElementMenu, type ElementOrPosition } from 'ckeditor5-elements-core';
+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 QuickInsert} plugin.
+ */
+export interface QuickInsertConfig {
+	/**
+	 * 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 QuickInsertConfig.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 QuickInsert extends Plugin {
+	public static get requires(): readonly [typeof ElementMenu] {
+		return [ElementMenu] as const;
+	}
+
+	public static get pluginName(): 'QuickInsert' {
+		return 'QuickInsert' as const;
+	}
+
+	constructor(editor: Editor) {
+		super(editor);
+
+		editor.config.define('quickInsert', { labels: {}, exclude: [], keystroke: 'Alt+Enter' });
+	}
+
+	public init(): void {
+		const editor = this.editor;
+		const keystroke = editor.config.get('quickInsert')?.keystroke;
+
+		editor.commands.add('quickInsert', new QuickInsertCommand(editor));
+		editor.commands.add('quickInsertBefore', new QuickInsertPositionCommand(editor, 'before'));
+		editor.commands.add('quickInsertAfter', new QuickInsertPositionCommand(editor, 'after'));
+
+		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('quickInsert');
+		const labels = config?.labels ?? {};
+		const command = this.editor.commands.get('quickInsert');
+
+		return (command?.getAllowedElements(elementOrPosition, config?.exclude) ?? []).map(name => ({
+			name,
+			label: labels[name] ?? name
+		}));
+	}
+
+	/**
+	 * 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 ?? this._getDomTarget(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;
+	}
+
+	/**
+	 * Returns the DOM element of the element, or the DOM range of the selection.
+	 */
+	private _getDomTarget(elementOrPosition?: ElementOrPosition): RectSource | null {
+		const editing = this.editor.editing;
+
+		if (elementOrPosition && !elementOrPosition.is('position')) {
+			return this._getDomElement(elementOrPosition);
+		}
+
+		const viewRange = elementOrPosition
+			? editing.view.createRange(editing.mapper.toViewPosition(elementOrPosition))
+			: editing.view.document.selection.getFirstRange();
+
+		return viewRange && editing.view.domConverter.viewRangeToDom(viewRange);
+	}
+
+	private _getDomElement(element: ModelElement): HTMLElement | null {
+		const editing = this.editor.editing;
+		const viewElement = editing.mapper.toViewElement(element);
+		const domElement = viewElement && editing.view.domConverter.mapViewToDom(viewElement);
+
+		return domElement instanceof HTMLElement ? domElement : null;
+	}
+}

package/src/quickInsertCommand.ts

@@ -0,0 +1,103 @@
+import { type Editor, type ModelElement, type ModelPosition, type ModelWriter } from 'ckeditor5';
+import { ElementOrPositionCommand, type ElementOrPosition } from 'ckeditor5-elements-core';
+import { insertIcon } from './icons.js';
+
+/**
+ * Inserts an element by its model name at a position, or opens the quick insert menu for that position.
+ *
+ * The target comes first, as in every {@link ElementOrPositionCommand}: a position, an element (meaning the position
+ * before it), or none (the selection).
+ *
+ * ```ts
+ * editor.execute('quickInsert', position, 'heading1'); // Inserts a heading at the position.
+ * editor.execute('quickInsert'); // Opens the quick insert menu at the selection.
+ * ```
+ *
+ * Only elements that the schema allows at exactly that position are inserted (see {@link getAllowedElements}):
+ * nothing is split to make room, so e.g. a heading cannot be inserted inside a paragraph.
+ *
+ * After inserting, objects are selected; other elements get the selection inside them, in a new paragraph when they
+ * can hold blocks.
+ */
+export default class QuickInsertCommand extends ElementOrPositionCommand {
+	constructor(editor: Editor) {
+		super(editor);
+
+		this.title = editor.t('Insert element');
+		this.icon = insertIcon;
+	}
+
+	/**
+	 * Returns the names of the model elements allowed at exactly the position (or the selection), in the order they
+	 * were registered. Generic items (such as `$text` or `$block`) and the excluded names are skipped.
+	 */
+	public getAllowedElements(elementOrPosition?: ElementOrPosition, exclude: readonly string[] = []): string[] {
+		const target = this._getPosition(elementOrPosition);
+
+		if (!target) {
+			return [];
+		}
+
+		const schema = this.editor.model.schema;
+
+		return Object.keys(schema.getDefinitions()).filter(
+			name => !name.startsWith('$') && !exclude.includes(name) && schema.checkChild(target, name)
+		);
+	}
+
+	/**
+	 * Returns the position where elements are inserted for the target: the position, the position before the element,
+	 * or the selection.
+	 */
+	public getInsertPosition(elementOrPosition?: ElementOrPosition): ModelPosition | null {
+		return this._getPosition(elementOrPosition);
+	}
+
+	/**
+	 * Inserts the element named `name` at the target, when the schema allows it there. Without a name, opens the quick
+	 * insert menu for the target (requires the `QuickInsert` plugin).
+	 */
+	public override execute(elementOrPosition?: ElementOrPosition, name?: string): void {
+		if (name === undefined) {
+			const plugins = this.editor.plugins;
+
+			if (plugins.has('QuickInsert')) {
+				plugins.get('QuickInsert').open(elementOrPosition);
+			}
+
+			return;
+		}
+
+		const model = this.editor.model;
+		const target = this._getPosition(elementOrPosition);
+
+		if (!target || !model.canEditAt(target) || !model.schema.checkChild(target, name)) {
+			return;
+		}
+
+		model.change(writer => {
+			const element = writer.createElement(name);
+
+			writer.insert(element, target);
+			this._setSelection(writer, element);
+		});
+	}
+
+	private _setSelection(writer: ModelWriter, element: ModelElement): void {
+		const schema = this.editor.model.schema;
+
+		if (schema.isObject(element)) {
+			writer.setSelection(element, 'on');
+		} else if (schema.checkChild(element, '$text')) {
+			writer.setSelection(element, 0);
+		} else if (schema.checkChild(element, 'paragraph')) {
+			const paragraph = writer.createElement('paragraph');
+
+			writer.append(paragraph, element);
+			writer.setSelection(paragraph, 0);
+		} else {
+			// Only objects can be selected as a whole. The selection post-fixer moves it to the closest valid place.
+			writer.setSelection(element, 'after');
+		}
+	}
+}

package/src/quickInsertListView.ts

@@ -0,0 +1,71 @@
+import {
+	ButtonView,
+	ListItemView,
+	ListView,
+	type FilteredView,
+	type FilteredViewExecuteEvent,
+	type Locale
+} from 'ckeditor5';
+
+/**
+ * An element that can be inserted: its model name and the label shown in the list.
+ */
+export interface QuickInsertItem {
+	name: string;
+	label: string;
+}
+
+/**
+ * A list of insertable elements that can be filtered by a search query.
+ *
+ * Fires `execute` with `{ value: name }` when an item is chosen.
+ */
+export default class QuickInsertListView extends ListView implements FilteredView {
+	private readonly _entries: { item: QuickInsertItem; view: ListItemView; button: ButtonView }[];
+
+	constructor(locale: Locale, items: readonly QuickInsertItem[]) {
+		super(locale);
+
+		this.role = 'listbox';
+
+		this._entries = items.map(item => {
+			const view = new ListItemView(locale);
+			const button = new ButtonView(locale);
+
+			button.set({ label: item.label, withText: true, role: 'option' });
+			button.on('execute', () => {
+				this.fire<FilteredViewExecuteEvent>('execute', { value: item.name });
+			});
+
+			view.children.add(button);
+
+			return { item, view, button };
+		});
+
+		this.items.addMany(this._entries.map(entry => entry.view));
+	}
+
+	/**
+	 * Shows only the items whose label or name matches the expression. `null` shows all items.
+	 */
+	public filter(regExp: RegExp | null): { resultsCount: number; totalItemsCount: number } {
+		let resultsCount = 0;
+
+		for (const { item, view } of this._entries) {
+			view.isVisible = !regExp || regExp.test(item.label) || regExp.test(item.name);
+
+			if (view.isVisible) {
+				resultsCount++;
+			}
+		}
+
+		return { resultsCount, totalItemsCount: this._entries.length };
+	}
+
+	/**
+	 * Returns the first item that is not filtered out.
+	 */
+	public getFirstVisibleItem(): QuickInsertItem | null {
+		return this._entries.find(entry => entry.view.isVisible)?.item ?? null;
+	}
+}

package/src/quickInsertPositionCommand.ts

@@ -0,0 +1,72 @@
+import { type Editor, type ModelPosition } from 'ckeditor5';
+import { ElementOrPositionCommand, type ElementOrPosition } from 'ckeditor5-elements-core';
+import { insertAfterIcon, insertBeforeIcon } from './icons.js';
+
+/**
+ * Where the quick insert menu inserts, relative to the element.
+ */
+export type QuickInsertPlacement = 'before' | 'after';
+
+/**
+ * Opens the quick insert menu for the position before or after an element, next to that element.
+ *
+ * The element is the given one, the parent of the given position, or the selected element or the parent of the
+ * selection (see {@link ElementOrPositionCommand}). Enabled when something can be inserted at that position.
+ *
+ * Requires the `QuickInsert` plugin, which registers it as `quickInsertBefore` and `quickInsertAfter`.
+ */
+export default class QuickInsertPositionCommand extends ElementOrPositionCommand {
+	/**
+	 * Where the quick insert menu inserts, relative to the element.
+	 */
+	public readonly placement: QuickInsertPlacement;
+
+	constructor(editor: Editor, placement: QuickInsertPlacement) {
+		super(editor);
+
+		this.placement = placement;
+		this.title = placement === 'before' ? editor.t('Insert before') : editor.t('Insert after');
+		this.icon = placement === 'before' ? insertBeforeIcon : insertAfterIcon;
+	}
+
+	/**
+	 * Opens the quick insert menu for the position before or after the element, next to the element.
+	 */
+	public override execute(elementOrPosition?: ElementOrPosition): void {
+		const editor = this.editor;
+		const element = this._getElement(elementOrPosition);
+		const position = this._getInsertPosition(elementOrPosition);
+
+		if (!element || !position) {
+			return;
+		}
+
+		const viewElement = editor.editing.mapper.toViewElement(element);
+		const domElement = viewElement && editor.editing.view.domConverter.mapViewToDom(viewElement);
+
+		editor.plugins.get('QuickInsert').open(position, domElement ?? undefined);
+	}
+
+	protected override _isEnabledFor(elementOrPosition?: ElementOrPosition): boolean {
+		const position = this._getInsertPosition(elementOrPosition);
+		const plugins = this.editor.plugins;
+
+		return (
+			!!position &&
+			this.editor.model.canEditAt(position) &&
+			plugins.has('QuickInsert') &&
+			plugins.get('QuickInsert').getItems(position).length > 0
+		);
+	}
+
+	private _getInsertPosition(elementOrPosition?: ElementOrPosition): ModelPosition | null {
+		const element = this._getElement(elementOrPosition);
+		const model = this.editor.model;
+
+		if (!element) {
+			return null;
+		}
+
+		return this.placement === 'before' ? model.createPositionBefore(element) : model.createPositionAfter(element);
+	}
+}