@ckeditor/ckeditor5-minimap 0.0.0-internal-20241017.0

package/src/minimappositiontrackerview.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/minimappositiontrackerview
+ */
+import { View } from 'ckeditor5/src/ui.js';
+import { type Locale } from 'ckeditor5/src/utils.js';
+/**
+ * The position tracker visualizing the visible subset of the content. Displayed over the minimap.
+ *
+ * @internal
+ */
+export default class MinimapPositionTrackerView extends View {
+    /**
+     * The CSS `height` of the tracker visualizing the subset of the content visible to the user.
+     *
+     * @readonly
+     */
+    height: number;
+    /**
+     * The CSS `top` of the tracker, used to move it vertically over the minimap.
+     *
+     * @readonly
+     */
+    top: number;
+    /**
+     * The scroll progress (in %) displayed over the tracker when being dragged by the user.
+     *
+     * @readonly
+     */
+    scrollProgress: number;
+    /**
+     * Indicates whether the tracker is being dragged by the user (e.g. using the mouse).
+     *
+     * @internal
+     * @readonly
+     */
+    _isDragging: boolean;
+    constructor(locale: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Sets the new height of the tracker to visualize the subset of the content visible to the user.
+     */
+    setHeight(newHeight: number): void;
+    /**
+     * Sets the top offset of the tracker to move it around vertically.
+     */
+    setTopOffset(newOffset: number): void;
+    /**
+     * Sets the scroll progress (in %) to inform the user using a label when the tracker is being dragged.
+     */
+    setScrollProgress(newProgress: number): void;
+}

package/src/minimappositiontrackerview.js

@@ -0,0 +1,78 @@
+/**
+ * @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/minimappositiontrackerview
+ */
+import { View } from 'ckeditor5/src/ui.js';
+import { toUnit, global } from 'ckeditor5/src/utils.js';
+const toPx = /* #__PURE__ */ toUnit('px');
+/**
+ * The position tracker visualizing the visible subset of the content. Displayed over the minimap.
+ *
+ * @internal
+ */
+export default class MinimapPositionTrackerView extends View {
+    constructor(locale) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.set('height', 0);
+        this.set('top', 0);
+        this.set('scrollProgress', 0);
+        this.set('_isDragging', false);
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-minimap__position-tracker',
+                    bind.if('_isDragging', 'ck-minimap__position-tracker_dragging')
+                ],
+                style: {
+                    top: bind.to('top', top => toPx(top)),
+                    height: bind.to('height', height => toPx(height))
+                },
+                'data-progress': bind.to('scrollProgress')
+            },
+            on: {
+                mousedown: bind.to(() => {
+                    this._isDragging = true;
+                })
+            }
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this.listenTo(global.document, 'mousemove', (evt, data) => {
+            if (!this._isDragging) {
+                return;
+            }
+            this.fire('drag', data.movementY);
+        }, { useCapture: true });
+        this.listenTo(global.document, 'mouseup', () => {
+            this._isDragging = false;
+        }, { useCapture: true });
+    }
+    /**
+     * Sets the new height of the tracker to visualize the subset of the content visible to the user.
+     */
+    setHeight(newHeight) {
+        this.height = newHeight;
+    }
+    /**
+     * Sets the top offset of the tracker to move it around vertically.
+     */
+    setTopOffset(newOffset) {
+        this.top = newOffset;
+    }
+    /**
+     * Sets the scroll progress (in %) to inform the user using a label when the tracker is being dragged.
+     */
+    setScrollProgress(newProgress) {
+        this.scrollProgress = newProgress;
+    }
+}

package/src/minimapview.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @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/minimapview
+ */
+import { View } from 'ckeditor5/src/ui.js';
+import { type Locale } from 'ckeditor5/src/utils.js';
+export type MinimapViewOptions = {
+    domRootClone: HTMLElement;
+    pageStyles: Array<string | {
+        href: string;
+    }>;
+    scaleRatio: number;
+    useSimplePreview?: boolean;
+    extraClasses?: string;
+};
+/**
+ * The main view of the minimap. It renders the original content but scaled down with a tracker element
+ * visualizing the subset of the content visible to the user and allowing interactions (scrolling, dragging).
+ *
+ * @internal
+ */
+export default class MinimapView extends View {
+    /**
+     * An instance of the tracker view displayed over the minimap.
+     */
+    private readonly _positionTrackerView;
+    /**
+     * The scale ratio of the minimap relative to the original editing DOM root with the content.
+     */
+    private readonly _scaleRatio;
+    /**
+     * An instance of the iframe view that hosts the minimap.
+     */
+    private readonly _minimapIframeView;
+    /**
+     * Creates an instance of the minimap view.
+     */
+    constructor({ locale, scaleRatio, pageStyles, extraClasses, useSimplePreview, domRootClone }: {
+        locale: Locale;
+    } & MinimapViewOptions);
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Returns the DOM {@link module:utils/dom/rect~Rect} height of the minimap.
+     */
+    get height(): number;
+    /**
+     * Returns the number of available space (pixels) the position tracker (visible subset of the content) can use to scroll vertically.
+     */
+    get scrollHeight(): number;
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Sets the new height of the minimap (in px) to respond to the changes in the original editing DOM root.
+     *
+     * **Note**:The provided value should be the `offsetHeight` of the original editing DOM root.
+     */
+    setContentHeight(newHeight: number): void;
+    /**
+     * Sets the minimap scroll progress.
+     *
+     * The minimap scroll progress is linked to the original editing DOM root and its scrollable container (ancestor).
+     * Changing the progress will alter the vertical position of the minimap (and its position tracker) and give the user an accurate
+     * overview of the visible document.
+     *
+     * **Note**: The value should be between 0 and 1. 0 when the DOM root has not been scrolled, 1 when the
+     * scrolling has reached the end.
+     */
+    setScrollProgress(newScrollProgress: number): void;
+    /**
+     * Sets the new height of the tracker (in px) to visualize the subset of the content visible to the user.
+     */
+    setPositionTrackerHeight(trackerHeight: number): void;
+    /**
+     * @param data DOM event data
+     */
+    private _handleMinimapClick;
+    /**
+     * @param data DOM event data
+     */
+    private _handleMinimapMouseWheel;
+}
+/**
+ * Fired when the minimap view is clicked.
+ *
+ * @eventName ~MinimapView#click
+ * @param percentage The number between 0 and 1 representing a place in the minimap (its height) that was clicked.
+ */
+export type MinimapClickEvent = {
+    name: 'click';
+    args: [percentage: number];
+};
+/**
+ * Fired when the position tracker is dragged or the minimap is scrolled via mouse wheel.
+ *
+ * @eventName ~MinimapView#drag
+ * @param movementY The vertical movement of the minimap as a result of dragging or scrolling.
+ */
+export type MinimapDragEvent = {
+    name: 'drag';
+    args: [movementY: number];
+};

package/src/minimapview.js

@@ -0,0 +1,137 @@
+/**
+ * @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/minimapview
+ */
+import { View } from 'ckeditor5/src/ui.js';
+import { Rect } from 'ckeditor5/src/utils.js';
+import MinimapIframeView from './minimapiframeview.js';
+import MinimapPositionTrackerView from './minimappositiontrackerview.js';
+/**
+ * The main view of the minimap. It renders the original content but scaled down with a tracker element
+ * visualizing the subset of the content visible to the user and allowing interactions (scrolling, dragging).
+ *
+ * @internal
+ */
+export default class MinimapView extends View {
+    /**
+     * Creates an instance of the minimap view.
+     */
+    constructor({ locale, scaleRatio, pageStyles, extraClasses, useSimplePreview, domRootClone }) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this._positionTrackerView = new MinimapPositionTrackerView(locale);
+        this._positionTrackerView.delegate('drag').to(this);
+        this._scaleRatio = scaleRatio;
+        this._minimapIframeView = new MinimapIframeView(locale, {
+            useSimplePreview,
+            pageStyles,
+            extraClasses,
+            scaleRatio,
+            domRootClone
+        });
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-minimap'
+                ]
+            },
+            children: [
+                this._positionTrackerView
+            ],
+            on: {
+                click: bind.to(this._handleMinimapClick.bind(this)),
+                wheel: bind.to(this._handleMinimapMouseWheel.bind(this))
+            }
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        this._minimapIframeView.destroy();
+        super.destroy();
+    }
+    /**
+     * Returns the DOM {@link module:utils/dom/rect~Rect} height of the minimap.
+     */
+    get height() {
+        return new Rect(this.element).height;
+    }
+    /**
+     * Returns the number of available space (pixels) the position tracker (visible subset of the content) can use to scroll vertically.
+     */
+    get scrollHeight() {
+        return Math.max(0, Math.min(this.height, this._minimapIframeView.height) - this._positionTrackerView.height);
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this._minimapIframeView.render();
+        this.element.appendChild(this._minimapIframeView.element);
+    }
+    /**
+     * Sets the new height of the minimap (in px) to respond to the changes in the original editing DOM root.
+     *
+     * **Note**:The provided value should be the `offsetHeight` of the original editing DOM root.
+     */
+    setContentHeight(newHeight) {
+        this._minimapIframeView.setHeight(newHeight * this._scaleRatio);
+    }
+    /**
+     * Sets the minimap scroll progress.
+     *
+     * The minimap scroll progress is linked to the original editing DOM root and its scrollable container (ancestor).
+     * Changing the progress will alter the vertical position of the minimap (and its position tracker) and give the user an accurate
+     * overview of the visible document.
+     *
+     * **Note**: The value should be between 0 and 1. 0 when the DOM root has not been scrolled, 1 when the
+     * scrolling has reached the end.
+     */
+    setScrollProgress(newScrollProgress) {
+        const iframeView = this._minimapIframeView;
+        const positionTrackerView = this._positionTrackerView;
+        // The scrolling should end when the bottom edge of the iframe touches the bottom edge of the minimap.
+        if (iframeView.height < this.height) {
+            iframeView.setTopOffset(0);
+            positionTrackerView.setTopOffset((iframeView.height - positionTrackerView.height) * newScrollProgress);
+        }
+        else {
+            const totalOffset = iframeView.height - this.height;
+            iframeView.setTopOffset(-totalOffset * newScrollProgress);
+            positionTrackerView.setTopOffset((this.height - positionTrackerView.height) * newScrollProgress);
+        }
+        positionTrackerView.setScrollProgress(Math.round(newScrollProgress * 100));
+    }
+    /**
+     * Sets the new height of the tracker (in px) to visualize the subset of the content visible to the user.
+     */
+    setPositionTrackerHeight(trackerHeight) {
+        this._positionTrackerView.setHeight(trackerHeight * this._scaleRatio);
+    }
+    /**
+     * @param data DOM event data
+     */
+    _handleMinimapClick(data) {
+        const positionTrackerView = this._positionTrackerView;
+        if (data.target === positionTrackerView.element) {
+            return;
+        }
+        const trackerViewRect = new Rect(positionTrackerView.element);
+        const diff = data.clientY - trackerViewRect.top - trackerViewRect.height / 2;
+        const percentage = diff / this._minimapIframeView.height;
+        this.fire('click', percentage);
+    }
+    /**
+     * @param data DOM event data
+     */
+    _handleMinimapMouseWheel(data) {
+        this.fire('drag', data.deltaY * this._scaleRatio);
+    }
+}

package/src/utils.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @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/src/utils.js

@@ -0,0 +1,97 @@
+/**
+ * @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
+ */
+/* global CSSMediaRule */
+/**
+ * @module minimap/utils
+ */
+import { Rect, global } from 'ckeditor5/src/utils.js';
+import { DomConverter, Renderer } from 'ckeditor5/src/engine.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 function cloneEditingViewDomRoot(editor, rootName) {
+    const viewDocument = editor.editing.view.document;
+    const viewRoot = viewDocument.getRoot(rootName);
+    const domConverter = new DomConverter(viewDocument);
+    const renderer = new Renderer(domConverter, viewDocument.selection);
+    const domRootClone = editor.editing.view.getDomRoot().cloneNode();
+    domConverter.bindElements(domRootClone, viewRoot);
+    renderer.markToSync('children', viewRoot);
+    renderer.markToSync('attributes', viewRoot);
+    viewRoot.on('change:children', (evt, node) => renderer.markToSync('children', node));
+    viewRoot.on('change:attributes', (evt, node) => renderer.markToSync('attributes', node));
+    viewRoot.on('change:text', (evt, node) => renderer.markToSync('text', node));
+    renderer.render();
+    editor.editing.view.on('render', () => renderer.render());
+    // TODO: Cleanup after destruction.
+    editor.on('destroy', () => {
+        domConverter.unbindDomElement(domRootClone);
+    });
+    return domRootClone;
+}
+/**
+ * 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 function getPageStyles() {
+    return Array.from(global.document.styleSheets)
+        .map(styleSheet => {
+        // CORS
+        if (styleSheet.href && !styleSheet.href.startsWith(global.window.location.origin)) {
+            return { href: styleSheet.href };
+        }
+        return Array.from(styleSheet.cssRules)
+            .filter(rule => !(rule instanceof CSSMediaRule))
+            .map(rule => rule.cssText)
+            .join(' \n');
+    });
+}
+/**
+ * Gets dimensions rectangle according to passed DOM element. Returns whole window's size for `body` element.
+ *
+ * @internal
+ */
+export function getDomElementRect(domElement) {
+    return new Rect(domElement === global.document.body ? global.window : domElement);
+}
+/**
+ * Gets client height according to passed DOM element. Returns window's height for `body` element.
+ *
+ * @internal
+ */
+export function getClientHeight(domElement) {
+    return domElement === global.document.body ? global.window.innerHeight : domElement.clientHeight;
+}
+/**
+ * Returns the DOM element itself if it's not a `body` element, whole window otherwise.
+ *
+ * @internal
+ */
+export function getScrollable(domElement) {
+    return domElement === global.document.body ? global.window : domElement;
+}

package/theme/minimap.css

@@ -0,0 +1,80 @@
+/*
+ * 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
+ */
+
+:root {
+	--ck-color-minimap-tracker-background: 208, 0%, 51%;
+	--ck-color-minimap-iframe-outline: hsl(0deg 0% 75%);
+	--ck-color-minimap-iframe-shadow: hsl(0deg 0% 0% / 11%);
+	--ck-color-minimap-progress-background: hsl(0,0%,40%);
+}
+
+.ck.ck-minimap {
+	position: absolute;
+	user-select: none;
+	background: var(--ck-color-base-background);
+
+	&,
+	& iframe {
+		width: 100%;
+		height: 100%;
+	}
+
+	& iframe {
+		border: 0;
+		pointer-events: none;
+		position: relative;
+		outline: 1px solid var(--ck-color-minimap-iframe-outline);
+		box-shadow: 0 2px 5px var(--ck-color-minimap-iframe-shadow);
+		margin: 0;
+	}
+
+	& .ck.ck-minimap__position-tracker {
+		position: absolute;
+		width: 100%;
+		top: 0;
+		background: hsla( var(--ck-color-minimap-tracker-background), .2 );
+		z-index: 1;
+		transition: background 100ms ease-in-out;
+
+
+		@media (prefers-reduced-motion: reduce) {
+			transition: none;
+		}
+
+		&:hover {
+			background:hsla( var(--ck-color-minimap-tracker-background), .3 );
+		}
+
+		&.ck-minimap__position-tracker_dragging,
+		&.ck-minimap__position-tracker_dragging:hover {
+			background:hsla( var(--ck-color-minimap-tracker-background), .4 );
+
+			&::after {
+				opacity: 1;
+			}
+		}
+
+		&::after {
+			content: attr(data-progress) "%";
+			position: absolute;
+			top: 5px;
+			right: 5px;
+			background: var(--ck-color-minimap-progress-background);
+			color: var(--ck-color-base-background);
+			border: 1px solid var(--ck-color-base-background);
+			padding: 2px 4px;
+			font-size: 10px;
+			border-radius: 3px;
+			opacity: 0;
+			transition: opacity 100ms ease-in-out;
+
+
+			@media (prefers-reduced-motion: reduce) {
+				transition: none;
+			}
+		}
+	}
+}
+