@ckeditor/ckeditor5-track-changes 44.1.0-alpha.5 → 44.2.0-alpha.0

package/dist/suggestion.d.ts

@@ -1,295 +0,0 @@
-/**
- * @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-licensing-options
- */
-/**
- * @module track-changes/suggestion
- * @publicApi
- */
-import { Element, type Marker, type Model, type Range, type Item } from 'ckeditor5/src/engine.js';
-import type { User } from 'ckeditor5-collaboration/src/collaboration-core.js';
-import type { CommentThread } from '@ckeditor/ckeditor5-comments';
-import type { FormatData, AttributeData } from './trackchangesediting.js';
-declare const Suggestion_base: {
-    new (): import("ckeditor5/src/utils.js").Observable;
-    prototype: import("ckeditor5/src/utils.js").Observable;
-};
-/**
- * Represents a singular suggestion that is tracked by track changes plugin.
- *
- * `Suggestion` instances are created and handled by {@link module:track-changes/trackchanges~TrackChanges track changes plugin}.
- */
-export default class Suggestion extends /* #__PURE__ -- @preserve */ Suggestion_base {
-    /**
-     * Suggestion ID.
-     */
-    readonly id: string;
-    /**
-     * Suggestion type.
-     */
-    type: SuggestionType;
-    /**
-     * Suggestion sub-type.
-     *
-     * This is an additional identifier for suggestions. Two suggestions of the same type may have different sub-types to differentiate
-     * suggestions behavior and handle interactions between suggestions.
-     *
-     * Sub-type is used for:
-     *
-     *  * suggestions joining (only suggestions with the same sub-type can be joined),
-     *  * suggestions custom callbacks (fired when adding, deleting and joining suggestions).
-     */
-    subType: string | null;
-    /**
-     * The author of the change marked by the suggestion.
-     */
-    author: User;
-    /**
-     * The user which saved the suggestion data in the database.
-     *
-     * Usually the same as author but may be different in some cases (e.g. when suggestion was added from an external source).
-     */
-    creator: User;
-    /**
-     * The flag indicating whether the suggestion comes from an external source.
-     */
-    isExternal: boolean;
-    /**
-     * Additional suggestion data.
-     */
-    data: FormatData | AttributeData | null;
-    /**
-     * Date when the suggestion was saved in the database.
-     */
-    createdAt: Date | null;
-    /**
-     * Date when the change marked by the suggestion was made.
-     *
-     * Usually the same as {@link #createdAt `createdAt`} but may be different in some cases
-     * (e.g. when suggestion was added from an external source).
-     *
-     * @observable
-     */
-    authoredAt: Date | null;
-    /**
-     * Custom suggestion attributes. See also {@link #setAttribute} and {@link #removeAttribute}.
-     *
-     * @observable
-     */
-    attributes: {
-        [k: string]: unknown;
-    };
-    /**
-     * Previous suggestion in suggestions chain.
-     *
-     * Chained suggestions should be handled as one entity.
-     *
-     * @observable
-     */
-    previous: Suggestion | null;
-    /**
-     * Next suggestion in suggestions chain.
-     *
-     * Chained suggestions should be handled as one entity.
-     *
-     * @observable
-     */
-    next: Suggestion | null;
-    /**
-     * Comment thread model for comments added to this suggestion.
-     *
-     * @observable
-     */
-    commentThread: CommentThread | null;
-    constructor(model: Model, options: SuggestionOptions);
-    /**
-     * The first (most-previous) suggestion in this suggestion chain.
-     */
-    get head(): Suggestion;
-    /**
-     * Informs whether suggestion has at least one comment.
-     */
-    get hasComments(): boolean;
-    /**
-     * Informs whether the suggestion is a multi-range suggestion or a single-range suggestion.
-     *
-     * This is evaluated basing on the marker name belonging to this suggestion.
-     * Even if only one marker belongs to the suggestion at a given time it can still be a multi range suggestion.
-     */
-    get isMultiRange(): boolean;
-    /**
-     * Informs whether the suggestion is still in the editor content.
-     *
-     * Returns `true` if there is at least one marker suggestion in the editor content.
-     */
-    get isInContent(): boolean;
-    /**
-     * Binds given marker name to this suggestion.
-     */
-    addMarkerName(markerName: string): void;
-    /**
-     * Returns all names of markers belonging to this suggestion.
-     */
-    getMarkerNames(): Array<string>;
-    /**
-     * Returns all markers belonging to this suggestion.
-     */
-    getMarkers(): Array<Marker>;
-    /**
-     * Returns the first marker belonging to this suggestion, i.e the first marker that was added to this suggestion
-     * and not removed yet.
-     *
-     * This method is useful if you know that the suggestion has only one marker and want to process it.
-     */
-    getFirstMarker(): Marker | null;
-    /**
-     * Removes all markers from the suggestion and the editor content.
-     */
-    removeMarkers(): void;
-    /**
-     * Removes marker with the given name from the suggestion and the editor content.
-     */
-    removeMarker(markerName: string): void;
-    /**
-     * Adds a new range to this suggestion. It is assumed that the suggestion is a multi-range suggestion.
-     *
-     * A marker name is generated from this suggestion's properties and a marker with that name is created and set to a given `range`.
-     */
-    addRange(range: Range): void;
-    /**
-     * Checks if given `range` is intersecting with any of the ranges of markers belonging to this suggestion.
-     */
-    isIntersectingWithRange(range: Range): boolean;
-    /**
-     * Returns all ranges of all markers belonging to this suggestion.
-     */
-    getRanges(): Array<Range>;
-    /**
-     * Returns all {@link module:engine/model/item~Item model items} that are in this suggestion.
-     */
-    getItems(): Array<Item>;
-    /**
-     * Returns the first range belonging to this suggestion, i.e. the range of the first marker that was added to
-     * this suggestion and not removed yet.
-     *
-     * This method is useful if you know that the suggestion has only one marker and want to process its range.
-     */
-    getFirstRange(): Range | null;
-    /**
-     * Returns the model element contained in the suggestion.
-     *
-     * A {@link module:engine/model/element~Element model element} is considered as contained if there is exactly
-     * one range in the suggestion, and that range contains exactly one element.
-     *
-     * Returns `null` if there is no contained element.
-     */
-    getContainedElement(): Element | null;
-    /**
-     * Accepts the suggestion.
-     */
-    accept(): void;
-    /**
-     * Discards the suggestion.
-     */
-    discard(): void;
-    /**
-     * Returns all suggestions that are in this suggestion chain.
-     */
-    getAllAdjacentSuggestions(): Array<Suggestion>;
-    /**
-     * Adds suggestion attribute.
-     *
-     * Suggestion attributes are custom data that can be set and used by features
-     * built around suggestions. Use it to store your feature data with other suggestion data.
-     *
-     * ```ts
-     * suggestion.setAttribute( 'isImportant', true );
-     * ```
-     *
-     * You can group multiple values in an object, using dot notation:
-     *
-     * ```ts
-     * suggestion.setAttribute( 'customData.type', 'image' );
-     * suggestion.setAttribute( 'customData.src', 'foo.jpg' );
-     * ```
-     *
-     * Attributes set on the suggestion can be accessed through `attribute` property:
-     *
-     * ```ts
-     * const isImportant = suggestion.attributes.isImportant;
-     * const type = suggestion.attributes.customData.type;
-     * ```
-     *
-     * You can also observe `attributes` property or bind other properties to it:
-     *
-     * ```ts
-     * myObj.bind( 'customData' ).to( suggestion, 'attributes', attributes => attributes.customData );
-     * ```
-     *
-     * Whenever `setAttribute()` or `removeAttribute()` is called, `attributes` property
-     * is re-set and observables are refreshed.
-     */
-    setAttribute(name: string, value: unknown): void;
-    /**
-     * Removes suggestion attribute.
-     *
-     * See also {@link #setAttribute}
-     */
-    removeAttribute(name: string): void;
-    toJSON(): SuggestionJSON;
-    /**
-     * Returns a random string that can be used as additional identifier for the marker name for suggestions that are multi range.
-     */
-    static getMultiRangeId(): string;
-}
-export interface SuggestionOptions {
-    id: string;
-    type: SuggestionType;
-    subType: string | null;
-    attributes: {
-        [k: string]: unknown;
-    };
-    author: User;
-    creator: User;
-    onAccept: Function;
-    onDiscard: Function;
-    onAttributesChange: Function;
-}
-export interface SuggestionJSON {
-    /**
-     * Suggestion ID.
-     */
-    id: string;
-    /**
-     * Contains the information about the type and subtype of the suggestion.
-     */
-    type: string;
-    /**
-     * The ID of the author.
-     */
-    authorId: string;
-    /**
-     * Date when the suggestion was saved in the database.
-     */
-    createdAt: Date | null;
-    /**
-     * Informs whether suggestion has at least one comment.
-     */
-    hasComments?: boolean;
-    /**
-     * Additional suggestion data.
-     */
-    data?: FormatData | AttributeData | null;
-    /**
-     * Custom suggestion attributes.
-     */
-    attributes: {
-        [k: string]: unknown;
-    };
-}
-export type SuggestionType = 'insertion' | 'deletion' | 'formatInline' | 'formatBlock' | 'attribute';
-export {};

package/dist/suggestiondescriptionfactory.d.ts

@@ -1,187 +0,0 @@
-/**
- * @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-licensing-options
- */
-import { type Locale, type PriorityString } from 'ckeditor5/src/utils.js';
-import type { Schema, Element } from 'ckeditor5/src/engine.js';
-import type Suggestion from './suggestion.js';
-/**
- * Creates descriptions for suggestions and suggestions chains.
- *
- * The class manages everything related to generating descriptions for suggestions. Here, you register labels for elements,
- * attributes, or custom callback for non-regular cases.
- *
- * One or more suggestions that are grouped together (based ond various conditions) create "suggestion chain".
- * In such chain one suggestion may impact other suggestion when it comes to the description of the whole chain.
- * For example, insertion next to deletion results in "Replaced" description.
- */
-export default class SuggestionDescriptionFactory {
-    constructor(schema: Schema, locale: Locale);
-    /**
-     * Returns descriptions for given suggestion chain.
-     *
-     * The structure of the descriptions array is as follows (explained on an example):
-     *
-     * ```ts
-     * [
-     *	 { type: 'insertion', content: '*Insert:* 2 paragraphs' },
-     *	 { type: 'insertion', content: '*Insert:* image },
-     *	 { type: 'replace', content: '*Replace:* "Foo" *with* "Bar"' }
-     * ]
-     * ```
-     *
-     * In above example there are three description instances (or lines). Two new (empty) paragraphs were added,
-     * an image was added and then "Foo" text was removed and "Bar" text was added. For example, above structure could be rendered as:
-     *
-     * ```html
-     * <p><strong>Insert:</strong> 2 paragraphs</p>
-     * <p><strong>Insert:</strong> image</p>
-     * <p><strong>Replace:</strong> "Foo" <strong>with</strong> "Bar"</p>
-     * ```
-     */
-    getDescriptions(suggestions: Array<Suggestion>): Array<Description>;
-    /**
-     * Registers a callback function that returns a custom description for a suggestion.
-     *
-     * Registered callback is fired for a suggestion whenever there is a need to generate a description for that suggestion.
-     *
-     * The callback takes the suggestion instance as a parameter and should return
-     * {@link module:track-changes/suggestiondescriptionfactory~Description description object} or a falsy value
-     * if the suggestion was not handled by the callback.
-     *
-     * Example of a description callback for the bold style:
-     *
-     * ```ts
-     * suggestionDescriptionFactory.registerDescriptionCallback( suggestion => {
-     *		const { data } = suggestion;
-     *
-     *		// Omit suggestions that are not bold style suggestions.
-     *		if ( !data || data.commandName !== 'bold' ) {
-     *			return;
-     *		}
-     *
-     *		const isSet = !!data.commandParams[ 0 ].forceValue;
-     *		const content = isSet ? '*Set format:* bold' : '*Remove format:* bold';
-     *
-     *		return {
-     *			type: 'format',
-     *			content
-     *		};
-     *	} );
-     * ```
-     */
-    registerDescriptionCallback(callback: DescriptionCallback): void;
-    /**
-     * For given `elementName` registers how this element will be labeled in a description (for example when it is added
-     * or removed).
-     *
-     * Instead of a string name you may provide a matching function that takes item {@link module:engine/model/item~Item} as an input
-     * and should return boolean value.
-     *
-     * Provided label callback takes one parameter, `quantity`, and is expected to return the label for the element as a string.
-     *
-     * A simple use case without using internationalization:
-     *
-     * ```ts
-     * suggestionDescriptionFactory.registerElementLabel(
-     *		'paragraph',
-     *		quantity => quantity == 1 ? 'paragraph' : quantity + ' paragraphs'
-     * );
-     * ```
-     *
-     * If you want your feature to be localized to other languages, use localization service:
-     *
-     * ```ts
-     * const t = editor.locale.t; // Remember that you have to use function named `t`.
-     *
-     * suggestionDescriptionFactory.registerElementLabel(
-     *		'paragraph',
-     *		quantity => t( { string: 'paragraph', plural: '%0 paragraphs', id: 'ELEMENT_PARAGRAPH' }, quantity )
-     * );
-     * ```
-     */
-    registerElementLabel(elementNameOrCallback: string | Function, labelCallback: LabelCallback, priority?: PriorityString): void;
-    /**
-     * For given `attributeName` registers how this attribute will be labeled in a description (for example when it is added
-     * or removed).
-     *
-     * Example usage with internationalization:
-     *
-     * ```ts
-     * const t = editor.locale.t; // Remember that you have to use function named `t`.
-     *
-     * suggestionDescriptionFactory.registerAttributeLabel(
-     *		'bold',
-     *		t( 'bold' )
-     * );
-     * ```
-     */
-    registerAttributeLabel(attributeName: string, attributeLabel: string): void;
-    /**
-     * Returns label registered for given element or the element name if there is no label registered for it.
-     */
-    getItemLabel(element: Element, quantity?: number): string;
-}
-/**
- * A description for the suggestion.
- *
- * ```ts
- * {
- *		type: 'format',
- *		label: '*Set format:* bold'
- * }
- * ```
- *
- * A description for the color-related suggestions like font color may specify the `color` property that will provide a better UX
- * by displaying a color box next to the suggestion.
- *
- * ```ts
- * {
- * 		type: 'format',
- * 		label: '*Set font color:*',
- * 		color: {
- * 			value: 'hsl( 60, 60%, 60% )',
- * 			title: 'yellow'
- * 		}
- * }
- * ```
- */
-export interface Description {
-    type: 'insertion' | 'deletion' | 'replace' | 'format';
-    /**
-     * Description label. You may use `*` to bold part of the label.
-     */
-    content: string;
-    /**
-     * The optional `color` property used for color-related suggestions.
-     * The object should provide the `value` (for displaying the color) and `title` (for describing the color) fields.
-     */
-    color?: {
-        value: string;
-        title: string;
-    };
-}
-export type DescriptionCallback = (suggestion: Suggestion) => Description | DescriptionItem | undefined;
-export type LabelCallback = (quantity: number) => string;
-export interface LabelCallbackObject {
-    matchingCallback: (element: Element) => boolean;
-    label: LabelCallback;
-    priority: PriorityString;
-}
-/**
- * An intermediate state which is easier to operate on when consecutive suggestion
- * ranges are traversed.
- */
-interface DescriptionItem {
-    type: 'text' | 'addEmptyContainer' | 'addObject' | 'removeEmptyContainer' | 'removeObject' | 'addContainer' | 'removeContainer' | 'addFormat' | 'removeFormat';
-    add?: string;
-    remove?: string;
-    element?: Element;
-    quantity?: number;
-    key?: string;
-}
-export {};

package/dist/trackchanges.d.ts

@@ -1,192 +0,0 @@
-/**
- * @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-licensing-options
- */
-/**
- * @module track-changes/trackchanges
- * @publicApi
- */
-import { Plugin } from 'ckeditor5/src/core.js';
-import TrackChangesUI from './trackchangesui.js';
-import TrackChangesEditing from './trackchangesediting.js';
-import 'ckeditor5-collaboration/src/collaboration-core.js';
-import type { default as Suggestion, SuggestionJSON } from './suggestion.js';
-/**
- * A plugin that provides track changes mode for the editor. In track changes mode, all insertions are visually marked and all deletions
- * are not deleted but also visually marked. Unsupported commands are disabled when the editor is in the track changes mode.
- *
- * To learn how to integrate the track changes feature with your editor, refer to the
- * {@glink features/collaboration/track-changes/track-changes-integration Track changes integration} guide.
- *
- * Basic API:
- *
- * ```ts
- * // Get the track changes plugin:
- * const trackChangesPlugin = editor.plugins.get( 'TrackChanges' );
- *
- * // Add a suggestion:
- * trackChangesPlugin.addSuggestion( suggestionData );
- *
- * // Get all suggestions:
- * trackChangesPlugin.getSuggestions();
- *
- * // Set the adapter:
- * trackChangesPlugin.adapter = {
- * 		// ...
- * }
- * ```
- *
- * The plugin registers several commands:
- *
- * * `trackChanges` – Toggles the track changes mode in the editor.
- * * `acceptSuggestion` – Accepts a suggestion with the specified ID.
- * * `discardSuggestion` – Discards a suggestion with the specified ID.
- * * `acceptAllSuggestions` – Accepts all suggestions.
- * * `discardAllSuggestions` – Discards all suggestions.
- * * `acceptSelectedSuggestions` – Accepts all suggestions in the current selection.
- * * `discardSelectedSuggestions` – Discards all suggestions in the current selection.
- *
- * Examples:
- *
- * ```ts
- * editor.execute( 'trackChanges' );
- * editor.execute( 'acceptSuggestion', 'suggestion-1' );
- * editor.execute( 'discardSuggestion', 'suggestion-1' );
- * editor.execute( 'acceptAllSuggestions' );
- * editor.execute( 'discardAllSuggestions' );
- * editor.execute( 'acceptSelectedSuggestions' );
- * editor.execute( 'discardSelectedSuggestions' )
- * ```
- *
- * Note that there is no command to add a suggestion. This is because suggestions
- * are added automatically when editing commands are executed while the editor is in track
- * changes mode. For instance:
- *
- * ```ts
- * // Turn on the track changes mode:
- * editor.execute( 'trackChanges' );
- *
- * // Insert some text. It will be automatically inserted as a suggestion:
- * editor.execute( 'input', { text: 'foo' } );
- * ```
- */
-export default class TrackChanges extends Plugin {
-    static get requires(): readonly [typeof TrackChangesEditing, typeof TrackChangesUI, "Comments"];
-    static get pluginName(): "TrackChanges";
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin(): true;
-    /**
-     * @inheritDoc
-     */
-    static get isPremiumPlugin(): true;
-    /**
-     * An adapter object that should communicate with the data source to fetch or save the suggestion data.
-     *
-     * This is a shorthand to {@link module:track-changes/trackchangesediting~TrackChangesEditing#adapter `TrackChangesEditing#adapter`}.
-     */
-    set adapter(adapter: TrackChangesAdapter | null);
-    get adapter(): TrackChangesAdapter | null;
-    /**
-     * Adds suggestion data.
-     *
-     * Use this method to load the suggestion data during the editor initialization if you do not use the adapter integration.
-     */
-    addSuggestion(suggestionData: SuggestionData): Suggestion;
-    getSuggestions(options: {
-        skipNotAttached?: boolean;
-        toJSON: true;
-    }): Array<SuggestionJSON>;
-    getSuggestions(options?: {
-        skipNotAttached?: boolean;
-        toJSON?: false;
-    }): Array<Suggestion>;
-    getSuggestions(options: {
-        skipNotAttached?: boolean;
-        toJSON: boolean;
-    }): Array<Suggestion> | Array<SuggestionJSON>;
-    /**
-     * Returns the suggestion instance for a given ID.
-     */
-    getSuggestion(id: string): Suggestion;
-}
-/**
- * Track changes adapter.
- *
- * The track changes adapter is an object that communicates asynchronously with the data source to fetch or save the suggestion data.
- * It is used internally by the track changes feature whenever a suggestion is loaded, created or deleted.
- *
- * The adapter is optional. You might need to provide it if you are {@glink features/collaboration/track-changes/track-changes-integration}
- * using the track changes feature without real-time collaboration.
- *
- * To set the adapter, overwrite {@link module:track-changes/trackchanges~TrackChanges#adapter the `TrackChanges#adapter` property}.
- */
-export interface TrackChangesAdapter {
-    /**
-     * Called each time the suggestion data is needed.
-     *
-     * The method should return a promise that resolves with the suggestion data object.
-     *
-     * @param id The ID of the suggestion to get.
-     */
-    getSuggestion(id: string): Promise<SuggestionData>;
-    /**
-     * Called each time a new suggestion is created.
-     *
-     * The method should save the suggestion data in the database
-     * and return a promise that should be resolved when the save is
-     * completed.
-     *
-     * If the promise resolves with an object with the `createdAt` property,
-     * this suggestion property will be updated in the suggestion in the editor.
-     * This lets you update the suggestion data with server-side information.
-     *
-     * The `suggestionData` object does not expect the `authorId` property.
-     * For security reasons, the author of the suggestion should be set
-     * on the server side.
-     *
-     * If `suggestionData.originalSuggestionId` is set, the new suggestion should
-     * have the `authorId` property set to the same as the suggestion with
-     * `originalSuggestionId`. This happens when one user splits
-     * another user's suggestion, creating a new suggestion as a result. See
-     * {@glink features/collaboration/track-changes/track-changes-integration#implementation Track changes integration} guide.
-     *
-     * **Note:** Failure to properly handle this property will result in editor crash in some scenarios.
-     *
-     * In any other case, use the current (local) user to set `authorId`.
-     *
-     * The `suggestionData` object does not expect the `createdAt` property either.
-     * You should use the server-side time generator to ensure that all users
-     * see the same date.
-     *
-     * It is recommended to stringify `suggestionData.attributes` value to JSON and save it as a string in your database,
-     * and then to parse the strings when loading suggestions.
-     */
-    addSuggestion(suggestionData: AddSuggestionInput): Promise<SuggestionData>;
-    /**
-     * Called each time the suggestion properties change.
-     *
-     * The method should update the suggestion properties in the database
-     * and return a promise that should be resolved when the save is
-     * completed.
-     *
-     * Keep in mind that the `data` parameter only contains those
-     * properties of a suggestion which changed.
-     */
-    updateSuggestion(id: string, suggestionData: UpdateSuggestionInput): Promise<void>;
-}
-export interface SuggestionData extends SuggestionJSON {
-    /**
-     * Original suggestion ID from which the current one was split.
-     */
-    originalSuggestionId?: string | null;
-}
-export type AddSuggestionInput = Omit<SuggestionData, 'authorId' | 'createdAt'>;
-export type UpdateSuggestionInput = Partial<Pick<SuggestionJSON, 'hasComments' | 'attributes'>> & {
-    state?: 'open' | 'accepted' | 'rejected';
-};