@ckeditor/ckeditor5-minimap 36.0.1 → 37.0.0-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-minimap",
-  "version": "36.0.1",
+  "version": "37.0.0-alpha.1",
   "description": "Content minimap feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -12,23 +12,23 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "ckeditor5": "^36.0.1"
+    "ckeditor5": "^37.0.0-alpha.1"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-alignment": "^36.0.1",
-    "@ckeditor/ckeditor5-basic-styles": "^36.0.1",
-    "@ckeditor/ckeditor5-cloud-services": "^36.0.1",
-    "@ckeditor/ckeditor5-code-block": "^36.0.1",
-    "@ckeditor/ckeditor5-core": "^36.0.1",
-    "@ckeditor/ckeditor5-dev-utils": "^32.0.0",
-    "@ckeditor/ckeditor5-easy-image": "^36.0.1",
-    "@ckeditor/ckeditor5-editor-decoupled": "^36.0.1",
-    "@ckeditor/ckeditor5-font": "^36.0.1",
-    "@ckeditor/ckeditor5-image": "^36.0.1",
-    "@ckeditor/ckeditor5-indent": "^36.0.1",
-    "@ckeditor/ckeditor5-page-break": "^36.0.1",
-    "@ckeditor/ckeditor5-table": "^36.0.1",
-    "@ckeditor/ckeditor5-theme-lark": "^36.0.1",
+    "@ckeditor/ckeditor5-alignment": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-basic-styles": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-cloud-services": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-code-block": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-core": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-dev-utils": "^35.0.0",
+    "@ckeditor/ckeditor5-easy-image": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-editor-decoupled": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-font": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-image": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-indent": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-page-break": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-table": "^37.0.0-alpha.1",
+    "@ckeditor/ckeditor5-theme-lark": "^37.0.0-alpha.1",
     "typescript": "^4.8.4",
     "webpack": "^5.58.1",
     "webpack-cli": "^4.9.0"
@@ -57,7 +57,8 @@
   ],
   "scripts": {
     "dll:build": "webpack",
-    "build": "tsc -p ./tsconfig.release.json",
+    "build": "tsc -p ./tsconfig.json",
     "postversion": "npm run build"
-  }
+  },
+  "types": "src/index.d.ts"
 }

package/src/augmentation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+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-2023, 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-2023, 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';
+export type { MinimapConfig } from './minimapconfig';
+import './augmentation';

package/src/index.js

@@ -6,3 +6,4 @@
  * @module minimap
  */
 export { default as Minimap } from './minimap';
+import './augmentation';

package/src/minimap.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import '../theme/minimap.css';
+/**
+ * The content minimap feature.
+ */
+export default class Minimap extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'Minimap';
+    /**
+     * 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/minimapconfig.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @license Copyright (c) 2003-2023, 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-2023, 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-2023, 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';
+import { type Locale } from 'ckeditor5/src/utils';
+import type { MinimapViewOptions } from './minimapview';
+/**
+ * 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/minimappositiontrackerview.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import { type Locale } from 'ckeditor5/src/utils';
+/**
+ * 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/minimapview.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import { type Locale } from 'ckeditor5/src/utils';
+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/utils.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import type { Editor } from 'ckeditor5/src/core';
+/**
+ * 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;