ckeditor5-elements-menu 0.0.0-stage → 49.0.0

package/src/quickInsert/quickInsertCommand.ts

@@ -0,0 +1,96 @@
+import { type Editor, type ModelPosition } from 'ckeditor5';
+import { ElementOrPositionCommand, selectNewElement, type ElementOrPosition } from 'ckeditor5-elements-core';
+import { insertIcon } from './icons.js';
+
+/**
+ * Inserts an element by its model name at a position: what the quick insert menu does, when an element is chosen. The
+ * menu itself is opened by the `ElementQuickInsert` plugin, with its `open()`.
+ *
+ * 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', undefined, 'softBreak'); // Inserts a line break 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[] {
+		return Array.from(this._getAllowedElements(elementOrPosition, exclude));
+	}
+
+	/**
+	 * Whether an element is allowed at exactly the position (or the selection), as {@link getAllowedElements} returns
+	 * them: it stops at the first one.
+	 */
+	public hasAllowedElements(elementOrPosition?: ElementOrPosition, exclude: readonly string[] = []): boolean {
+		return !this._getAllowedElements(elementOrPosition, exclude).next().done;
+	}
+
+	/**
+	 * 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.
+	 */
+	public override execute(elementOrPosition: ElementOrPosition | undefined, name: string): void {
+		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);
+			selectNewElement(writer, element);
+		});
+	}
+
+	/**
+	 * Yields the names of the elements allowed at exactly the position (or the selection), one by one.
+	 */
+	private *_getAllowedElements(
+		elementOrPosition: ElementOrPosition | undefined,
+		exclude: readonly string[]
+	): Generator<string> {
+		const target = this._getPosition(elementOrPosition);
+
+		if (!target) {
+			return;
+		}
+
+		const schema = this.editor.model.schema;
+		const excluded = new Set(exclude);
+
+		for (const name of Object.keys(schema.getDefinitions())) {
+			if (!name.startsWith('$') && !excluded.has(name) && schema.checkChild(target, name)) {
+				yield name;
+			}
+		}
+	}
+}

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

@@ -0,0 +1,68 @@
+import { type Editor, type ModelPosition } from 'ckeditor5';
+import { ElementOrPositionCommand, type ElementOrPosition } from 'ckeditor5-elements-core';
+import { getDomTarget } from '../domTarget.js';
+import type ElementQuickInsert from './elementQuickInsert.js';
+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.
+ *
+ * The `ElementQuickInsert` plugin registers it as `quickInsertBefore` and `quickInsertAfter`, for its menu.
+ */
+export default class QuickInsertPositionCommand extends ElementOrPositionCommand {
+	/**
+	 * Where the quick insert menu inserts, relative to the element.
+	 */
+	public readonly placement: QuickInsertPlacement;
+
+	/**
+	 * The plugin whose menu the command opens.
+	 */
+	private readonly _quickInsert: ElementQuickInsert;
+
+	constructor(editor: Editor, placement: QuickInsertPlacement, quickInsert: ElementQuickInsert) {
+		super(editor);
+
+		this.placement = placement;
+		this._quickInsert = quickInsert;
+		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 element = this._getElement(elementOrPosition);
+		const position = this._getInsertPosition(elementOrPosition);
+
+		if (element && position) {
+			this._quickInsert.open(position, getDomTarget(this.editor, element) ?? undefined);
+		}
+	}
+
+	protected override _isEnabledFor(elementOrPosition?: ElementOrPosition): boolean {
+		const position = this._getInsertPosition(elementOrPosition);
+
+		return !!position && this.editor.model.canEditAt(position) && this._quickInsert.hasItems(position);
+	}
+
+	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);
+	}
+}

package/src/quickInsert/quickInsertView.ts

@@ -0,0 +1,64 @@
+import { SearchTextView, type FilteredViewExecuteEvent, 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.
+	 */
+	public readonly listView: QuickInsertListView;
+
+	constructor(locale: Locale, items: readonly QuickInsertItem[]) {
+		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.
+	 */
+	public override render(): void {
+		super.render();
+
+		const isInQueryField = (): boolean => this.focusTracker.focusedElement === this.queryView.element;
+
+		this.keystrokes.set('enter', (data, cancel) => {
+			const item = isInQueryField() ? this.listView.getFirstVisibleItem() : null;
+
+			if (item) {
+				this.fire<FilteredViewExecuteEvent>('execute', { value: item.name });
+				cancel();
+			}
+		});
+
+		this.keystrokes.set(
+			'arrowdown',
+			(data, cancel) => {
+				if (isInQueryField()) {
+					this.listView.focusFirst();
+					cancel();
+				}
+			},
+			{ priority: 'high' }
+		);
+	}
+}

package/theme/menu.css

@@ -0,0 +1,131 @@
+/*
+ * 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));
+}
+
+/*
+ * The element path: ancestors are muted, the innermost element (where the cursor is) is emphasised. Items are separated
+ * by chevrons. Buttons (with a menu) and labels (without one) look the same, except buttons react to hover and focus.
+ */
+.ck.ck-elements-breadcrumbs {
+	--ck-elements-breadcrumbs-item-height: 24px;
+	--ck-elements-breadcrumbs-separator-size: 0.38em;
+
+	display: flex;
+	align-items: center;
+	min-width: 0;
+	font-size: var(--ck-font-size-sm);
+	color: var(--ck-color-text);
+}
+
+.ck.ck-toolbar .ck.ck-elements-breadcrumbs {
+	min-height: var(--ck-size-control-min-height);
+}
+
+.ck.ck-elements-breadcrumbs__list {
+	display: flex;
+	flex-wrap: wrap;
+	align-items: center;
+	gap: 2px 0;
+	min-width: 0;
+	margin: 0;
+	padding: 0;
+	list-style: none;
+}
+
+.ck.ck-elements-breadcrumbs__list-item {
+	display: flex;
+	align-items: center;
+	min-width: 0;
+	margin: 0;
+	padding: 0;
+}
+
+/* Both item kinds: buttons and labels. */
+.ck.ck-elements-breadcrumbs__item,
+.ck.ck-button.ck-elements-breadcrumbs__item {
+	display: inline-flex;
+	align-items: center;
+	min-width: 0;
+	min-height: var(--ck-elements-breadcrumbs-item-height);
+	height: var(--ck-elements-breadcrumbs-item-height);
+	padding: 0 var(--ck-spacing-sm);
+	border-radius: var(--ck-border-radius-control);
+	font-family: var(--ck-font-family);
+	font-size: inherit;
+	line-height: 1;
+	white-space: nowrap;
+	color: color-mix(in srgb, var(--ck-color-text) 65%, transparent);
+}
+
+.ck.ck-button.ck-elements-breadcrumbs__item .ck-button__label {
+	font-size: inherit;
+	line-height: 1;
+}
+
+/* The innermost element: where the cursor is. */
+.ck.ck-elements-breadcrumbs__item[aria-current] {
+	color: var(--ck-color-text);
+	font-weight: 600;
+}
+
+/* Labels cannot be clicked, but can be focused with the keyboard. */
+.ck.ck-elements-breadcrumbs__label {
+	cursor: default;
+}
+
+.ck.ck-elements-breadcrumbs__label:focus {
+	outline: none;
+	box-shadow:
+		0 0 0 1px var(--ck-color-focus-border),
+		var(--ck-focus-shadow);
+}
+
+/* Buttons show they can be clicked. */
+.ck.ck-button.ck-elements-breadcrumbs__item:hover,
+.ck.ck-button.ck-elements-breadcrumbs__item:focus,
+.ck.ck-button.ck-elements-breadcrumbs__item.ck-on {
+	color: var(--ck-color-text);
+}
+
+/* A chevron between items, in the gap before each item, so it is not part of a button's hover area. */
+.ck.ck-elements-breadcrumbs__list-item + .ck.ck-elements-breadcrumbs__list-item {
+	position: relative;
+	margin-left: calc(var(--ck-spacing-base) + var(--ck-elements-breadcrumbs-separator-size));
+}
+
+.ck.ck-elements-breadcrumbs__list-item + .ck.ck-elements-breadcrumbs__list-item::before {
+	content: '';
+	position: absolute;
+	top: 50%;
+	left: calc(-0.5 * var(--ck-spacing-base) - var(--ck-elements-breadcrumbs-separator-size));
+	width: var(--ck-elements-breadcrumbs-separator-size);
+	height: var(--ck-elements-breadcrumbs-separator-size);
+	border-top: 1.5px solid color-mix(in srgb, var(--ck-color-text) 40%, transparent);
+	border-right: 1.5px solid color-mix(in srgb, var(--ck-color-text) 40%, transparent);
+	transform: translateY(-50%) rotate(45deg);
+	pointer-events: none;
+}
+
+.ck.ck-elements-quick-insert {
+	width: 260px;
+}
+
+.ck.ck-elements-quick-insert .ck-search__results {
+	max-height: 240px;
+	overflow-y: auto;
+}
+
+.ck.ck-elements-quick-insert .ck-list__item > .ck.ck-button {
+	width: 100%;
+}