ckeditor5-elements-schema 0.0.0-stage → 49.0.0-alpha.4

package/src/definition/types.ts

@@ -0,0 +1,123 @@
+/**
+ * The kinds of elements of an element schema:
+ *
+ * * `empty`: has no content, like an image or a line break. It is an object: selected as a whole.
+ * * `block`: can contain text and inline elements, like a paragraph or a heading. With `isInline`, it is an inline
+ *   element with text, like a bold with an `id`.
+ *
+ * * `container`: cannot contain text; holds blocks, empty block elements and other containers, like a block quote or a
+ *   note.
+ *
+ * Every type can be inline (see {@link ElementSchemaElement#isInline}): the type says what the element holds, `isInline`
+ * where and how it is laid out. Inline elements are allowed only in blocks.
+ */
+export type ElementSchemaType = 'empty' | 'block' | 'container';
+
+/**
+ * The kind of an element: what it is, and whether it is inline: laid out in a line with its siblings, instead of on a
+ * line of its own. Any type can be inline.
+ */
+export interface ElementSchemaKind {
+	type: ElementSchemaType;
+	isInline: boolean;
+}
+
+/**
+ * The definition of one element of an element schema.
+ */
+export interface ElementSchemaElement {
+	/**
+	 * What the element is: `'empty'`, `'block'` or `'container'`.
+	 */
+	type: ElementSchemaType;
+
+	/**
+	 * Whether the element is inline: it is about the position and the layout of the element, not about text. An inline
+	 * element is laid out in a line with its siblings, where a block-level one has a line of its own. Any type can be:
+	 *
+	 * * `empty`: like an inline image, or a line break;
+	 * * `block`: an element with text in a line of text, like a bold that is an element, with attributes;
+	 * * `container`: a box that is not typable, in a line with other boxes, e.g. several in a block.
+	 *
+	 * Inline elements are allowed only in blocks: by default, where text is. A block holds text and any number of inline
+	 * elements; containers and the root hold no inline elements. Default: `false`.
+	 */
+	isInline?: boolean;
+
+	/**
+	 * The elements allowed inside this one, in addition to what its type allows: names of elements of the schema, or of
+	 * elements of other plugins, and `'$text'`. As in CKEditor's `allowChildren`.
+	 *
+	 * What a type allows by default: a `block` has text and inline elements; a `container` has blocks, containers and
+	 * `empty` block-level elements.
+	 */
+	allowChildren?: string[];
+
+	/**
+	 * The elements this one is allowed in, in addition to what its type allows: names of elements, and `'$root'`. As in
+	 * CKEditor's `allowIn`.
+	 *
+	 * Unlike in CKEditor, when it is given it **replaces** the default places (a block-level element is allowed in the
+	 * root and in containers; an inline element, where text is), so that an element can be restricted to its parent,
+	 * e.g. a row to a table.
+	 */
+	allowIn?: string[];
+
+	/**
+	 * The attributes the element can have, as in CKEditor's `allowAttributes`.
+	 */
+	allowAttributes?: string[];
+
+	/**
+	 * The tag of the element in the editing view, e.g. `'section'`, when the converters of the schema are on (the
+	 * `elementSchemaConverters` option). The data has `div` or `span`, whatever it is. Default: the tag of the data.
+	 */
+	editingTag?: string;
+}
+
+/**
+ * An element schema: the definitions of the elements, by name.
+ */
+export type ElementSchemaDefinition = Record<string, ElementSchemaElement>;
+
+/**
+ * What the `elementSchema` option accepts: an {@link ElementSchemaDefinition}, or a JSON file imported as it is, whose
+ * strings TypeScript does not know are the allowed ones, and whose arrays are not known to be mutable. Either way, it is
+ * validated when the editor is created.
+ */
+export type ElementSchemaInput = Record<
+	string,
+	{
+		[Key in keyof ElementSchemaElement]: Key extends 'type'
+			? string
+			: ElementSchemaElement[Key] extends string[] | undefined
+				? readonly string[] | undefined
+				: ElementSchemaElement[Key];
+	}
+>;
+
+/**
+ * A problem of an element schema.
+ */
+export interface ElementSchemaIssue {
+	/**
+	 * Where the problem is, e.g. `note.allowChildren[1]`.
+	 */
+	path: string;
+
+	/**
+	 * What is wrong, and what to do about it.
+	 */
+	message: string;
+}
+
+/**
+ * The options of {@link validateElementSchema}.
+ */
+export interface ValidateElementSchemaOptions {
+	/**
+	 * Elements that exist outside the schema, e.g. `paragraph` of the `Paragraph` plugin, by name. The schema can refer to
+	 * them, but cannot declare them. Without them, the schema can refer only to its own elements.
+	 */
+	external?: Readonly<Record<string, ElementSchemaKind>>;
+}

package/src/definition/validateElementSchema.ts

@@ -0,0 +1,238 @@
+import { ROOT, whyNot } from './canHold.js';
+import {
+	ATTRIBUTE_NAME,
+	ELEMENT_KEYS,
+	ELEMENT_NAME,
+	TAG_NAME,
+	checkKeys,
+	isRecord,
+	readKind,
+	readNames,
+	type Report
+} from './readDefinition.js';
+import { suggest } from './suggest.js';
+import type { ElementSchemaIssue, ElementSchemaKind, ValidateElementSchemaOptions } from './types.js';
+
+/**
+ * Checks an element schema, so that it is not contradictory, and returns the problems. An empty array means that the
+ * schema is valid.
+ *
+ * The schema is rejected when it:
+ *
+ * * is not of the shape {@link ElementSchemaDefinition}: an object of elements, by name; has keys that are not part of
+ *   it (typos are problems), or has values of the wrong type;
+ * * declares an element with an unknown `type`, or an `empty` element with `allowChildren`;
+ * * has attribute names that are not valid, or that differ only in case (HTML attribute names are not case sensitive),
+ *   or an `editingTag` that is not the name of a tag;
+ * * refers to elements that do not exist (a name that is neither declared in the schema, nor in `external`), or lists the
+ *   same name twice;
+ * * allows what its type cannot hold: text or an inline element in a container or in the root, a block-level (not inline)
+ *   element in a block, or anything in an `empty` element, whichever side says it: `allowChildren` of the parent, or
+ *   `allowIn` of the child.
+ *
+ * `isInline` is about the position and the layout of an element, so it is valid for every type: an inline element is
+ * laid out in a line with its siblings. Inline elements are allowed only in blocks, which can hold several of them,
+ * e.g. inline containers, or inline images between text.
+ *
+ * It does not need an editor. The editor of `ElementSchema` runs it with the elements of the other plugins as `external`.
+ */
+export function validateElementSchema(
+	input: unknown,
+	{ external = {} }: ValidateElementSchemaOptions = {}
+): ElementSchemaIssue[] {
+	const issues: ElementSchemaIssue[] = [];
+	const report = (path: string, message: string): void => {
+		issues.push({ path, message });
+	};
+
+	if (!isRecord(input)) {
+		report(
+			'',
+			'The schema must be an object of element definitions, by name: { "note": { "type": "container" } }.'
+		);
+
+		return issues;
+	}
+
+	const elements = input;
+
+	if (!Object.keys(elements).length) {
+		report('', 'The schema declares no elements: declare at least one.');
+
+		return issues;
+	}
+
+	if (isRecord(elements.elements) && !('type' in elements.elements)) {
+		report(
+			'elements',
+			'the schema is the object of the elements itself: remove the "elements" wrapper, and put the elements at the top.'
+		);
+
+		return issues;
+	}
+
+	// The first pass checks every definition on its own, and collects the kinds and the lists to cross-check.
+	const kinds = new Map<string, ElementSchemaKind>();
+	const lists = new Map<string, { allowChildren: string[]; allowIn: string[] }>();
+
+	for (const [name, definition] of Object.entries(elements)) {
+		const path = name;
+
+		if (!ELEMENT_NAME.test(name)) {
+			report(
+				path,
+				`"${name}" is not a valid element name: use camelCase letters and digits, starting with a lowercase letter.`
+			);
+		}
+
+		if (name in external) {
+			report(
+				path,
+				`"${name}" already exists in the editor (it is declared by another plugin): remove it, or rename it.`
+			);
+		}
+
+		if (!isRecord(definition)) {
+			report(path, 'must be an object, e.g. { "type": "block" }.');
+			continue;
+		}
+
+		checkKeys(definition, ELEMENT_KEYS, path, report);
+
+		const kind = readKind(definition, path, report);
+
+		if (kind) {
+			kinds.set(name, kind);
+		}
+
+		const allowChildren = readNames(definition, 'allowChildren', path, report);
+		const allowIn = readNames(definition, 'allowIn', path, report);
+		const allowAttributes = readNames(definition, 'allowAttributes', path, report);
+
+		if (allowIn && !allowIn.length) {
+			report(
+				`${path}.allowIn`,
+				'is empty, so the element would be allowed nowhere: list its parents, or remove it for the default places.'
+			);
+		}
+
+		const lowercase = new Map<string, string>();
+
+		for (const [index, attribute] of (allowAttributes ?? []).entries()) {
+			const attributePath = `${path}.allowAttributes[${String(index)}]`;
+			const collides = lowercase.get(attribute.toLowerCase());
+
+			if (!ATTRIBUTE_NAME.test(attribute)) {
+				report(attributePath, `"${attribute}" is not a valid attribute name.`);
+			} else if (collides !== undefined) {
+				report(
+					attributePath,
+					`"${attribute}" collides with "${collides}": the names of HTML attributes are not case sensitive, so the data could not tell them apart.`
+				);
+			} else {
+				lowercase.set(attribute.toLowerCase(), attribute);
+			}
+		}
+
+		if (
+			definition.editingTag !== undefined &&
+			(typeof definition.editingTag !== 'string' || !TAG_NAME.test(definition.editingTag))
+		) {
+			report(
+				`${path}.editingTag`,
+				`must be the name of an HTML tag, in lowercase, e.g. "section", not ${JSON.stringify(definition.editingTag)}.`
+			);
+		}
+
+		if (kind?.type === 'empty' && allowChildren?.length) {
+			report(
+				`${path}.allowChildren`,
+				'an empty element has no content: remove allowChildren, or change the type.'
+			);
+		}
+
+		lists.set(name, { allowChildren: kind?.type === 'empty' ? [] : (allowChildren ?? []), allowIn: allowIn ?? [] });
+	}
+
+	// The second pass checks what the lists refer to, and whether the types can hold each other.
+	const known = (name: string): ElementSchemaKind | undefined => kinds.get(name) ?? external[name];
+	const candidates = [...kinds.keys(), ...Object.keys(external)];
+
+	for (const [name, { allowChildren, allowIn }] of lists) {
+		const kind = kinds.get(name);
+
+		if (!kind) {
+			continue;
+		}
+
+		allowChildren.forEach((child, index) => {
+			const path = `${name}.allowChildren[${String(index)}]`;
+			const childKind = child === '$text' ? child : resolveReference(child, known, candidates, path, report);
+
+			if (childKind) {
+				const reason = whyNot(kind, childKind);
+
+				if (reason) {
+					report(path, `"${child}" cannot be a child of "${name}": ${reason}.`);
+				}
+			}
+		});
+
+		allowIn.forEach((parent, index) => {
+			const path = `${name}.allowIn[${String(index)}]`;
+			const parentKind = parent === '$root' ? ROOT : resolveReference(parent, known, candidates, path, report);
+
+			if (parentKind) {
+				const reason = whyNot(parentKind, kind);
+
+				if (reason) {
+					report(
+						path,
+						`"${name}" cannot be allowed in ${parent === '$root' ? 'the root' : `"${parent}"`}: ${reason}.`
+					);
+				}
+			}
+		});
+	}
+
+	// In the order of the file: the problems of an element together, whichever pass found them.
+	const names = Object.keys(elements);
+	const position = ({ path }: ElementSchemaIssue): number =>
+		names.findIndex(name => path === name || path.startsWith(`${name}.`));
+
+	return issues.sort((a, b) => position(a) - position(b));
+}
+
+/**
+ * Returns the kind of the element the list entry names. Reports an unknown name (with the closest known one), and the
+ * names that cannot be used there: `$text` and `$root` are not elements that can be both parents and children.
+ */
+function resolveReference(
+	name: string,
+	known: (name: string) => ElementSchemaKind | undefined,
+	candidates: readonly string[],
+	path: string,
+	report: Report
+): ElementSchemaKind | undefined {
+	if (name === '$text' || name === '$root') {
+		report(
+			path,
+			name === '$text'
+				? '"$text" is not an element: it is text, and cannot have children or parents.'
+				: '"$root" is the root of the editor: it can be a parent (allowIn), not a child.'
+		);
+
+		return undefined;
+	}
+
+	const kind = known(name);
+
+	if (!kind) {
+		report(
+			path,
+			`unknown element "${name}"${suggest(name, candidates)}. It must be declared in the schema, or be an element of another plugin that is loaded.`
+		);
+	}
+
+	return kind;
+}

package/src/elementSchema.ts

@@ -0,0 +1,133 @@
+import { Plugin, type ModelSchema } from 'ckeditor5';
+import { findPlugin } from 'ckeditor5-elements-core';
+import { compileElementSchema } from './definition/compileElementSchema.js';
+import { convertElementSchema } from './conversion/convertElementSchema.js';
+import ElementSchemaError from './definition/elementSchemaError.js';
+import type { ElementSchemaInput, ElementSchemaKind } from './definition/types.js';
+import { validateElementSchema } from './definition/validateElementSchema.js';
+
+/**
+ * Declares elements in the model schema of the editor from a simple definition, the `elementSchema` editor option: a
+ * plain object, e.g. a JSON file.
+ *
+ * ```json
+ * {
+ *   "note": { "type": "container", "allowAttributes": ["type"] },
+ *   "title": { "type": "block", "allowIn": ["note"] },
+ *   "badge": { "type": "empty", "isInline": true, "allowAttributes": ["color"] }
+ * }
+ * ```
+ *
+ * Every element has one of three types, instead of CKEditor's many `is*` flags and generic items:
+ *
+ * * `empty`: has no content, like an image. It is an object, selected as a whole. With `isInline`, it is in a line of text.
+ * * `block`: can contain text and inline elements, like a paragraph. With `isInline`, it is an inline element with text,
+ *   like a bold that is an element with attributes.
+ * * `container`: cannot contain text, but blocks, containers and empty elements, like a block quote.
+ *
+ * `allowAttributes` and `allowChildren` work as in CKEditor's schema. `allowIn` too, but it replaces the default places.
+ * See {@link ElementSchemaElement}.
+ *
+ * The schema is validated first, and a schema that is contradictory or refers to unknown elements is not accepted: the
+ * editor is not created, and the {@link ElementSchemaError} lists all the problems (see {@link validateElementSchema}).
+ *
+ * The elements are registered after the plugins are initialized (in `afterInit()`), so they can refer to the elements
+ * of other plugins, e.g. `paragraph`. Plugins that extend or convert the elements must do it in `afterInit()` too, or
+ * later; the converters can be declared at any time.
+ *
+ * The `empty` and `container` elements can be selected as a whole, by a click on them and by the arrow keys, when
+ * the `ElementSelectable` plugin is loaded too: the element schema does not depend on it, and uses it when it is there
+ * (with `elementSchemaConverters`, it warns when it is not).
+ *
+ * The plugin declares the schema only: how the elements look in the editor and in the data is declared with
+ * converters, or by the plugin when the `elementSchemaConverters` option is `true`: one to one, as `div` and `span`.
+ */
+export default class ElementSchema extends Plugin {
+	public static get pluginName(): 'ElementSchema' {
+		return 'ElementSchema' as const;
+	}
+
+	public afterInit(): void {
+		const input = this.editor.config.get('elementSchema');
+
+		if (input === undefined) {
+			return;
+		}
+
+		const schema = this.editor.model.schema;
+		const issues = validateElementSchema(input, { external: getExternalKinds(schema) });
+
+		if (issues.length) {
+			throw new ElementSchemaError(issues);
+		}
+
+		const { items, children } = compileElementSchema(input);
+
+		for (const [name, definition] of items) {
+			schema.register(name, definition);
+		}
+
+		for (const { parent, child } of children) {
+			schema.extend(child, { allowIn: parent });
+		}
+
+		this._makeSelectable(input);
+
+		if (this.editor.config.get('elementSchemaConverters')) {
+			convertElementSchema(this.editor, input);
+		}
+	}
+
+	/**
+	 * Makes the `empty` elements and the containers selectable as a whole, by a click on them and by the arrow keys, with
+	 * `ElementSelectable`. Not the blocks: a click in a block puts the cursor in its text.
+	 */
+	private _makeSelectable(input: ElementSchemaInput): void {
+		const names = Object.entries(input)
+			.filter(([, element]) => element.type === 'empty' || element.type === 'container')
+			.map(([name]) => name);
+		const selectable = findPlugin(this.editor, 'ElementSelectable', isSelectablePlugin);
+
+		if (selectable) {
+			selectable.add(...names);
+		} else if (names.length && this.editor.config.get('elementSchemaConverters')) {
+			// The converters make the elements, and nothing selects them: say it, as it is a silent loss. Not CKEditor's
+			// `logWarning()`: it links to CKEditor's list of errors, which does not have this one.
+			// eslint-disable-next-line no-console -- A warning for the developer, once, when the editor is created.
+			console.warn(
+				`ElementSchema: load ElementSelectable to select the elements of the schema as a whole: ${names.join(', ')}.`
+			);
+		}
+	}
+}
+
+/**
+ * The part of the `ElementSelectable` plugin the element schema uses. The schema does not depend on the other features:
+ * the plugin is looked up by name and checked against this interface.
+ */
+interface SelectablePlugin {
+	add(...names: string[]): void;
+}
+
+function isSelectablePlugin(plugin: object): plugin is SelectablePlugin {
+	return 'add' in plugin && typeof plugin.add === 'function';
+}
+
+/**
+ * Returns the kinds of the elements of other plugins: inline or not, and `empty` for objects, `block` for what can
+ * contain text, `container` for the rest. The generic items (`$block`, …) are not elements.
+ */
+function getExternalKinds(schema: ModelSchema): Record<string, ElementSchemaKind> {
+	const kinds: Record<string, ElementSchemaKind> = {};
+
+	for (const name of Object.keys(schema.getDefinitions())) {
+		if (!name.startsWith('$')) {
+			kinds[name] = {
+				isInline: schema.isInline(name),
+				type: schema.isObject(name) ? 'empty' : schema.checkChild(name, '$text') ? 'block' : 'container'
+			};
+		}
+	}
+
+	return kinds;
+}

package/src/elementSchemaCommands.ts

@@ -0,0 +1,202 @@
+import { Plugin, type ModelSchema, type ViewDowncastWriter, type ViewElement } from 'ckeditor5';
+import { ElementOrPositionButtonView } from 'ckeditor5-elements-core';
+import { createInlineTextElement } from './conversion/inlineTextElement.js';
+import ElementBlockCommand from './commands/elementBlockCommand.js';
+import ElementContainerCommand from './commands/elementContainerCommand.js';
+import ElementInlineCommand from './commands/elementInlineCommand.js';
+import ElementInsertCommand from './commands/elementInsertCommand.js';
+import ElementSchema from './elementSchema.js';
+import type ElementSchemaCommand from './commands/elementSchemaCommand.js';
+import { enableTwoStepCaretMovement } from './typing/twoStepCaretMovement.js';
+
+/**
+ * An element of {@link ElementSchemaCommands}: its command and its button.
+ */
+export interface ElementSchemaCommandDefinition {
+	/**
+	 * The model element: of the element schema, or of another plugin. Default: the name of the command.
+	 */
+	element?: string;
+
+	/**
+	 * The title of the command, and the label of its button, e.g. `'Bold'`.
+	 */
+	title: string;
+
+	/**
+	 * The icon of the command and of its button (an SVG string), e.g. `IconBold` of CKEditor.
+	 */
+	icon?: string;
+
+	/**
+	 * The keystroke that executes the command, e.g. `'Ctrl+B'`.
+	 */
+	keystroke?: string;
+
+	/**
+	 * The tag of the element in the data and in the editing view, e.g. `'strong'` or `'hr'`. The converters of the plugin
+	 * replace the ones of the element schema (`elementSchemaConverters`) in the downcast, and the upcast takes both.
+	 * Without it, the element is converted by the schema, or by your converters.
+	 */
+	view?: string;
+}
+
+/**
+ * The `elementSchemaCommands` option: the elements, by the name of their command and of their button.
+ */
+export type ElementSchemaCommandsConfig = Record<string, ElementSchemaCommandDefinition>;
+
+/**
+ * Commands and toolbar buttons for the elements of the element schema, as CKEditor's features have for theirs: the
+ * command of an element is the one of its kind (see {@link ElementSchemaCommand}).
+ *
+ * | Element                       | Command                     | Works as CKEditor's           |
+ * | ----------------------------- | --------------------------- | ----------------------------- |
+ * | inline `block`                | {@link ElementInlineCommand}    | bold: wraps text              |
+ * | `block`                       | {@link ElementBlockCommand}     | heading: renames blocks       |
+ * | `container`                   | {@link ElementContainerCommand} | block quote: wraps blocks     |
+ * | `empty`, inline `container`   | {@link ElementInsertCommand}    | horizontal line: inserts      |
+ *
+ * ```ts
+ * elementSchema: schema,
+ * elementSchemaCommands: {
+ *   bold: { title: 'Bold', icon: IconBold, keystroke: 'Ctrl+B', view: 'strong' },
+ *   callout: { title: 'Callout', icon: IconQuote },
+ *   divider: { title: 'Divider', icon: IconHorizontalLine, view: 'hr' }
+ * },
+ * toolbar: ['bold', 'callout', 'divider']
+ * ```
+ *
+ * Each key is the name of the command and of its toolbar button. The commands have titles and icons, so they can be
+ * menu items too, e.g. of the context menu.
+ *
+ * At the ends of the inline elements with text, the left and right arrow keys move in two steps, as CKEditor's two-step
+ * caret movement does at the ends of a bold: in the element, then in the text.
+ *
+ * The commands are made when the elements are registered, after `ElementSchema` and the other plugins are initialized.
+ * The editor is not created when an element is unknown.
+ */
+export default class ElementSchemaCommands extends Plugin {
+	public static get pluginName(): 'ElementSchemaCommands' {
+		return 'ElementSchemaCommands' as const;
+	}
+
+	public static get requires(): readonly [typeof ElementSchema] {
+		return [ElementSchema] as const;
+	}
+
+	/**
+	 * The commands, by their name.
+	 */
+	private readonly _commands = new Map<string, ElementSchemaCommand>();
+
+	public init(): void {
+		const editor = this.editor;
+
+		for (const [name, { title, keystroke }] of this._getDefinitions()) {
+			if (keystroke) {
+				editor.keystrokes.set(keystroke, name);
+				editor.accessibility.addKeystrokeInfos({ keystrokes: [{ label: title, keystroke }] });
+			}
+
+			editor.ui.componentFactory.add(name, locale => {
+				const command = this._commands.get(name);
+
+				// The commands are made in `afterInit()`, and the toolbars after it.
+				if (!command) {
+					throw new Error(`elementSchemaCommands.${name}: the button is created before the command.`);
+				}
+
+				const button = new ElementOrPositionButtonView(locale, command);
+
+				button.bind('isOn').to(command, 'isOn');
+				button.keystroke = keystroke;
+
+				return button;
+			});
+		}
+	}
+
+	/**
+	 * Makes the commands of the elements, which are registered then, and their converters.
+	 */
+	public afterInit(): void {
+		const editor = this.editor;
+		const schema = editor.model.schema;
+		const inlineNames = new Set<string>();
+
+		for (const [name, { element, title, icon, view }] of this._getDefinitions()) {
+			const elementName = element ?? name;
+
+			if (!schema.isRegistered(elementName)) {
+				throw new Error(
+					`elementSchemaCommands.${name}: unknown element "${elementName}". Declare it in the element schema, or ` +
+						`set "element" to an element of another plugin.`
+				);
+			}
+
+			const CommandClass = getCommandClass(schema, elementName);
+			const command = new CommandClass(editor, elementName);
+
+			command.set({ title, icon });
+			editor.commands.add(name, command);
+			this._commands.set(name, command);
+
+			if (command instanceof ElementInlineCommand) {
+				inlineNames.add(elementName);
+			}
+
+			if (view) {
+				this._convert(elementName, view, (writer: ViewDowncastWriter) => {
+					if (command instanceof ElementInlineCommand) {
+						return createInlineTextElement(writer, view);
+					}
+
+					return schema.isObject(elementName)
+						? writer.createEmptyElement(view)
+						: writer.createContainerElement(view);
+				});
+			}
+		}
+
+		enableTwoStepCaretMovement(this, inlineNames);
+	}
+
+	private _getDefinitions(): [name: string, definition: ElementSchemaCommandDefinition][] {
+		return Object.entries(this.editor.config.get('elementSchemaCommands') ?? {});
+	}
+
+	/**
+	 * Declares the converters of an element with the tag of its `view`: the downcast with the highest priority, so it
+	 * replaces the ones of the element schema, and the upcast.
+	 */
+	private _convert(elementName: string, tag: string, createView: (writer: ViewDowncastWriter) => ViewElement): void {
+		const conversion = this.editor.conversion;
+
+		conversion.for('upcast').elementToElement({ view: tag, model: elementName });
+		conversion.for('downcast').elementToElement({
+			model: elementName,
+			view: (_element, { writer }) => createView(writer),
+			// Over the ones of the schema, some of which are `high` already.
+			converterPriority: 'highest'
+		});
+	}
+}
+
+/**
+ * Returns the command of an element, by its kind: an object, or an inline element with no text, is inserted; an inline
+ * element with text wraps text; a block-level one with text is a block; the others are containers.
+ */
+function getCommandClass(schema: ModelSchema, name: string): typeof ElementSchemaCommand {
+	const holdsText = schema.checkChild(name, '$text');
+
+	if (schema.isObject(name) || (schema.isInline(name) && !holdsText)) {
+		return ElementInsertCommand;
+	}
+
+	if (schema.isInline(name)) {
+		return ElementInlineCommand;
+	}
+
+	return holdsText ? ElementBlockCommand : ElementContainerCommand;
+}