@ckeditor/ckeditor5-editor-multi-root 0.0.0-internal-20241017.0

package/dist/multirooteditoruiview.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @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 editor-multi-root/multirooteditoruiview
+ */
+import { EditorUIView, InlineEditableUIView, MenuBarView, ToolbarView } from 'ckeditor5/src/ui.js';
+import type { Locale } from 'ckeditor5/src/utils.js';
+import type { EditingView } from 'ckeditor5/src/engine.js';
+/**
+ * The multi-root editor UI view. It is a virtual view providing an inline
+ * {@link module:editor-multi-root/multirooteditoruiview~MultiRootEditorUIView#editable} and a
+ * {@link module:editor-multi-root/multirooteditoruiview~MultiRootEditorUIView#toolbar}, but without any
+ * specific arrangement of the components in the DOM.
+ *
+ * See {@link module:editor-multi-root/multirooteditor~MultiRootEditor.create `MultiRootEditor.create()`}
+ * to learn more about this view.
+ */
+export default class MultiRootEditorUIView extends EditorUIView {
+    /**
+     * The main toolbar of the multi-root editor UI.
+     */
+    readonly toolbar: ToolbarView;
+    /**
+     * Editable elements used by the multi-root editor UI.
+     */
+    readonly editables: Record<string, InlineEditableUIView>;
+    readonly editable: InlineEditableUIView;
+    /**
+     * Menu bar view instance.
+     */
+    menuBarView: MenuBarView;
+    /**
+     * The editing view instance this view is related to.
+     */
+    private readonly _editingView;
+    /**
+     * Creates an instance of the multi-root editor UI view.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param editingView The editing view instance this view is related to.
+     * @param editableNames Names for all editable views. For each name, one
+     * {@link module:ui/editableui/inline/inlineeditableuiview~InlineEditableUIView `InlineEditableUIView`} instance will be initialized.
+     * @param options Configuration options for the view instance.
+     * @param options.editableElements The editable elements to be used, assigned to their names. If not specified, they will be
+     * automatically created by {@link module:ui/editableui/inline/inlineeditableuiview~InlineEditableUIView `InlineEditableUIView`}
+     * instances.
+     * @param options.shouldToolbarGroupWhenFull When set to `true` enables automatic items grouping
+     * in the main {@link module:editor-multi-root/multirooteditoruiview~MultiRootEditorUIView#toolbar toolbar}.
+     * See {@link module:ui/toolbar/toolbarview~ToolbarOptions#shouldGroupWhenFull} to learn more.
+     * @param options.label When set, this value will be used as an accessible `aria-label` of the
+     * {@link module:ui/editableui/editableuiview~EditableUIView editable view} elements.
+     */
+    constructor(locale: Locale, editingView: EditingView, editableNames: Array<string>, options?: {
+        editableElements?: Record<string, HTMLElement>;
+        shouldToolbarGroupWhenFull?: boolean;
+        label?: string | Record<string, string>;
+    });
+    /**
+     * Creates an editable instance with given name and registers it in the editor UI view.
+     *
+     * If `editableElement` is provided, the editable instance will be created on top of it. Otherwise, the editor will create a new
+     * DOM element and use it instead.
+     *
+     * @param editableName The name for the editable.
+     * @param editableElement DOM element for which the editable should be created.
+     * @param label The accessible editable label used by assistive technologies.
+     * @returns The created editable instance.
+     */
+    createEditable(editableName: string, editableElement?: HTMLElement, label?: string): InlineEditableUIView;
+    /**
+     * Destroys and removes the editable from the editor UI view.
+     *
+     * @param editableName The name of the editable that should be removed.
+     */
+    removeEditable(editableName: string): void;
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ckeditor/ckeditor5-editor-multi-root",
+  "version": "0.0.0-internal-20241017.0",
+  "description": "Multi-root editor implementation for CKEditor 5.",
+  "keywords": [
+    "ckeditor",
+    "ckeditor5",
+    "ckeditor 5",
+    "ckeditor5-editor",
+    "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",
+    "lodash-es": "4.17.21"
+  },
+  "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-editor-multi-root"
+  },
+  "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,90 @@
+/**
+ * @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 RootAttributes } from './multirooteditor.js';
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * Initial roots attributes for the document roots.
+         *
+         * **Note: This configuration option is supported only by the
+         * {@link module:editor-multi-root/multirooteditor~MultiRootEditor multi-root} editor type.**
+         *
+         * **Note: You must provide full set of attributes for each root. If an attribute is not set on a root, set the value to `null`.
+         * Only provided attribute keys will be returned by
+         * {@link module:editor-multi-root/multirooteditor~MultiRootEditor#getRootsAttributes}.**
+         *
+         * Roots attributes hold additional data related to the document roots, in addition to the regular document data (which usually is
+         * HTML). In roots attributes, for each root, you can store arbitrary key-value pairs with attributes connected with that root.
+         * Use it to store any custom data that is specific to your integration or custom features.
+         *
+         * Currently, roots attributes are not used only by any official plugins. This is a mechanism that is prepared for custom features
+         * and non-standard integrations. If you do not provide any custom feature that would use root attributes, you do not need to
+         * handle (save and load) this property.
+         *
+         * ```ts
+         * MultiRootEditor.create(
+         * 	// Roots for the editor:
+         * 	{
+         * 		uid1: document.querySelector( '#uid1' ),
+         * 		uid2: document.querySelector( '#uid2' ),
+         * 		uid3: document.querySelector( '#uid3' ),
+         * 		uid4: document.querySelector( '#uid4' )
+         * 	},
+         * 	// Config:
+         * 	{
+         * 		rootsAttributes: {
+         * 			uid1: { order: 20, isLocked: false }, // Third, unlocked.
+         * 			uid2: { order: 10, isLocked: true }, // Second, locked.
+         * 			uid3: { order: 30, isLocked: true }, // Fourth, locked.
+         * 			uid4: { order: 0, isLocked: false } // First, unlocked.
+         * 		}
+         * 	}
+         * )
+         * .then( ... )
+         * .catch( ... );
+         * ```
+         *
+         * Note, that the above code snippet is only an example. You need to implement your own features that will use these attributes.
+         *
+         * Roots attributes can be changed the same way as attributes set on other model nodes:
+         *
+         * ```ts
+         * editor.model.change( writer => {
+         * 	const root = editor.model.getRoot( 'uid3' );
+         *
+         * 	writer.setAttribute( 'order', 40, root );
+         * } );
+         * ```
+         *
+         * You can react to root attributes changes by listening to
+         * {@link module:engine/model/document~Document#event:change:data document `change:data` event}:
+         *
+         * ```ts
+         * editor.model.document.on( 'change:data', () => {
+         * 	const changedRoots = editor.model.document.differ.getChangedRoots();
+         *
+         * 	for ( const change of changedRoots ) {
+         * 		if ( change.attributes ) {
+         * 			const root = editor.model.getRoot( change.name );
+         *
+         * 			// ...
+         * 		}
+         * 	}
+         * } );
+         * ```
+         */
+        rootsAttributes?: Record<string, RootAttributes>;
+        /**
+         * A list of names of all the roots that exist in the document but are not initially loaded by the editor.
+         *
+         * These roots can be loaded at any time after the editor has been initialized, using
+         * {@link module:editor-multi-root/multirooteditor~MultiRootEditor#loadRoot `MultiRootEditor#lazyRoot()`}.
+         *
+         * This is useful for handling big documents that contain hundreds of roots, or contain very large roots, which may have
+         * impact editor performance if loaded all at once.
+         */
+        lazyRoots?: Array<string>;
+    }
+}

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 editor-multi-root
+ */
+export { default as MultiRootEditor } from './multirooteditor.js';
+export type { RootAttributes, AddRootEvent, DetachRootEvent } from './multirooteditor.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 editor-multi-root
+ */
+export { default as MultiRootEditor } from './multirooteditor.js';
+import './augmentation.js';