@ckeditor/ckeditor5-document-outline 0.0.0-internal-20241017.0

package/dist/documentoutline/documentoutlineui.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @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 document-outline/documentoutline/documentoutlineui
+ * @publicApi
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import DocumentOutlineView from './ui/documentoutlineview.js';
+import '../../theme/documentoutline.css';
+/**
+ * Provides the UI for the document outline feature.
+ */
+export default class DocumentOutlineUI extends Plugin {
+    /**
+     * The representation of the document outline view.
+     */
+    view: DocumentOutlineView;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "DocumentOutlineUI";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    static get isPremiumPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}

package/dist/documentoutline/documentoutlineutils.d.ts

@@ -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
+ */
+/**
+ * @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 document-outline/documentoutline/documentoutlineutils
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { type Element } from 'ckeditor5/src/engine.js';
+import { diffToChanges } from 'ckeditor5/src/utils.js';
+/**
+ * Document outline utilities.
+ */
+export default class DocumentOutlineUtils extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "DocumentOutlineUtils";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    static get isPremiumPlugin(): true;
+    /**
+     * Starts listening for editor events and handles them on the model document `change` event. This means both
+     * changes to the structure of the document and changes to the selection are reflected in the outline.
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+}
+/**
+ * The definition of the item in the document outline.
+ */
+export type OutlineItemDefinition = {
+    level: number;
+    text: string;
+    modelElement: Element;
+};
+/**
+ * Fired whenever the headings structure in the document changes.
+ *
+ * @eventName ~DocumentOutlineUtils#change
+ * @param outlineDefinitions The list of current outline definitions.
+ * @param outlineChanges Describes what changes were applied in the headings structure.
+ * @param activeItemIndex The index of the active document outline item.
+ */
+export type OutlineChangeEvent = {
+    name: 'change';
+    args: [
+        {
+            outlineDefinitions: Array<OutlineItemDefinition>;
+            outlineChanges: ReturnType<typeof diffToChanges<OutlineItemDefinition>>;
+            activeItemIndex: number;
+        }
+    ];
+};
+/**
+ * Fired whenever the active document outline item is changed.
+ *
+ * @eventName ~DocumentOutlineUtils#activeItemIndex
+ * @param activeItemIndex The index of the active document outline item.
+ */
+export type ActiveOutlineItemChangeEvent = {
+    name: 'activeItemIndex';
+    args: [{
+        index: number;
+    }];
+};

package/dist/documentoutline/ui/documentoutlineitemview.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @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 document-outline/documentoutline/ui/documentoutlineitemview
+ */
+import { View } from 'ckeditor5/src/ui.js';
+import { type Locale } from 'ckeditor5/src/utils.js';
+/**
+ * An item of the document outline.
+ */
+export default class DocumentOutlineItemView extends View {
+    /**
+     * The textual content of the item.
+     *
+     * @observable
+     */
+    text: string;
+    /**
+     * The level of heading nesting in the document.
+     *
+     * @observable
+     */
+    level: number;
+    /**
+     * Indicates whether the given item is currently active.
+     *
+     * @observable
+     */
+    isActive: boolean;
+    /**
+     * Indicates whether the heading doesn't have any text.
+     *
+     * @observable
+     */
+    isEmpty: boolean;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, showEmptyHeadingText?: boolean);
+}
+/**
+ * Fired whenever an item in the document outline is clicked.
+ *
+ * @eventName ~DocumentOutlineItemView#click
+ */
+export type DocumentOutlineItemViewClickEvent = {
+    name: 'click';
+    args: [];
+};

package/dist/documentoutline/ui/documentoutlineview.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @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 document-outline/documentoutline/ui/documentoutlineview
+ */
+import { View, type ViewCollection } from 'ckeditor5/src/ui.js';
+import { type Locale, type diffToChanges } from 'ckeditor5/src/utils.js';
+import type { OutlineItemDefinition } from '../documentoutlineutils.js';
+import DocumentOutlineItemView from './documentoutlineitemview.js';
+/**
+ * The document outline panel.
+ */
+export default class DocumentOutlineView extends View {
+    /**
+     * A collection of document outline items.
+     */
+    readonly items: ViewCollection<DocumentOutlineItemView>;
+    /**
+     * Indicates which item is active at the moment.
+     *
+     * @observable
+     */
+    activeItemIndex: number;
+    /**
+     * Creates an instance of the {@link module:documentoutline/ui/documentoutlineview~DocumentOutlineView} class.
+     *
+     * @param locale The localization services instance.
+     * @param showEmptyHeadingText Indicates whether the display of a placeholder for empty heading is enabled in the editor.
+     * @param containerElement The element that contains the document outline.
+     */
+    constructor(locale: Locale, showEmptyHeadingText?: boolean, containerElement?: HTMLElement);
+    /**
+     * If a heading was added or deleted in the editor, insert or delete it in the document outline.
+     */
+    sync(changesInItems: ReturnType<typeof diffToChanges<OutlineItemDefinition>>): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}
+/**
+ * Fired whenever an item in the document outline is clicked.
+ *
+ * @eventName ~DocumentOutlineView#itemSelected
+ * @param itemIndex Index of selected item.
+ */
+export type DocumentOutlineViewItemSelectedEvent = {
+    name: 'itemSelected';
+    args: [itemIndex: number];
+};

package/dist/documentoutline/utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @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 document-outline/documentoutline/utils
+ */
+import { type Element } from 'ckeditor5/src/engine.js';
+import { type Editor } from 'ckeditor5/src/core.js';
+/**
+ * Returns all text contents that are inside the given element and all its children.
+ */
+export declare function getElementText(element: Element): string;
+/**
+ * Returns a list of standard headings or GHS headings configured in the editor.
+ */
+export declare function getDefaultFeatureHeadingNames(editor: Editor): Array<string>;

package/dist/documentoutline.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @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 document-outline/documentoutline
+ * @publicApi
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import DocumentOutlineUtils from './documentoutline/documentoutlineutils.js';
+import DocumentOutlineUI from './documentoutline/documentoutlineui.js';
+/**
+ * The document outline feature.
+ * It allows for an easy access to a predefined list of headings in the document.
+ */
+export default class DocumentOutline extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof DocumentOutlineUtils, typeof DocumentOutlineUI];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "DocumentOutline";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    static get isPremiumPlugin(): true;
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}
+/**
+ * The configuration of the {@link module:document-outline/documentoutline~DocumentOutline document outline feature}.
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( editorElement, {
+ * 		documentOutline:  ... // Document outline feature configuration.
+ * 	} )
+ * 	.then( /* ... *\/ )
+ * 	.catch( /* ... *\/ );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface DocumentOutlineConfig {
+    /**
+     * The container element for the document outline to render. This should be a reference to an existing
+     * container element in the DOM.
+     */
+    container?: HTMLElement;
+    /**
+     * An array of {@glink framework/architecture/editing-engine#model model} element names considered
+     * as headings in the document outline.
+     *
+     * The index of the heading in the array reflects the heading nesting level. It can be used e.g. for reducing
+     * the number of visible headings.
+     *
+     * ```ts
+     * ClassicEditor
+     * 	.create( editorElement, {
+     * 		plugins: [ DocumentOutline, /* ... *\/ ],
+     * 		documentOutline: {
+     * 			headings: [ 'heading1', 'heading2', /* ... *\/ ],
+     * 			// ...
+     * 		}
+     * 	} )
+     * 	.then( /* ... *\/ )
+     * 	.catch( /* ... *\/ );
+     * ```
+     *
+     * If this configuration is not defined, the feature will use the following defaults instead:
+     *
+     * 1. If the {@glink features/headings Headings feature} is loaded, it equals
+     * * {@link module:heading/headingconfig~HeadingConfig#options `config.heading.options`}.
+     * * `[ 'heading1', 'heading2', 'heading3' ]` if `config.heading.options` is not defined.
+     * 2. If the {@glink features/html/general-html-support General HTML Support} feature is loaded, it equals
+     * `[ 'htmlH1', 'htmlH2', 'htmlH3', 'htmlH4', 'htmlH5', 'htmlH6' ]`.
+     *
+     * **Note**: The Headings feature takes precedence over the General HTML Support feature when
+     * both are loaded.
+     */
+    headings?: Array<string>;
+    /**
+     * Allows you to display a placeholder text: [Empty heading] for empty headings.
+     *
+     * By default, the display of a placeholder is disabled. To enable it, set this parameter to true.
+     *
+     * **Note**: This setting also affects Table of contents feature.
+     */
+    showEmptyHeadings?: boolean;
+}

package/dist/index-content.css

@@ -0,0 +1,44 @@
+/**
+ * @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
+ */
+:root{
+	--ck-table-of-contents-padding:1em;
+	--ck-table-of-contents-line-height:1.5;
+	--ck-table-of-contents-items-start-padding:24px;
+}
+
+.ck-content .table-of-contents{
+		margin:0.9em auto;
+	}
+
+.ck-content .table-of-contents.table-of-contents_empty{
+			display:none;
+		}
+
+.ck-content .table-of-contents .table-of-contents__placeholder{
+			margin:0;
+			padding:var(--ck-table-of-contents-padding);
+			font-style:italic;
+		}
+
+.ck-content .table-of-contents > ol{
+			padding:var(--ck-table-of-contents-padding);
+		}
+
+.ck-content .table-of-contents ol{
+			margin:0;
+			line-height:var(--ck-table-of-contents-line-height);
+			list-style-type:none;
+		}
+
+.ck-content .table-of-contents ol ol{
+				padding-inline-start:var(--ck-table-of-contents-items-start-padding);
+			}
+
+.ck-content .table-of-contents ol li{
+				white-space:nowrap;
+				text-overflow:ellipsis;
+				overflow:hidden;
+				cursor:default;
+			}

package/dist/index-editor.css

@@ -0,0 +1,147 @@
+/**
+ * @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
+ */
+:root{
+	--ck-document-outline-padding:var(--ck-spacing-large);
+	--ck-document-outline-base-font-size:.875em;
+	--ck-document-outline-placeholder-color:var(--ck-color-engine-placeholder-text);
+
+	--ck-document-outline-indent-level-1:0;
+	--ck-document-outline-indent-level-2:1.5em;
+	--ck-document-outline-indent-level-3:3em;
+	--ck-document-outline-indent-level-4:4.5em;
+	--ck-document-outline-indent-level-5:6em;
+	--ck-document-outline-indent-level-6:7.5em;
+
+	--ck-document-outline-item-padding:var(--ck-spacing-small);
+	--ck-document-outline-item-active-color:var(--ck-color-base-active);
+	--ck-document-outline-item-default-color:hsl(0, 0%, 26%);
+	--ck-document-outline-item-hover-state-color:var(--ck-color-base-text);
+}
+
+.ck.ck-document-outline{
+	padding:var(--ck-document-outline-padding);
+	font-size:var(--ck-document-outline-base-font-size);
+	user-select:none;
+}
+
+.ck.ck-document-outline:empty::before{
+		content:attr(data-document-outline-empty-placeholder);
+		display:inline-block;
+		color:var(--ck-document-outline-placeholder-color);
+	}
+
+.ck.ck-document-outline .ck-document-outline__item{
+		padding:var(--ck-document-outline-item-padding);
+		color:var(--ck-document-outline-item-default-color);
+		white-space:nowrap;
+		text-overflow:ellipsis;
+		overflow:hidden;
+		cursor:pointer;
+	}
+
+.ck.ck-document-outline .ck-document-outline__item.ck-document-outline__item_empty{
+			font-style:italic;
+		}
+
+.ck.ck-document-outline .ck-document-outline__item.ck-document-outline__item_empty:hover,
+		.ck.ck-document-outline .ck-document-outline__item:hover{
+			color:var(--ck-document-outline-item-hover-state-color);
+			text-decoration:underline;
+		}
+
+.ck.ck-document-outline .ck-document-outline__item.ck-document-outline__item_active{
+			color:var(--ck-document-outline-item-active-color);
+		}
+
+.ck.ck-document-outline .ck-document-outline__item.ck-document-outline__item_level-1{
+			font-size:1.1em;
+			font-weight:bold;
+		}
+
+.ck.ck-document-outline[dir="ltr"] .ck-document-outline__item.ck-document-outline__item_level-1{
+		padding-left:var(--ck-document-outline-indent-level-1);
+	}
+
+.ck.ck-document-outline[dir="ltr"] .ck-document-outline__item.ck-document-outline__item_level-2{
+		padding-left:var(--ck-document-outline-indent-level-2);
+	}
+
+.ck.ck-document-outline[dir="ltr"] .ck-document-outline__item.ck-document-outline__item_level-3{
+		padding-left:var(--ck-document-outline-indent-level-3);
+	}
+
+.ck.ck-document-outline[dir="ltr"] .ck-document-outline__item.ck-document-outline__item_level-4{
+		padding-left:var(--ck-document-outline-indent-level-4);
+	}
+
+.ck.ck-document-outline[dir="ltr"] .ck-document-outline__item.ck-document-outline__item_level-5{
+		padding-left:var(--ck-document-outline-indent-level-5);
+	}
+
+.ck.ck-document-outline[dir="ltr"] .ck-document-outline__item.ck-document-outline__item_level-6{
+		padding-left:var(--ck-document-outline-indent-level-6);
+	}
+
+.ck.ck-document-outline[dir="rtl"] .ck-document-outline__item.ck-document-outline__item_level-1{
+		padding-right:var(--ck-document-outline-indent-level-1);
+	}
+
+.ck.ck-document-outline[dir="rtl"] .ck-document-outline__item.ck-document-outline__item_level-2{
+		padding-right:var(--ck-document-outline-indent-level-2);
+	}
+
+.ck.ck-document-outline[dir="rtl"] .ck-document-outline__item.ck-document-outline__item_level-3{
+		padding-right:var(--ck-document-outline-indent-level-3);
+	}
+
+.ck.ck-document-outline[dir="rtl"] .ck-document-outline__item.ck-document-outline__item_level-4{
+		padding-right:var(--ck-document-outline-indent-level-4);
+	}
+
+.ck.ck-document-outline[dir="rtl"] .ck-document-outline__item.ck-document-outline__item_level-5{
+		padding-right:var(--ck-document-outline-indent-level-5);
+	}
+
+.ck.ck-document-outline[dir="rtl"] .ck-document-outline__item.ck-document-outline__item_level-6{
+		padding-right:var(--ck-document-outline-indent-level-6);
+	}
+
+:root{
+	--ck-table-of-contents-padding:1em;
+	--ck-table-of-contents-line-height:1.5;
+	--ck-table-of-contents-items-start-padding:24px;
+	--ck-table-of-contents-border-color:var(--ck-color-base-border);
+	--ck-table-of-contents-label-background-color:hsl(0, 0%, 46%);
+	--ck-table-of-contents-background-color:var(--ck-color-base-foreground);
+}
+
+.ck-editor__editable .ck-widget.table-of-contents{
+	position:relative;
+	background-color:var(--ck-table-of-contents-background-color);
+	border:1px solid var(--ck-table-of-contents-border-color);
+	display:flow-root;
+	min-width:15em;
+}
+
+.ck-editor__editable .ck-widget.table-of-contents[data-table-of-contents-label]::after{
+		content:attr(data-table-of-contents-label);
+
+		position:absolute;
+		top:-1px;
+		right:10px;
+		padding:var(--ck-spacing-tiny) var(--ck-spacing-medium);
+		background-color:var(--ck-table-of-contents-label-background-color);
+
+		font-size:10px;
+		font-family:var(--ck-font-face);
+		line-height:16px;
+		color:hsl(0, 0%, 100%);
+		white-space:nowrap;
+	}
+
+[dir="rtl"] .ck-editor__editable .ck-widget.table-of-contents[data-table-of-contents-label]::after{
+			left:10px;
+			right:auto;
+	}