ckeditor5-elements-schema 49.0.0-alpha.2 → 49.0.0-alpha.4

package/src/commands/elementInlineCommand.ts

@@ -0,0 +1,311 @@
+import {
+	ModelLivePosition,
+	ModelLiveRange,
+	type ModelDocumentFragment,
+	type ModelElement,
+	type ModelNode,
+	type ModelRange,
+	type ModelWriter
+} from 'ckeditor5';
+import type { ElementOrPosition } from 'ckeditor5-elements-core';
+import ElementSchemaCommand from './elementSchemaCommand.js';
+
+/**
+ * Toggles an inline element with text, as CKEditor's `bold` toggles an attribute of text, but with an element, e.g. a
+ * `bold` that is an inline `block` of the element schema.
+ *
+ * ```ts
+ * editor.execute('bold'); // The selection.
+ * editor.commands.get('bold').executeFor(element); // An element, e.g. of a context menu.
+ * ```
+ *
+ * * On selected text, it wraps the text with the element, in each block, and merges it with the elements next to it.
+ *   When all the text is in the element already, it unwraps the elements: the whole ones, not only the selected part.
+ * * On the cursor, it inserts an empty element with the cursor in it. In the element, it moves the cursor out of it, at
+ *   its start or end, or it unwraps it.
+ * * On an element (selected, or given), it unwraps the element it is in, or wraps it.
+ *
+ * It is "on" ({@link isOn}) when the target is in the element: for selected text, when all of it is.
+ */
+export default class ElementInlineCommand extends ElementSchemaCommand {
+	public override isToggleable = true;
+
+	/**
+	 * Puts the target in the element, or out of it: by default, the selection, also selected text.
+	 */
+	public override execute(elementOrPosition?: ElementOrPosition): void {
+		const ranges = this._getSelectedRanges(elementOrPosition);
+		const target = this._getElementOrPosition(elementOrPosition);
+
+		this.editor.model.change(writer => {
+			if (ranges) {
+				if (this._isOnRanges(ranges)) {
+					this._unwrapRanges(writer, ranges);
+				} else {
+					this._wrapRanges(writer, ranges);
+				}
+			} else if (target) {
+				const element = this._findElement(target);
+
+				if (element) {
+					this._leave(writer, element, target);
+				} else {
+					this._insert(writer, target);
+				}
+			}
+		});
+	}
+
+	/**
+	 * Enabled when the target can be edited, and is in the element, or the element can be there.
+	 */
+	protected override _isEnabledFor(elementOrPosition?: ElementOrPosition): boolean {
+		const ranges = this._getSelectedRanges(elementOrPosition);
+		const target = this._getElementOrPosition(elementOrPosition);
+
+		if (!target || !super._isEnabledFor(target)) {
+			return false;
+		}
+
+		if (ranges) {
+			return this._isOnRanges(ranges) || this._getWrapRanges(ranges).length > 0;
+		}
+
+		if (this._findElement(target)) {
+			return true;
+		}
+
+		return target.is('position')
+			? this.editor.model.schema.checkChild(target, this.elementName)
+			: this._canHold(this.editor.model.createPositionBefore(target), [target]);
+	}
+
+	/**
+	 * "On" when the target is in the element: for selected text, when all of it is.
+	 */
+	protected override _isOnFor(elementOrPosition?: ElementOrPosition): boolean {
+		const ranges = this._getSelectedRanges(elementOrPosition);
+		const target = this._getElementOrPosition(elementOrPosition);
+
+		return ranges ? this._isOnRanges(ranges) : !!target && !!this._findElement(target);
+	}
+
+	/**
+	 * Whether all the text of the ranges is in the element: there are elements, and nothing to wrap.
+	 */
+	private _isOnRanges(ranges: ModelRange[]): boolean {
+		return this._getElementsIn(ranges).length > 0 && !this._getWrapRanges(ranges).length;
+	}
+
+	/**
+	 * Returns the elements of the command that a node is, or is in, in its line of text: the node and its ancestors, up to
+	 * the first that is not inline, e.g. the paragraph. The inner first.
+	 */
+	private _getElementsAround(node: ModelElement | ModelDocumentFragment | null): ModelElement[] {
+		const schema = this.editor.model.schema;
+		const elements: ModelElement[] = [];
+
+		for (let element = node; element?.is('element') && schema.isInline(element); element = element.parent) {
+			if (this.isElement(element)) {
+				elements.push(element);
+			}
+		}
+
+		return elements;
+	}
+
+	/**
+	 * Returns the closest element of the command that the target is, or is in, in its line of text.
+	 */
+	protected override _findElement(elementOrPosition?: ElementOrPosition): ModelElement | null {
+		const target = this._getElementOrPosition(elementOrPosition);
+
+		return target ? (this._getElementsAround(target.is('position') ? target.parent : target)[0] ?? null) : null;
+	}
+
+	/**
+	 * Returns the elements of the command in ranges, and around their ends.
+	 */
+	private _getElementsIn(ranges: ModelRange[]): ModelElement[] {
+		const elements = new Set<ModelElement>();
+
+		for (const range of ranges) {
+			for (const element of [
+				...this._getElementsAround(range.start.parent),
+				...this._getElementsAround(range.end.parent)
+			]) {
+				elements.add(element);
+			}
+
+			for (const item of range.getItems()) {
+				if (this.isElement(item)) {
+					elements.add(item);
+				}
+			}
+		}
+
+		return Array.from(elements);
+	}
+
+	/**
+	 * Returns the ranges to wrap with the element to put the text of ranges in it: in each parent the element is allowed
+	 * in, the runs of nodes it can hold, which are not in the element already. The other elements are looked into, e.g.
+	 * the paragraphs of a selection across blocks.
+	 */
+	private _getWrapRanges(ranges: ModelRange[]): ModelRange[] {
+		const model = this.editor.model;
+		const wrapRanges: ModelRange[] = [];
+
+		const collect = (flatRange: ModelRange): void => {
+			const parent = flatRange.start.parent as ModelElement;
+
+			if (this._getElementsAround(parent).length) {
+				return;
+			}
+
+			let run: ModelRange | null = null;
+			const close = (): void => {
+				if (run) {
+					wrapRanges.push(run);
+					run = null;
+				}
+			};
+
+			for (const item of flatRange.getItems({ shallow: true })) {
+				if (this.isElement(item)) {
+					close();
+				} else if (this._canHold(flatRange.start, [item])) {
+					run = model.createRange(
+						run?.start ?? model.createPositionBefore(item),
+						model.createPositionAfter(item)
+					);
+				} else {
+					close();
+
+					if (item.is('element')) {
+						collect(model.createRangeIn(item));
+					}
+				}
+			}
+
+			close();
+		};
+
+		for (const range of ranges) {
+			range.getMinimalFlatRanges().forEach(collect);
+		}
+
+		return wrapRanges;
+	}
+
+	/**
+	 * Wraps the text of ranges with new elements, merged with the ones next to them, and keeps the selection on the text.
+	 */
+	private _wrapRanges(writer: ModelWriter, ranges: ModelRange[]): void {
+		// The last first: wrapping one does not move the ones before it.
+		const wrapRanges = this._getWrapRanges(ranges).reverse();
+
+		this._keepSelection(writer, ranges, () => {
+			for (const range of wrapRanges) {
+				const element = writer.createElement(this.elementName);
+
+				writer.wrap(range, element);
+				this._mergeWithSiblings(writer, element);
+			}
+		});
+	}
+
+	/**
+	 * Unwraps the elements in ranges and around their ends, and keeps the selection on the text.
+	 */
+	private _unwrapRanges(writer: ModelWriter, ranges: ModelRange[]): void {
+		const elements = this._getElementsIn(ranges);
+
+		this._keepSelection(writer, ranges, () => {
+			for (const element of elements) {
+				writer.unwrap(element);
+			}
+		});
+	}
+
+	/**
+	 * Changes the content of the selected ranges, and selects the same text then: the ends of the ranges stick to the
+	 * text, so they follow it into the elements and out of them.
+	 */
+	private _keepSelection(writer: ModelWriter, ranges: ModelRange[], change: () => void): void {
+		const backward = this.editor.model.document.selection.isBackward;
+		const ends = ranges.map(range => ({
+			start: ModelLivePosition.fromPosition(range.start, 'toNext'),
+			end: ModelLivePosition.fromPosition(range.end, 'toPrevious')
+		}));
+
+		change();
+		writer.setSelection(
+			ends.map(({ start, end }) => writer.createRange(start, end)),
+			{ backward }
+		);
+
+		for (const { start, end } of ends) {
+			start.detach();
+			end.detach();
+		}
+	}
+
+	/**
+	 * Merges a new element with the elements of the command next to it that have no attributes, as it has none.
+	 */
+	private _mergeWithSiblings(writer: ModelWriter, element: ModelElement): void {
+		const isPlain = (node: ModelNode | null): boolean =>
+			this.isElement(node) && node.getAttributeKeys().next().done === true;
+
+		if (isPlain(element.nextSibling)) {
+			writer.merge(writer.createPositionAfter(element));
+		}
+
+		if (isPlain(element.previousSibling)) {
+			writer.merge(writer.createPositionBefore(element));
+		}
+	}
+
+	/**
+	 * Puts the target out of the element it is in: a cursor at the start or the end of the element goes before or after
+	 * it, so that what is typed next is out of it; otherwise the element is unwrapped. A selected element that is
+	 * unwrapped leaves its content selected.
+	 */
+	private _leave(writer: ModelWriter, element: ModelElement, target: ElementOrPosition): void {
+		if (target.is('position') && target.parent === element && !element.isEmpty) {
+			if (target.isAtEnd || target.isAtStart) {
+				writer.setSelection(element, target.isAtEnd ? 'after' : 'before');
+
+				return;
+			}
+		}
+
+		const isSelected = this.editor.model.document.selection.getSelectedElement() === element;
+		const content = ModelLiveRange.fromRange(writer.createRangeIn(element));
+
+		writer.unwrap(element);
+
+		if (isSelected) {
+			writer.setSelection(content.toRange());
+		}
+
+		content.detach();
+	}
+
+	/**
+	 * Puts the target in a new element: at a position, an empty element with the cursor in it; an element, e.g. a
+	 * selected inline object, is wrapped, and selected.
+	 */
+	private _insert(writer: ModelWriter, target: ElementOrPosition): void {
+		if (target.is('position')) {
+			const element = writer.createElement(this.elementName);
+
+			writer.insert(element, target);
+			writer.setSelection(element, 0);
+		} else {
+			writer.wrap(writer.createRangeOn(target), this.elementName);
+			writer.setSelection(target, 'on');
+		}
+	}
+}

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/{convertElementSchema.ts → conversion/convertElementSchema.ts}

@@ -1,5 +1,6 @@
 import type { Editor } from 'ckeditor5';
-import type { ElementSchemaElement, ElementSchemaInput } from './types.js';
+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
@@ -14,15 +15,17 @@ export function getViewTag({ type, isInline }: Pick<ElementSchemaElement, 'type'
  * {@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 `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, editingTag, allowAttributes } = element as ElementSchemaElement;
+		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.
@@ -40,10 +43,21 @@ export function convertElementSchema(editor: Editor, input: ElementSchemaInput):
 			});
 		}
 
-		if (editingTag) {
+		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: { name: editingTag, classes: 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/elementSchema.ts

@@ -1,10 +1,10 @@
 import { Plugin, type ModelSchema } from 'ckeditor5';
 import { findPlugin } from 'ckeditor5-elements-core';
-import { compileElementSchema } from './compileElementSchema.js';
-import { convertElementSchema } from './convertElementSchema.js';
-import ElementSchemaError from './elementSchemaError.js';
-import type { ElementSchemaInput, ElementSchemaKind } from './types.js';
-import { validateElementSchema } from './validateElementSchema.js';
+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