@ckeditor/ckeditor5-minimap 0.0.0-internal-20241017.0

package/dist/utils.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module minimap/utils
+ */
+import { Rect } from 'ckeditor5/src/utils.js';
+import type { Editor } from 'ckeditor5/src/core.js';
+/**
+ * Clones the editing view DOM root by using a dedicated pair of {@link module:engine/view/renderer~Renderer} and
+ * {@link module:engine/view/domconverter~DomConverter}. The DOM root clone updates incrementally to stay in sync with the
+ * source root.
+ *
+ * @internal
+ * @param editor The editor instance the original editing root belongs to.
+ * @param rootName The name of the root to clone.
+ * @returns The editing root DOM clone element.
+ */
+export declare function cloneEditingViewDomRoot(editor: Editor, rootName?: string): HTMLElement;
+/**
+ * Harvests all web page styles, for instance, to allow re-using them in an `<iframe>` preserving the look of the content.
+ *
+ * The returned data format is as follows:
+ *
+ * ```ts
+ * [
+ * 	'p { color: red; ... } h2 { font-size: 2em; ... } ...',
+ * 	'.spacing { padding: 1em; ... }; ...',
+ * 	'...',
+ * 	{ href: 'http://link.to.external.stylesheet' },
+ * 	{ href: '...' }
+ * ]
+ * ```
+ *
+ * **Note**: For stylesheets with `href` different than window origin, an object is returned because
+ * accessing rules of these styles may cause CORS errors (depending on the configuration of the web page).
+ *
+ * @internal
+ */
+export declare function getPageStyles(): Array<string | {
+    href: string;
+}>;
+/**
+ * Gets dimensions rectangle according to passed DOM element. Returns whole window's size for `body` element.
+ *
+ * @internal
+ */
+export declare function getDomElementRect(domElement: HTMLElement): Rect;
+/**
+ * Gets client height according to passed DOM element. Returns window's height for `body` element.
+ *
+ * @internal
+ */
+export declare function getClientHeight(domElement: HTMLElement): number;
+/**
+ * Returns the DOM element itself if it's not a `body` element, whole window otherwise.
+ *
+ * @internal
+ */
+export declare function getScrollable(domElement: HTMLElement): Window | HTMLElement;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ckeditor/ckeditor5-minimap",
+  "version": "0.0.0-internal-20241017.0",
+  "description": "Content minimap feature for CKEditor 5.",
+  "keywords": [
+    "ckeditor",
+    "ckeditor5",
+    "ckeditor 5",
+    "ckeditor5-feature",
+    "ckeditor5-plugin",
+    "ckeditor5-dll"
+  ],
+  "type": "module",
+  "main": "src/index.js",
+  "dependencies": {
+    "@ckeditor/ckeditor5-core": "0.0.0-internal-20241017.0",
+    "@ckeditor/ckeditor5-engine": "0.0.0-internal-20241017.0",
+    "@ckeditor/ckeditor5-ui": "0.0.0-internal-20241017.0",
+    "@ckeditor/ckeditor5-utils": "0.0.0-internal-20241017.0",
+    "ckeditor5": "0.0.0-internal-20241017.0"
+  },
+  "author": "CKSource (http://cksource.com/)",
+  "license": "GPL-2.0-or-later",
+  "homepage": "https://ckeditor.com/ckeditor-5",
+  "bugs": "https://github.com/ckeditor/ckeditor5/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ckeditor/ckeditor5.git",
+    "directory": "packages/ckeditor5-minimap"
+  },
+  "files": [
+    "dist",
+    "lang",
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "theme",
+    "build",
+    "ckeditor5-metadata.json",
+    "CHANGELOG.md"
+  ],
+  "types": "src/index.d.ts"
+}

package/src/augmentation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import type { MinimapConfig, Minimap } from './index.js';
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * The configuration of the minimap feature. Introduced by the {@link module:minimap/minimap~Minimap} feature.
+         *
+         * Read more in {@link module:minimap/minimapconfig~MinimapConfig}.
+         */
+        minimap?: MinimapConfig;
+    }
+    interface PluginsMap {
+        [Minimap.pluginName]: Minimap;
+    }
+}

package/src/augmentation.js

@@ -0,0 +1,5 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+export {};

package/src/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module minimap
+ */
+export { default as Minimap } from './minimap.js';
+export type { MinimapConfig } from './minimapconfig.js';
+import './augmentation.js';

package/src/index.js

@@ -0,0 +1,9 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module minimap
+ */
+export { default as Minimap } from './minimap.js';
+import './augmentation.js';

package/src/minimap.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module minimap/minimap
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import '../theme/minimap.css';
+/**
+ * The content minimap feature.
+ */
+export default class Minimap extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "Minimap";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * The reference to the view of the minimap.
+     */
+    private _minimapView;
+    /**
+     * The DOM element closest to the editable element of the editor as returned
+     * by {@link module:ui/editorui/editorui~EditorUI#getEditableElement}.
+     */
+    private _scrollableRootAncestor;
+    /**
+     * The DOM element closest to the editable element of the editor as returned
+     * by {@link module:ui/editorui/editorui~EditorUI#getEditableElement}.
+     */
+    private _editingRootElement?;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Initializes the minimap view element and starts the layout synchronization
+     * on the editing view `render` event.
+     */
+    private _onUiReady;
+    /**
+     * Initializes the minimap view and attaches listeners that make it responsive to the environment (document)
+     * but also allow the minimap to control the document (scroll position).
+     */
+    private _initializeMinimapView;
+    /**
+     * @private
+     */
+    private _syncMinimapToEditingRootScrollPosition;
+}

package/src/minimap.js

@@ -0,0 +1,164 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module minimap/minimap
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { findClosestScrollableAncestor, global } from 'ckeditor5/src/utils.js';
+import MinimapView from './minimapview.js';
+import { cloneEditingViewDomRoot, getClientHeight, getDomElementRect, getPageStyles, getScrollable } from './utils.js';
+// @if CK_DEBUG_MINIMAP // const RectDrawer = require( '@ckeditor/ckeditor5-utils/tests/_utils/rectdrawer' ).default;
+import '../theme/minimap.css';
+/**
+ * The content minimap feature.
+ */
+export default class Minimap extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'Minimap';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        this._minimapView = null;
+        this._scrollableRootAncestor = null;
+        this.listenTo(editor.ui, 'ready', this._onUiReady.bind(this));
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this._minimapView.destroy();
+        this._minimapView.element.remove();
+    }
+    /**
+     * Initializes the minimap view element and starts the layout synchronization
+     * on the editing view `render` event.
+     */
+    _onUiReady() {
+        const editor = this.editor;
+        // TODO: This will not work with the multi-root editor.
+        const editingRootElement = this._editingRootElement = editor.ui.getEditableElement();
+        this._scrollableRootAncestor = findClosestScrollableAncestor(editingRootElement);
+        // DOM root element is not yet attached to the document.
+        if (!editingRootElement.ownerDocument.body.contains(editingRootElement)) {
+            editor.ui.once('update', this._onUiReady.bind(this));
+            return;
+        }
+        this._initializeMinimapView();
+        this.listenTo(editor.editing.view, 'render', () => {
+            if (editor.state !== 'ready') {
+                return;
+            }
+            this._syncMinimapToEditingRootScrollPosition();
+        });
+        this._syncMinimapToEditingRootScrollPosition();
+    }
+    /**
+     * Initializes the minimap view and attaches listeners that make it responsive to the environment (document)
+     * but also allow the minimap to control the document (scroll position).
+     */
+    _initializeMinimapView() {
+        const editor = this.editor;
+        const locale = editor.locale;
+        const useSimplePreview = editor.config.get('minimap.useSimplePreview');
+        // TODO: Throw an error if there is no `minimap` in config.
+        const minimapContainerElement = editor.config.get('minimap.container');
+        const scrollableRootAncestor = this._scrollableRootAncestor;
+        // TODO: This should be dynamic, the root width could change as the viewport scales if not fixed unit.
+        const editingRootElementWidth = getDomElementRect(this._editingRootElement).width;
+        const minimapContainerWidth = getDomElementRect(minimapContainerElement).width;
+        const minimapScaleRatio = minimapContainerWidth / editingRootElementWidth;
+        const minimapView = this._minimapView = new MinimapView({
+            locale,
+            scaleRatio: minimapScaleRatio,
+            pageStyles: getPageStyles(),
+            extraClasses: editor.config.get('minimap.extraClasses'),
+            useSimplePreview,
+            domRootClone: cloneEditingViewDomRoot(editor)
+        });
+        minimapView.render();
+        // Scrollable ancestor scroll -> minimap position update.
+        minimapView.listenTo(global.document, 'scroll', (evt, data) => {
+            if (scrollableRootAncestor === global.document.body) {
+                if (data.target !== global.document) {
+                    return;
+                }
+            }
+            else if (data.target !== scrollableRootAncestor) {
+                return;
+            }
+            this._syncMinimapToEditingRootScrollPosition();
+        }, { useCapture: true, usePassive: true });
+        // Viewport resize -> minimap position update.
+        minimapView.listenTo(global.window, 'resize', () => {
+            this._syncMinimapToEditingRootScrollPosition();
+        });
+        // Dragging the visible content area -> document (scrollable) position update.
+        minimapView.on('drag', (evt, movementY) => {
+            let movementYPercentage;
+            if (minimapView.scrollHeight === 0) {
+                movementYPercentage = 0;
+            }
+            else {
+                movementYPercentage = movementY / minimapView.scrollHeight;
+            }
+            const absoluteScrollProgress = movementYPercentage *
+                (scrollableRootAncestor.scrollHeight - getClientHeight(scrollableRootAncestor));
+            const scrollable = getScrollable(scrollableRootAncestor);
+            scrollable.scrollBy(0, Math.round(absoluteScrollProgress));
+        });
+        // Clicking the minimap -> center the document (scrollable) to the corresponding position.
+        minimapView.on('click', (evt, percentage) => {
+            const absoluteScrollProgress = percentage * scrollableRootAncestor.scrollHeight;
+            const scrollable = getScrollable(scrollableRootAncestor);
+            scrollable.scrollBy(0, Math.round(absoluteScrollProgress));
+        });
+        minimapContainerElement.appendChild(minimapView.element);
+    }
+    /**
+     * @private
+     */
+    _syncMinimapToEditingRootScrollPosition() {
+        const editingRootElement = this._editingRootElement;
+        const minimapView = this._minimapView;
+        minimapView.setContentHeight(editingRootElement.offsetHeight);
+        const editingRootRect = getDomElementRect(editingRootElement);
+        const scrollableRootAncestorRect = getDomElementRect(this._scrollableRootAncestor);
+        let scrollProgress;
+        // @if CK_DEBUG_MINIMAP // RectDrawer.clear();
+        // @if CK_DEBUG_MINIMAP // RectDrawer.draw( scrollableRootAncestorRect, { outlineColor: 'red' }, 'scrollableRootAncestor' );
+        // @if CK_DEBUG_MINIMAP // RectDrawer.draw( editingRootRect, { outlineColor: 'green' }, 'editingRoot' );
+        // The root is completely visible in the scrollable ancestor.
+        if (scrollableRootAncestorRect.contains(editingRootRect)) {
+            scrollProgress = 0;
+        }
+        else {
+            if (editingRootRect.top > scrollableRootAncestorRect.top) {
+                scrollProgress = 0;
+            }
+            else {
+                scrollProgress = (editingRootRect.top - scrollableRootAncestorRect.top) /
+                    (scrollableRootAncestorRect.height - editingRootRect.height);
+                scrollProgress = Math.max(0, Math.min(scrollProgress, 1));
+            }
+        }
+        // The intersection helps to change the tracker height when there is a lot of padding around the root.
+        // Note: It is **essential** that the height is set first because the progress depends on the correct tracker height.
+        minimapView.setPositionTrackerHeight(scrollableRootAncestorRect.getIntersection(editingRootRect).height);
+        minimapView.setScrollProgress(scrollProgress);
+    }
+}

package/src/minimapconfig.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module minimap/minimapconfig
+ */
+/**
+ * The configuration of the {@link module:minimap/minimap~Minimap} feature.
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( {
+ * 		minimap: ... // Minimap feature config.
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface MinimapConfig {
+    /**
+     * The DOM element container for the minimap.
+     *
+     * **Note**: The container must have a fixed `width` and `overflow: hidden` for the minimap to work correctly.
+     */
+    container: HTMLElement;
+    /**
+     * When set to `true`, the minimap will render content as simple boxes instead of replicating the look of the content (default).
+     */
+    useSimplePreview?: boolean;
+    /**
+     * Extra CSS class (or classes) that will be set internally on the `<body>` element of the `<iframe>` enclosing the minimap.
+     *
+     * By default, the minimap feature will attempt to clone all website styles and re-apply them in the `<iframe>` for the best accuracy.
+     * However, this may not work if the content of your editor inherits the styles from parent containers, resulting in inconsistent
+     * look and imprecise scrolling of the minimap.
+     *
+     * This optional configuration can address these issues by ensuring the same CSS rules apply to the content of the minimap
+     * and the original content of the editor.
+     *
+     * For instance, consider the following DOM structure:
+     *
+     * ```html
+     * <div class="website">
+     * 	<!-- ... -->
+     * 	<div class="styled-container">
+     * 		 <!-- ... -->
+     * 		<div id="editor">
+     * 			<!-- content of the editor -->
+     * 		</div>
+     * 	</div>
+     * 	<!-- ... -->
+     * </div>
+     * ```
+     *
+     * and the following CSS styles:
+     *
+     * ```css
+     * .website p {
+     * 	font-size: 13px;
+     * }
+     *
+     * .styled-container p {
+     * 	color: #ccc;
+     * }
+     * ```
+     *
+     * To maintain the consistency of styling (`font-size` and `color` of paragraphs), you will need to pass the CSS class names
+     * of these containers:
+     *
+     * ```ts
+     * ClassicEditor
+     * 	.create( document.getElementById( 'editor' ), {
+     * 		minimap: {
+     * 			extraClasses: 'website styled-container'
+     * 		}
+     * 	} )
+     * 	.then( ... )
+     * 	.catch( ... );
+     * ```
+     */
+    extraClasses?: string;
+}

package/src/minimapconfig.js

@@ -0,0 +1,5 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+export {};

package/src/minimapiframeview.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module minimap/minimapiframeview
+ */
+import { IframeView } from 'ckeditor5/src/ui.js';
+import { type Locale } from 'ckeditor5/src/utils.js';
+import type { MinimapViewOptions } from './minimapview.js';
+/**
+ * The internal `<iframe>` view that hosts the minimap content.
+ *
+ * @internal
+ */
+export default class MinimapIframeView extends IframeView {
+    /**
+     * The CSS `top` used to scroll the minimap.
+     *
+     * @readonly
+     */
+    top: number;
+    /**
+     * The CSS `height` of the iframe.
+     *
+     * @readonly
+     */
+    height: number;
+    /**
+     * Cached view constructor options for re-use in other methods.
+     */
+    private readonly _options;
+    /**
+     * Creates an instance of the internal minimap iframe.
+     */
+    constructor(locale: Locale, options: MinimapViewOptions);
+    /**
+     * @inheritDoc
+     */
+    render(): Promise<unknown>;
+    /**
+     * Sets the new height of the iframe.
+     */
+    setHeight(newHeight: number): void;
+    /**
+     * Sets the top offset of the iframe to move it around vertically.
+     */
+    setTopOffset(newOffset: number): void;
+    /**
+     * Sets the internal structure of the `<iframe>` readying it to display the
+     * minimap element.
+     */
+    private _prepareDocument;
+}

package/src/minimapiframeview.js

@@ -0,0 +1,132 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module minimap/minimapiframeview
+ */
+import { IframeView } from 'ckeditor5/src/ui.js';
+import { toUnit } from 'ckeditor5/src/utils.js';
+const toPx = /* #__PURE__ */ toUnit('px');
+/**
+ * The internal `<iframe>` view that hosts the minimap content.
+ *
+ * @internal
+ */
+export default class MinimapIframeView extends IframeView {
+    /**
+     * Creates an instance of the internal minimap iframe.
+     */
+    constructor(locale, options) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.set('top', 0);
+        this.set('height', 0);
+        this._options = options;
+        this.extendTemplate({
+            attributes: {
+                tabindex: -1,
+                'aria-hidden': 'true',
+                class: [
+                    'ck-minimap__iframe'
+                ],
+                style: {
+                    top: bind.to('top', top => toPx(top)),
+                    height: bind.to('height', height => toPx(height))
+                }
+            }
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        return super.render().then(() => {
+            this._prepareDocument();
+        });
+    }
+    /**
+     * Sets the new height of the iframe.
+     */
+    setHeight(newHeight) {
+        this.height = newHeight;
+    }
+    /**
+     * Sets the top offset of the iframe to move it around vertically.
+     */
+    setTopOffset(newOffset) {
+        this.top = newOffset;
+    }
+    /**
+     * Sets the internal structure of the `<iframe>` readying it to display the
+     * minimap element.
+     */
+    _prepareDocument() {
+        const iframeDocument = this.element.contentWindow.document;
+        const domRootClone = iframeDocument.adoptNode(this._options.domRootClone);
+        const boxStyles = this._options.useSimplePreview ? `
+			.ck.ck-editor__editable_inline img {
+				filter: contrast( 0 );
+			}
+
+			p, li, a, figcaption, span {
+				background: hsl(0, 0%, 80%) !important;
+				color: hsl(0, 0%, 80%) !important;
+			}
+
+			h1, h2, h3, h4 {
+				background: hsl(0, 0%, 60%) !important;
+				color: hsl(0, 0%, 60%) !important;
+			}
+		` : '';
+        const pageStyles = this._options.pageStyles.map(definition => {
+            if (typeof definition === 'string') {
+                return `<style>${definition}</style>`;
+            }
+            else {
+                return `<link rel="stylesheet" type="text/css" href="${definition.href}">`;
+            }
+        }).join('\n');
+        const html = `<!DOCTYPE html><html lang="en">
+			<head>
+				<meta charset="utf-8">
+				<meta name="viewport" content="width=device-width, initial-scale=1">
+				${pageStyles}
+				<style>
+					html, body {
+						margin: 0 !important;
+						padding: 0 !important;
+					}
+
+					html {
+						overflow: hidden;
+					}
+
+					body {
+						transform: scale( ${this._options.scaleRatio} );
+						transform-origin: 0 0;
+						overflow: visible;
+					}
+
+					.ck.ck-editor__editable_inline {
+						margin: 0 !important;
+						border-color: transparent !important;
+						outline-color: transparent !important;
+						box-shadow: none !important;
+					}
+
+					.ck.ck-content {
+						background: white;
+					}
+
+					${boxStyles}
+				</style>
+			</head>
+			<body class="${this._options.extraClasses || ''}"></body>
+		</html>`;
+        iframeDocument.open();
+        iframeDocument.write(html);
+        iframeDocument.close();
+        iframeDocument.body.appendChild(domRootClone);
+    }
+}