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

package/src/commands/elementInsertCommand.ts

@@ -0,0 +1,74 @@
+import type { ModelDocumentSelection, ModelSelection } from 'ckeditor5';
+import { selectNewElement, type ElementOrPosition } from 'ckeditor5-elements-core';
+import ElementSchemaCommand from './elementSchemaCommand.js';
+
+/**
+ * Inserts the element, as CKEditor's horizontal line and image commands do: an element that is not typed around text,
+ * e.g. an `empty` element of the element schema (a `divider`, or an inline `badge`), or an inline `container` (a `card`).
+ *
+ * ```ts
+ * editor.execute('divider'); // In place of the selection.
+ * editor.commands.get('divider').executeFor(element); // After the element.
+ * ```
+ *
+ * For the selection, it replaces the selected content, as typing does; at a position, it is inserted there; for an
+ * element, after it. Where the element cannot be, the blocks are split up to where it can, e.g. a block-level one in the
+ * middle of a paragraph. Then it is selected, as `selectNewElement()` does: an `empty` element as a whole, and an inline
+ * container gets a paragraph, with the cursor in it.
+ *
+ * It does not toggle: it is never "on".
+ */
+export default class ElementInsertCommand extends ElementSchemaCommand {
+	/**
+	 * Inserts a new element at the target, and selects it.
+	 */
+	public override execute(elementOrPosition?: ElementOrPosition): void {
+		const model = this.editor.model;
+		const selectable = this._getSelectable(elementOrPosition);
+
+		if (!selectable) {
+			return;
+		}
+
+		model.change(writer => {
+			const element = writer.createElement(this.elementName);
+
+			model.insertContent(element, selectable);
+
+			if (element.parent) {
+				selectNewElement(writer, element);
+			}
+		});
+	}
+
+	/**
+	 * Enabled when the target can be edited, and the element can be there, or in one of its ancestors.
+	 */
+	protected override _isEnabledFor(elementOrPosition?: ElementOrPosition): boolean {
+		const position = this._getSelectable(elementOrPosition)?.getFirstPosition();
+
+		return (
+			!!position &&
+			super._isEnabledFor(elementOrPosition) &&
+			!!this.editor.model.schema.findAllowedParent(position, this.elementName)
+		);
+	}
+
+	/**
+	 * Returns where the element goes: the selection, or the given position, or the position after the given element.
+	 */
+	private _getSelectable(elementOrPosition?: ElementOrPosition): ModelSelection | ModelDocumentSelection | null {
+		const model = this.editor.model;
+		const target = this._getElementOrPosition(elementOrPosition);
+
+		if (!target) {
+			return null;
+		}
+
+		if (!elementOrPosition) {
+			return model.document.selection;
+		}
+
+		return model.createSelection(target.is('position') ? target : model.createPositionAfter(target));
+	}
+}

package/src/commands/elementSchemaCommand.ts

@@ -0,0 +1,140 @@
+import type { Editor, ModelElement, ModelDocumentFragment, ModelItem, ModelPosition, ModelRange } from 'ckeditor5';
+import { ElementOrPositionCommand, type ElementOrPosition } from 'ckeditor5-elements-core';
+
+/**
+ * The base of the commands of the elements of a schema, one for each kind of element: what they share is the element,
+ * the state, and how they find their targets and check the schema.
+ *
+ * * {@link ElementInlineCommand}: an inline element with text, as bold (an inline `block`);
+ * * {@link ElementBlockCommand}: a block, as a heading (a `block`);
+ * * {@link ElementContainerCommand}: a container of blocks, as a block quote (a `container`);
+ * * {@link ElementInsertCommand}: an element that is inserted, as a horizontal line, an inline image, or a card (an
+ *   `empty` element, and an inline `container`).
+ *
+ * As every {@link ElementOrPositionCommand}, it is for the selection, or for a given position or element, e.g. of a
+ * context menu.
+ */
+export default class ElementSchemaCommand extends ElementOrPositionCommand {
+	/**
+	 * Whether the target is in the element, or is one, for the commands that toggle it.
+	 *
+	 * @observable
+	 */
+	declare public isOn: boolean;
+
+	/**
+	 * The name of the model element of the command.
+	 */
+	public readonly elementName: string;
+
+	constructor(editor: Editor, elementName: string) {
+		super(editor);
+
+		this.elementName = elementName;
+		this.set('isOn', false);
+	}
+
+	public override refresh(elementOrPosition?: ElementOrPosition): void {
+		this.isOn = this._isOnFor(elementOrPosition);
+		super.refresh(elementOrPosition);
+	}
+
+	/**
+	 * Whether a node is an element of the command.
+	 */
+	public isElement(node: ModelItem | ModelDocumentFragment | null): node is ModelElement {
+		return !!node?.is('element', this.elementName);
+	}
+
+	/**
+	 * Returns the closest element of the command that the target is, or is in: by default, the selection. Never a root.
+	 */
+	protected _findElement(elementOrPosition?: ElementOrPosition): ModelElement | null {
+		return this._getAncestors(elementOrPosition).find(element => this.isElement(element)) ?? null;
+	}
+
+	/**
+	 * Returns the elements the target is, or is in (by default, the selection), the inner first: an element and its
+	 * ancestors, or the parent of a position and its ancestors. Not the root.
+	 */
+	protected _getAncestors(elementOrPosition?: ElementOrPosition): ModelElement[] {
+		const target = this._getElementOrPosition(elementOrPosition);
+		const element = target && (target.is('position') ? target.parent : target);
+
+		return element?.is('element')
+			? element
+					.getAncestors({ includeSelf: true, parentFirst: true })
+					.filter((node): node is ModelElement => node.is('element') && !node.is('rootElement'))
+			: [];
+	}
+
+	/**
+	 * Returns the ranges of the selected content, when the command is for the selection, and the selection is content,
+	 * not a cursor nor an element.
+	 */
+	protected _getSelectedRanges(elementOrPosition?: ElementOrPosition): ModelRange[] | null {
+		const selection = this.editor.model.document.selection;
+
+		return !elementOrPosition && !selection.isCollapsed && !selection.getSelectedElement()
+			? Array.from(selection.getRanges())
+			: null;
+	}
+
+	/**
+	 * Returns the blocks of the target, by default of the selection: the selected blocks, or the block-level element the
+	 * target is, or is in (e.g. the paragraph with the cursor, a selected horizontal line, or a block quote).
+	 */
+	protected _getBlocks(elementOrPosition?: ElementOrPosition): ModelElement[] {
+		const selection = this.editor.model.document.selection;
+		const blocks =
+			elementOrPosition || selection.getSelectedElement() ? [] : Array.from(selection.getSelectedBlocks());
+
+		if (blocks.length) {
+			return blocks;
+		}
+
+		const block = this._getAncestors(elementOrPosition).find(
+			element => !this.editor.model.schema.isInline(element)
+		);
+
+		return block ? [block] : [];
+	}
+
+	/**
+	 * Whether an element (by default, the one of the command) can be at a position, and hold the items there: the check
+	 * for wrapping them, or for renaming their parent.
+	 */
+	protected _canHold(position: ModelPosition, items: Iterable<ModelItem>, name = this.elementName): boolean {
+		const schema = this.editor.model.schema;
+
+		if (!schema.checkChild(position, name)) {
+			return false;
+		}
+
+		const parent = position.parent as ModelElement;
+		const context = [...parent.getAncestors({ includeSelf: true }).filter(node => node.is('element')), name];
+
+		for (const item of items) {
+			if (!schema.checkChild(context, item.is('$textProxy') ? '$text' : item)) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
+	/**
+	 * Whether the children of an element can be in its place: the check for unwrapping it.
+	 */
+	protected _canUnwrap(element: ModelElement): boolean {
+		const model = this.editor.model;
+
+		if (!element.parent) {
+			return false;
+		}
+
+		const position = model.createPositionBefore(element);
+
+		return Array.from(element.getChildren()).every(child => model.schema.checkChild(position, child));
+	}
+}

package/src/conversion/convertElementSchema.ts

@@ -0,0 +1,65 @@
+import type { Editor } from 'ckeditor5';
+import type { ElementSchemaElement, ElementSchemaInput } from '../definition/types.js';
+import { createInlineTextElement } from './inlineTextElement.js';
+
+/**
+ * Returns the tag of an element in the data: a `span` for what is in a line of text (an inline element that is empty or
+ * has text), a `div` for the rest. An inline container is a `div`: it holds blocks, which a `span` cannot hold.
+ */
+export function getViewTag({ type, isInline }: Pick<ElementSchemaElement, 'type' | 'isInline'>): 'div' | 'span' {
+	return isInline && type !== 'container' ? 'span' : 'div';
+}
+
+/**
+ * Declares the converters of the elements of a schema, one to one: an element is a `div` or a `span` in the data (see
+ * {@link getViewTag}), with its name as the class. Its attributes are `data-*` attributes. The data is loaded as it is
+ * saved. The editing view is the same, except for the tag, when the element has an `editingTag`.
+ *
+ * The `empty` elements are empty in the data too: `<div class="divider"></div>`, with no filler. The inline elements with
+ * text have no block filler, so the cursor can go in an empty one (see `withoutBlockFiller()`).
+ */
+export function convertElementSchema(editor: Editor, input: ElementSchemaInput): void {
+	const { conversion } = editor;
+
+	for (const [name, element] of Object.entries(input)) {
+		const { type, isInline, editingTag, allowAttributes } = element as ElementSchemaElement;
+		const tag = getViewTag(element as ElementSchemaElement);
+		const view = { name: tag, classes: name };
+		const isInlineText = type === 'block' && !!isInline;
+
+		for (const key of allowAttributes ?? []) {
+			// The names of HTML attributes are lowercase, so the data has them in lowercase; the model keeps the key as it is.
+			conversion.attributeToAttribute({ model: { name, key }, view: `data-${key.toLowerCase()}` });
+		}
+
+		// Upcast, data downcast and editing downcast at once; what differs is declared with a higher priority.
+		conversion.elementToElement({ model: name, view });
+
+		if (type === 'empty') {
+			conversion.for('dataDowncast').elementToElement({
+				model: name,
+				view: (_element, { writer }) => writer.createEmptyElement(tag, { class: name }),
+				converterPriority: 'high'
+			});
+		}
+
+		if (isInlineText) {
+			conversion.for('dataDowncast').elementToElement({
+				model: name,
+				view: (_element, { writer }) => createInlineTextElement(writer, tag, name),
+				converterPriority: 'high'
+			});
+		}
+
+		if (editingTag || isInlineText) {
+			conversion.for('editingDowncast').elementToElement({
+				model: name,
+				view: (_element, { writer }) =>
+					isInlineText
+						? createInlineTextElement(writer, editingTag ?? tag, name)
+						: writer.createContainerElement(editingTag ?? tag, { class: name }),
+				converterPriority: 'high'
+			});
+		}
+	}
+}

package/src/conversion/inlineTextElement.ts

@@ -0,0 +1,31 @@
+import type { ViewContainerElement, ViewDowncastWriter } from 'ckeditor5';
+
+/**
+ * Makes a view element have no block filler, and returns it: for the view of an inline element with text, e.g. a bold
+ * that is an element, so that the cursor can go in it when it is empty.
+ *
+ * CKEditor puts a block filler, a `<br>`, in an empty container element, so that an empty paragraph has a height. In an
+ * inline element, the browser does not type there: the text goes before the element. Without the block filler, CKEditor
+ * puts its inline filler where the cursor is, as in the empty `<strong>` of its own bold, and the text goes in.
+ *
+ * ```ts
+ * conversion.for('downcast').elementToElement({
+ *   model: 'bold',
+ *   view: (element, { writer }) => withoutBlockFiller(writer.createContainerElement('strong'))
+ * });
+ * ```
+ *
+ * The converters of the element schema (`elementSchemaConverters`) and the `view` of `ElementSchemaCommands` do it already.
+ */
+export function withoutBlockFiller<T extends ViewContainerElement>(element: T): T {
+	element.getFillerOffset = () => null;
+
+	return element;
+}
+
+/**
+ * Creates the view of an inline element with text: an element with no block filler (see {@link withoutBlockFiller}).
+ */
+export function createInlineTextElement(writer: ViewDowncastWriter, tag: string, name?: string): ViewContainerElement {
+	return withoutBlockFiller(writer.createContainerElement(tag, name ? { class: name } : {}));
+}

package/src/definition/canHold.ts

@@ -0,0 +1,29 @@
+import type { ElementSchemaKind } from './types.js';
+
+/**
+ * The root can hold blocks, containers and block-level empty elements, like a container.
+ */
+export const ROOT: ElementSchemaKind = { type: 'container', isInline: false };
+
+/**
+ * Returns why `parent` cannot contain `child` (an element, or `'$text'`), or `null` when it can.
+ */
+export function whyNot(parent: ElementSchemaKind, child: ElementSchemaKind | '$text'): string | null {
+	const isText = child === '$text';
+
+	if (parent.type === 'empty') {
+		return 'an empty element cannot contain anything';
+	}
+
+	if (parent.type === 'block') {
+		const what = parent.isInline ? 'an inline text element' : 'a block';
+
+		return isText || child.isInline ? null : `${what} can contain only text and inline elements`;
+	}
+
+	if (isText) {
+		return 'a container cannot contain text: put the text in a block';
+	}
+
+	return child.isInline ? 'a container cannot contain inline elements: put them in a block' : null;
+}

package/src/definition/compileElementSchema.ts

@@ -0,0 +1,88 @@
+import type { ModelSchemaItemDefinition } from 'ckeditor5';
+import type { ElementSchemaElement, ElementSchemaInput } from './types.js';
+
+/**
+ * The result of {@link compileElementSchema}.
+ */
+export interface CompiledElementSchema {
+	/**
+	 * The items to register in CKEditor's schema, by name.
+	 */
+	items: [name: string, definition: ModelSchemaItemDefinition][];
+
+	/**
+	 * The `allowChildren` of the elements, as the places to add to the children: `schema.extend(child, { allowIn: parent })`.
+	 * The child can be an element of another plugin, which is extended, not registered.
+	 */
+	children: { parent: string; child: string }[];
+}
+
+/**
+ * Translates a valid element schema to the definitions of CKEditor's schema. Each type is made like a generic item of
+ * CKEditor:
+ *
+ * * `container`: like `$container`: allowed in the root and in containers; holds what is allowed in a container: blocks,
+ *   containers and block objects, not text.
+ * * `block`: like `$block`: a block, allowed in the root and in containers; holds text and inline objects.
+ * * `empty` and not inline: like `$blockObject`: an object, allowed where blocks are.
+ * * `empty` and inline: like `$inlineObject`: an object, allowed where text is, with the attributes of text.
+ * * `block` and inline: an inline element that holds text and inline elements, allowed where text is, with the attributes
+ *   of text: like `$text`, but an element, so it can have attributes of its own.
+ * * `container` and inline: a container laid out in a line, e.g. with others in a block: allowed where text is, like every
+ *   inline element, and holds the same as a container: blocks, not text.
+ *
+ * `isInline` is about the layout and the position of an element, so it is set for every type, and CKEditor's features and
+ * the converters can use it.
+ *
+ * `allowAttributes` is passed as it is. `allowIn` replaces the default places of the type. `allowChildren` adds to what
+ * the type holds, as in CKEditor.
+ */
+export function compileElementSchema(input: ElementSchemaInput): CompiledElementSchema {
+	const items: CompiledElementSchema['items'] = [];
+	const children: CompiledElementSchema['children'] = [];
+
+	for (const [name, element] of Object.entries(input)) {
+		items.push([name, compileElement(element as ElementSchemaElement)]);
+
+		for (const child of element.allowChildren ?? []) {
+			children.push({ parent: name, child });
+		}
+	}
+
+	return { items, children };
+}
+
+function compileElement({ type, isInline, allowIn, allowAttributes }: ElementSchemaElement): ModelSchemaItemDefinition {
+	// Where the element is allowed: the places of its type, or the given ones.
+	const places = (defaultPlaces: string): Pick<ModelSchemaItemDefinition, 'allowIn' | 'allowWhere'> =>
+		allowIn ? { allowIn } : { allowWhere: defaultPlaces };
+	const attributes = allowAttributes ? { allowAttributes } : {};
+
+	if (type === 'empty' && isInline) {
+		return { inheritTypesFrom: '$inlineObject', allowAttributesOf: '$text', ...places('$text'), ...attributes };
+	}
+
+	if (type === 'empty') {
+		return { inheritTypesFrom: '$blockObject', ...places('$block'), ...attributes };
+	}
+
+	if (type === 'block' && isInline) {
+		return {
+			isInline: true,
+			allowContentOf: '$block',
+			allowAttributesOf: '$text',
+			...places('$text'),
+			...attributes
+		};
+	}
+
+	if (type === 'block') {
+		return { inheritTypesFrom: '$block', allowContentOf: '$block', ...places('$block'), ...attributes };
+	}
+
+	return {
+		allowContentOf: '$container',
+		...(isInline ? { isInline: true, ...places('$text') } : places('$block')),
+		...attributes
+	};
+}

package/src/definition/elementSchemaError.ts

@@ -0,0 +1,21 @@
+import type { ElementSchemaIssue } from './types.js';
+
+/**
+ * Thrown when the element schema is not valid. It lists all the problems, and has them in {@link issues}.
+ */
+export default class ElementSchemaError extends Error {
+	/**
+	 * The problems of the schema.
+	 */
+	public readonly issues: readonly ElementSchemaIssue[];
+
+	constructor(issues: readonly ElementSchemaIssue[]) {
+		super(
+			`The element schema is not valid (${String(issues.length)} ${issues.length === 1 ? 'problem' : 'problems'}):\n` +
+				issues.map(({ path, message }) => `- ${path ? `${path}: ` : ''}${message}`).join('\n')
+		);
+
+		this.name = 'ElementSchemaError';
+		this.issues = issues;
+	}
+}

package/src/definition/readDefinition.ts

@@ -0,0 +1,98 @@
+import type { ElementSchemaKind } from './types.js';
+import { suggest } from './suggest.js';
+
+/**
+ * Reports a problem of the schema, at the path.
+ */
+export type Report = (path: string, message: string) => void;
+
+const TYPES = ['empty', 'block', 'container'];
+export const ELEMENT_KEYS = ['type', 'isInline', 'allowChildren', 'allowIn', 'allowAttributes', 'editingTag'];
+
+export const ELEMENT_NAME = /^[a-z][A-Za-z0-9]*$/;
+export const ATTRIBUTE_NAME = /^[A-Za-z][\w.:-]*$/;
+export const TAG_NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+export function readKind(definition: Record<string, unknown>, path: string, report: Report): ElementSchemaKind | null {
+	const { type, isInline } = definition;
+
+	if (isInline !== undefined && typeof isInline !== 'boolean') {
+		report(`${path}.isInline`, 'must be true or false.');
+	}
+
+	if (type === undefined) {
+		report(`${path}.type`, 'is required: "empty", "block" or "container".');
+
+		return null;
+	}
+
+	if (typeof type !== 'string' || !TYPES.includes(type)) {
+		report(
+			`${path}.type`,
+			`must be "empty", "block" or "container", not ${JSON.stringify(type)}${typeof type === 'string' ? suggest(type, TYPES) : ''}.`
+		);
+
+		return null;
+	}
+
+	return { type: type as ElementSchemaKind['type'], isInline: isInline === true };
+}
+
+/**
+ * Reads a list of names, and reports what is not a list of unique, non-empty strings. Returns the list, or
+ * `undefined` when it is missing.
+ */
+export function readNames(
+	definition: Record<string, unknown>,
+	key: string,
+	path: string,
+	report: Report
+): string[] | undefined {
+	const value = definition[key];
+
+	if (value === undefined) {
+		return undefined;
+	}
+
+	if (!Array.isArray(value)) {
+		report(`${path}.${key}`, `must be an array of names, e.g. ["a", "b"].`);
+
+		return undefined;
+	}
+
+	const names: string[] = [];
+
+	value.forEach((item: unknown, index) => {
+		const itemPath = `${path}.${key}[${String(index)}]`;
+
+		if (typeof item !== 'string' || !item) {
+			report(itemPath, 'must be a non-empty string.');
+		} else if (names.includes(item)) {
+			report(itemPath, `"${item}" is listed twice.`);
+		} else {
+			names.push(item);
+		}
+	});
+
+	return names;
+}
+
+export function checkKeys(
+	object: Record<string, unknown>,
+	allowed: readonly string[],
+	path: string,
+	report: Report
+): void {
+	for (const key of Object.keys(object)) {
+		if (!allowed.includes(key)) {
+			report(
+				path ? `${path}.${key}` : key,
+				`is not a known key${suggest(key, allowed)}. The keys are: ${allowed.map(name => `"${name}"`).join(', ')}.`
+			);
+		}
+	}
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/definition/suggest.ts

@@ -0,0 +1,38 @@
+/**
+ * Returns ` Did you mean "x"?` for the closest candidate, when it is close enough to be a typo.
+ */
+export function suggest(name: string, candidates: readonly string[]): string {
+	let best: string | undefined;
+	let bestDistance = 3;
+
+	for (const candidate of candidates) {
+		const distance = editDistance(name.toLowerCase(), candidate.toLowerCase());
+
+		if (distance < bestDistance) {
+			best = candidate;
+			bestDistance = distance;
+		}
+	}
+
+	return best ? ` (did you mean "${best}"?)` : '';
+}
+
+function editDistance(a: string, b: string): number {
+	let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+
+	for (let i = 1; i <= a.length; i++) {
+		const current = [i];
+
+		for (let j = 1; j <= b.length; j++) {
+			current[j] = Math.min(
+				(previous[j] ?? 0) + 1,
+				(current[j - 1] ?? 0) + 1,
+				(previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1)
+			);
+		}
+
+		previous = current;
+	}
+
+	return previous[b.length] ?? 0;
+}