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

package/src/convertElementSchema.ts

@@ -0,0 +1,51 @@
+import type { Editor } from 'ckeditor5';
+import type { ElementSchemaElement, ElementSchemaInput } from './types.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.
+ */
+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 tag = getViewTag(element as ElementSchemaElement);
+		const view = { name: tag, classes: name };
+
+		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 (editingTag) {
+			conversion.for('editingDowncast').elementToElement({
+				model: name,
+				view: { name: editingTag, classes: name },
+				converterPriority: 'high'
+			});
+		}
+	}
+}

package/src/elementSchema.ts

@@ -0,0 +1,133 @@
+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';
+
+/**
+ * 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/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/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Element schema: declare elements in the model schema from a simple definition, e.g. a JSON file, with three types of
+ * elements (`empty`, `block`, `container`), and a validation that rejects contradictory definitions.
+ *
+ * @module ckeditor5-elements-schema
+ */
+
+// Plugins.
+export { default as ElementSchema } from './elementSchema.js';
+
+// Validation and compiling, which do not need an editor (also in `validate.ts`, for Node.js).
+export * from './validate.js';
+
+import './augmentation.js';

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

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

@@ -0,0 +1,20 @@
+/**
+ * The part of the element schema that needs no editor and no browser: the validation, the compiling to schema
+ * definitions, the error and the types. It is in its own module, so that it can be used in Node.js, e.g. to validate a
+ * schema file in a test or in CI: the main entry loads CKEditor, which needs a DOM.
+ *
+ * @module ckeditor5-elements-schema/validate
+ */
+
+export { validateElementSchema } from './validateElementSchema.js';
+export { compileElementSchema, type CompiledElementSchema } from './compileElementSchema.js';
+export { default as ElementSchemaError } from './elementSchemaError.js';
+export type {
+	ElementSchemaDefinition,
+	ElementSchemaElement,
+	ElementSchemaInput,
+	ElementSchemaIssue,
+	ElementSchemaKind,
+	ElementSchemaType,
+	ValidateElementSchemaOptions
+} from './types.js';