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

package/src/breadcrumbs.ts

@@ -0,0 +1,375 @@
+import {
+	Plugin,
+	type DifferItem,
+	type Editor,
+	type Locale,
+	type ModelDocumentChangeEvent,
+	type ModelDocumentFragment,
+	type ModelElement,
+	type ModelRootElement,
+	type RectSource,
+	type ViewDocumentFragment,
+	type ViewElement,
+	type ViewNode
+} from 'ckeditor5';
+import { findPlugin } from 'ckeditor5-elements-core';
+import { type BreadcrumbItem, type default as BreadcrumbItemView } from './breadcrumbItemView.js';
+import BreadcrumbsView, { type BreadcrumbsViewExecuteEvent } from './breadcrumbsView.js';
+
+/**
+ * Converting the data view of a large document takes a while. When the last conversion took longer than this (in
+ * milliseconds), the next one waits for {@link THROTTLE_TIME}, so editing elements quickly does not convert every time.
+ */
+const SLOW_CONVERSION_TIME = 10;
+const THROTTLE_TIME = 250;
+
+/**
+ * The configuration of the {@link Breadcrumbs} plugin.
+ */
+export interface BreadcrumbsConfig {
+	/**
+	 * Returns the items of the menu that opens when a breadcrumb is clicked, for the element of the breadcrumb: the
+	 * same items as in the `elementContextMenu` option (commands, submenus and `'|'` separators; see `ElementMenuConfig`),
+	 * so one callback can serve both. Without this option, or without a loaded `ElementMenu` plugin, breadcrumbs cannot
+	 * be clicked.
+	 */
+	menu?: BreadcrumbsMenuItems;
+}
+
+/**
+ * The data view of a root, with the model elements mapped to their view elements and back.
+ */
+interface DataView {
+	root: ModelRootElement;
+	viewElements: WeakMap<ModelElement, ViewElement>;
+	modelElements: WeakMap<ViewElement, ModelElement>;
+}
+
+/**
+ * Shows the data view structure at the current selection (the elements of the editor data, as in `getData()`), e.g.
+ * `aside.note › p`, `ul › li` or `figure.table › table › tbody › tr › td`.
+ *
+ * Text attributes such as `<strong>` are skipped. The selected element, e.g. an image, is the innermost item.
+ *
+ * Place them in a toolbar as the `breadcrumbs` component, or anywhere else using a view from {@link createView}.
+ *
+ * Clicking is configured only by the `breadcrumbs.menu` editor config option (see {@link BreadcrumbsConfig}): with it,
+ * the items are buttons that open a menu of their element; without it, they are labels. The menu is shown by the
+ * `ElementMenu` plugin (loaded by `ElementContextMenu` and `QuickInsert`), which is used through the
+ * {@link BreadcrumbsMenu} interface: the breadcrumbs do not depend on the other features.
+ *
+ * The data view is converted again only when elements change, not when typing or moving the cursor. For a large
+ * document, that happens at most every 250 ms.
+ */
+export default class Breadcrumbs extends Plugin {
+	/**
+	 * The elements at the current selection, from the outermost to the innermost one.
+	 *
+	 * @observable
+	 */
+	declare public items: readonly BreadcrumbItem[];
+
+	private _dataView: DataView | null = null;
+	private _isDataViewOutdated = true;
+	private _isConversionSlow = false;
+	private _conversionTimeout: ReturnType<typeof setTimeout> | null = null;
+
+	public static get pluginName(): 'Breadcrumbs' {
+		return 'Breadcrumbs' as const;
+	}
+
+	constructor(editor: Editor) {
+		super(editor);
+
+		this.set('items', []);
+	}
+
+	public init(): void {
+		const editor = this.editor;
+
+		editor.ui.componentFactory.add('breadcrumbs', locale => this.createView(locale));
+
+		this.listenTo(editor.ui, 'ready', () => {
+			this.refresh();
+		});
+
+		// Both selection and data changes.
+		this.listenTo<ModelDocumentChangeEvent>(editor.model.document, 'change', () => {
+			if (hasElementChanges(editor.model.document.differ.getChanges())) {
+				this._isDataViewOutdated = true;
+			}
+
+			this._update();
+		});
+	}
+
+	/**
+	 * Creates a breadcrumbs view that follows {@link items}.
+	 */
+	public createView(locale: Locale = this.editor.locale): BreadcrumbsView {
+		const isClickable = typeof this.editor.config.get('breadcrumbs')?.menu === 'function' && !!this._getMenu();
+		const view = new BreadcrumbsView(locale, { isClickable });
+
+		view.setItems(this.items);
+		view.listenTo(this, 'change:items', () => {
+			view.setItems(this.items);
+		});
+
+		view.on<BreadcrumbsViewExecuteEvent>('execute', (evt, item) => {
+			this._openMenu(item);
+		});
+
+		return view;
+	}
+
+	/**
+	 * Updates {@link items} from the current selection, converting the data view first when elements changed.
+	 */
+	public refresh(): void {
+		const root = this.editor.model.document.selection.getFirstPosition()?.root;
+
+		if (root?.is('rootElement') && (this._isDataViewOutdated || root !== this._dataView?.root)) {
+			this._convert(root);
+		}
+
+		const items = this._getItems();
+
+		if (!areEqual(items, this.items)) {
+			this.items = items;
+		}
+	}
+
+	public override destroy(): void {
+		this._cancelConversion();
+		super.destroy();
+	}
+
+	/**
+	 * Refreshes the items after a change. When converting is slow, the data view is converted later, and the items
+	 * follow the outdated data view until then.
+	 */
+	private _update(): void {
+		const root = this.editor.model.document.selection.getFirstPosition()?.root;
+
+		if (this._isDataViewOutdated && this._isConversionSlow && root === this._dataView?.root) {
+			this._conversionTimeout ??= setTimeout(() => {
+				this._conversionTimeout = null;
+				this.refresh();
+			}, THROTTLE_TIME);
+		}
+
+		if (this._conversionTimeout) {
+			const items = this._getItems();
+
+			if (!areEqual(items, this.items)) {
+				this.items = items;
+			}
+		} else {
+			this.refresh();
+		}
+	}
+
+	/**
+	 * Converts the root to the data view, and maps its model elements to their view elements.
+	 */
+	private _convert(root: ModelRootElement): void {
+		const data = this.editor.data;
+		const start = performance.now();
+		const viewElements = new WeakMap<ModelElement, ViewElement>();
+		const modelElements = new WeakMap<ViewElement, ModelElement>();
+
+		// The mapper of the data pipeline is cleared by the next conversion (e.g. `getData()`), so keep the mapping.
+		data.toView(root);
+
+		for (const { item } of this.editor.model.createRangeIn(root)) {
+			const viewElement = item.is('element') ? data.mapper.toViewElement(item) : undefined;
+
+			if (item.is('element') && viewElement) {
+				viewElements.set(item, viewElement);
+				modelElements.set(viewElement, item);
+			}
+		}
+
+		this._dataView = { root, viewElements, modelElements };
+		this._isDataViewOutdated = false;
+		this._isConversionSlow = performance.now() - start > SLOW_CONVERSION_TIME;
+		this._cancelConversion();
+	}
+
+	private _cancelConversion(): void {
+		if (this._conversionTimeout) {
+			clearTimeout(this._conversionTimeout);
+			this._conversionTimeout = null;
+		}
+	}
+
+	/**
+	 * Returns the data view elements at the selection: the view element of the selected element, or of the innermost
+	 * element with the selection, and its ancestors.
+	 */
+	private _getItems(): BreadcrumbItem[] {
+		const dataView = this._dataView;
+		const selection = this.editor.model.document.selection;
+		const position = selection.getFirstPosition();
+
+		if (!dataView || position?.root !== dataView.root) {
+			return [];
+		}
+
+		// Elements created since the last conversion are not mapped yet; their closest mapped ancestor is used meanwhile.
+		let viewElement: ViewElement | undefined;
+
+		for (
+			let element: ModelElement | ModelDocumentFragment | null =
+				selection.getSelectedElement() ?? position.parent;
+			element?.is('element') && !element.is('rootElement') && !viewElement;
+			element = element.parent
+		) {
+			viewElement = dataView.viewElements.get(element);
+		}
+
+		return viewElement ? getPath(viewElement).map(node => createItem(node, dataView)) : [];
+	}
+
+	private _openMenu(item: BreadcrumbItemView): void {
+		const menuItems = this.editor.config.get('breadcrumbs')?.menu;
+		const menu = this._getMenu();
+		const element = item.modelElement;
+
+		if (!menuItems || !menu || !item.element || !element || !isInDocument(element)) {
+			return;
+		}
+
+		item.isExpanded = menu.open(element, item.element, menuItems, {
+			// The breadcrumbs may have been replaced while the menu was open.
+			returnFocusTo: {
+				focus: () => {
+					if (item.element?.isConnected) {
+						item.focus();
+					} else {
+						this.editor.editing.view.focus();
+					}
+				}
+			},
+			onHide: () => {
+				item.isExpanded = false;
+			}
+		});
+	}
+
+	/**
+	 * Returns the plugin that shows menus: `ElementMenu`, when it is loaded.
+	 */
+	private _getMenu(): BreadcrumbsMenu | null {
+		return findPlugin(this.editor, 'ElementMenu', isBreadcrumbsMenu);
+	}
+}
+
+/**
+ * The part of the `ElementMenu` plugin the breadcrumbs use. The breadcrumbs do not depend on the other features: the
+ * plugin is looked up by name and checked against this interface.
+ */
+export interface BreadcrumbsMenu {
+	open(
+		element: ModelElement,
+		target: RectSource,
+		items: BreadcrumbsMenuItems,
+		options: BreadcrumbsMenuOptions
+	): boolean;
+}
+
+/**
+ * The options the breadcrumbs pass to {@link BreadcrumbsMenu#open}.
+ */
+export interface BreadcrumbsMenuOptions {
+	/**
+	 * What gets the focus when the menu is closed with Esc: the breadcrumb that opened it.
+	 */
+	returnFocusTo: { focus(): void };
+
+	/**
+	 * Called when the menu closes.
+	 */
+	onHide: () => void;
+}
+
+/**
+ * Returns the items of the menu of an element. The breadcrumbs pass them to the menu plugin as they are; for
+ * `ElementMenu`, they are commands, submenus and `'|'` separators.
+ */
+export type BreadcrumbsMenuItems = (element: ModelElement, editor: Editor) => readonly unknown[];
+
+function isBreadcrumbsMenu(plugin: object): plugin is BreadcrumbsMenu {
+	return 'open' in plugin && typeof plugin.open === 'function';
+}
+
+/**
+ * Whether the changes add, remove or change elements. Typing (text changes) does not change the data view structure.
+ */
+function hasElementChanges(changes: readonly DifferItem[]): boolean {
+	return changes.some(change =>
+		change.type === 'attribute'
+			? Array.from(change.range.getItems({ shallow: true })).some(item => item.is('element'))
+			: change.name !== '$text'
+	);
+}
+
+/**
+ * Returns the view element and its ancestors, outermost first, without:
+ *
+ * * text attributes (attribute elements without a block inside, such as `<strong>` or `<a>`); list items (`<ul>`,
+ *   `<li>`) are attribute elements too, but wrap blocks,
+ * * elements that are not rendered in the data, such as the paragraph in a list item or a table cell that has only
+ *   one paragraph.
+ */
+function getPath(viewElement: ViewElement): ViewElement[] {
+	const path: ViewElement[] = [];
+	let hasBlock = false;
+
+	for (let node: ViewNode | ViewDocumentFragment | null = viewElement; node?.is('element'); node = node.parent) {
+		const isTextAttribute = node.is('attributeElement') && !hasBlock;
+
+		if (!isTextAttribute && !node.getCustomProperty('dataPipeline:transparentRendering')) {
+			path.unshift(node);
+		}
+
+		hasBlock ||= node.is('containerElement');
+	}
+
+	return path;
+}
+
+/**
+ * Creates the item of a view element. Its model element is the mapped one, or the closest mapped ancestor of a part of
+ * a structure (e.g. a `tbody` is a part of a table). List items have none: they come from the attributes of the blocks
+ * in them, not from an element.
+ */
+function createItem(viewElement: ViewElement, dataView: DataView): BreadcrumbItem {
+	let modelElement: ModelElement | null = null;
+
+	for (
+		let node: ViewNode | ViewDocumentFragment | null = viewElement;
+		node?.is('element') && !modelElement && !node.is('attributeElement');
+		node = node.parent
+	) {
+		modelElement = dataView.modelElements.get(node) ?? null;
+	}
+
+	return { label: [viewElement.name, ...viewElement.getClassNames()].join('.'), viewElement, modelElement };
+}
+
+/**
+ * Whether the element is in the document, i.e. not removed.
+ */
+function isInDocument(element: ModelElement): boolean {
+	const root = element.root;
+
+	return root.is('rootElement') && root.rootName !== '$graveyard' && root.isAttached();
+}
+
+function areEqual(a: readonly BreadcrumbItem[], b: readonly BreadcrumbItem[]): boolean {
+	return (
+		a.length === b.length &&
+		a.every((item, index) => item.label === b[index]?.label && item.modelElement === b[index].modelElement)
+	);
+}

package/src/breadcrumbsView.ts

@@ -0,0 +1,176 @@
+import { KeystrokeHandler, View, ViewCollection, type Locale } from 'ckeditor5';
+import BreadcrumbItemView, { type BreadcrumbItem } from './breadcrumbItemView.js';
+import BreadcrumbLabelView from './breadcrumbLabelView.js';
+
+/**
+ * The options of {@link BreadcrumbsView}.
+ */
+export interface BreadcrumbsViewOptions {
+	/**
+	 * Whether the items are buttons that can be clicked, or labels. Defaults to `false`.
+	 */
+	isClickable?: boolean;
+}
+
+/**
+ * Shows a path of elements, from the outermost to the innermost one, as a list (`<ol>`) in a `<nav>` landmark: buttons
+ * when the items can be clicked, labels otherwise. Items without a model element (list items) are labels too. The
+ * innermost item is marked with `aria-current="location"`.
+ *
+ * The left and right arrows move the focus between the items; past the first or the last one, they are left to the
+ * toolbar the view is in. Fires `execute` with the item when one of the buttons is clicked.
+ */
+export default class BreadcrumbsView extends View {
+	/**
+	 * The breadcrumb items: the buttons or labels, from the outermost to the innermost one.
+	 */
+	public readonly items = new ViewCollection<BreadcrumbItemView | BreadcrumbLabelView>();
+
+	/**
+	 * Whether the items are buttons that can be clicked, or labels.
+	 */
+	public readonly isClickable: boolean;
+
+	/**
+	 * Handles the keystrokes within the breadcrumbs.
+	 */
+	public readonly keystrokes = new KeystrokeHandler();
+
+	/**
+	 * The list items (`<li>`) that hold the {@link items}.
+	 */
+	private readonly _listItems: ViewCollection<BreadcrumbsListItemView>;
+
+	constructor(locale?: Locale, { isClickable = false }: BreadcrumbsViewOptions = {}) {
+		super(locale);
+
+		this._listItems = this.createCollection();
+		this.isClickable = isClickable;
+
+		const isRtl = locale?.uiLanguageDirection === 'rtl';
+
+		this.keystrokes.set(isRtl ? 'arrowright' : 'arrowleft', (data, cancel) => {
+			if (this._focusSibling(-1)) {
+				cancel();
+			}
+		});
+
+		this.keystrokes.set(isRtl ? 'arrowleft' : 'arrowright', (data, cancel) => {
+			if (this._focusSibling(1)) {
+				cancel();
+			}
+		});
+
+		this.setTemplate({
+			tag: 'nav',
+			attributes: {
+				class: ['ck', 'ck-elements-breadcrumbs'],
+				'aria-label': locale?.t('Element path') ?? 'Element path'
+			},
+			children: [
+				{
+					tag: 'ol',
+					attributes: {
+						class: ['ck', 'ck-elements-breadcrumbs__list']
+					},
+					children: this._listItems
+				}
+			]
+		});
+	}
+
+	/**
+	 * Replaces the items.
+	 */
+	public setItems(items: readonly BreadcrumbItem[]): void {
+		for (const listItem of this._listItems) {
+			listItem.destroy();
+		}
+
+		this._listItems.clear();
+		this.items.clear();
+
+		items.forEach((item, index) => {
+			const isCurrent = index === items.length - 1;
+			const view =
+				this.isClickable && item.modelElement
+					? new BreadcrumbItemView(this.locale, item, { isCurrent })
+					: new BreadcrumbLabelView(this.locale, item, { isCurrent });
+
+			if (view instanceof BreadcrumbItemView) {
+				view.on('execute', () => {
+					this.fire<BreadcrumbsViewExecuteEvent>('execute', view);
+				});
+			}
+
+			this.items.add(view);
+			this._listItems.add(new BreadcrumbsListItemView(this.locale, view));
+		});
+	}
+
+	/**
+	 * Renders the view and starts handling the keystrokes.
+	 */
+	public override render(): void {
+		super.render();
+
+		if (this.element) {
+			this.keystrokes.listenTo(this.element);
+		}
+	}
+
+	/**
+	 * Focuses an item: the first one when the focus moves forward (`1`, e.g. from the previous toolbar item), the
+	 * innermost one otherwise.
+	 */
+	public focus(direction?: 1 | -1): void {
+		(direction === 1 ? this.items.first : this.items.last)?.focus();
+	}
+
+	/**
+	 * Destroys the view and its keystroke handler.
+	 */
+	public override destroy(): void {
+		super.destroy();
+		this.keystrokes.destroy();
+	}
+
+	/**
+	 * Focuses the item before (`-1`) or after (`1`) the focused one. Returns `false` when there is none.
+	 */
+	private _focusSibling(step: 1 | -1): boolean {
+		const items = Array.from(this.items);
+		const index = items.findIndex(item => item.element === document.activeElement);
+		const sibling = index === -1 ? undefined : items[index + step];
+
+		sibling?.focus();
+
+		return !!sibling;
+	}
+}
+
+/**
+ * Fired by {@link BreadcrumbsView} when one of its buttons is clicked.
+ */
+export interface BreadcrumbsViewExecuteEvent {
+	name: 'execute';
+	args: [item: BreadcrumbItemView];
+}
+
+/**
+ * A list item (`<li>`) of the breadcrumbs, holding a button or a label.
+ */
+class BreadcrumbsListItemView extends View {
+	constructor(locale: Locale | undefined, item: BreadcrumbItemView | BreadcrumbLabelView) {
+		super(locale);
+
+		// Rendering registers the item as a child, so it is destroyed with the list item.
+		this.setTemplate({
+			tag: 'li',
+			attributes: {
+				class: ['ck', 'ck-elements-breadcrumbs__list-item']
+			},
+			children: [item]
+		});
+	}
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Breadcrumbs: the element path at the selection, optionally clickable with a configured menu.
+ *
+ * @module ckeditor5-elements-breadcrumbs
+ */
+
+// Plugins.
+export {
+	default as Breadcrumbs,
+	type BreadcrumbsConfig,
+	type BreadcrumbsMenu,
+	type BreadcrumbsMenuItems,
+	type BreadcrumbsMenuOptions
+} from './breadcrumbs.js';
+
+// Views.
+export {
+	default as BreadcrumbsView,
+	type BreadcrumbsViewExecuteEvent,
+	type BreadcrumbsViewOptions
+} from './breadcrumbsView.js';
+export {
+	default as BreadcrumbItemView,
+	type BreadcrumbItem,
+	type BreadcrumbItemViewOptions
+} from './breadcrumbItemView.js';
+export { default as BreadcrumbLabelView } from './breadcrumbLabelView.js';
+
+import './augmentation.js';

package/theme/breadcrumbs.css

@@ -0,0 +1,103 @@
+/*
+ * 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;
+}