| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465 |
- /**
- * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
- * For licensing, see LICENSE.md.
- */
- /**
- * @module engine/model/document
- */
- // Load all basic deltas and transformations, they register themselves.
- import './delta/basic-deltas';
- import './delta/basic-transformations';
- import Range from './range';
- import Position from './position';
- import RootElement from './rootelement';
- import History from './history';
- import DocumentSelection from './documentselection';
- import TreeWalker from './treewalker';
- import deltaTransform from './delta/transform';
- import clone from '@ckeditor/ckeditor5-utils/src/lib/lodash/clone';
- import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
- import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
- import mix from '@ckeditor/ckeditor5-utils/src/mix';
- import { isInsideSurrogatePair, isInsideCombinedSymbol } from '@ckeditor/ckeditor5-utils/src/unicode';
- const graveyardName = '$graveyard';
- /**
- * Document tree model describes all editable data in the editor. It may contain multiple
- * {@link module:engine/model/document~Document#roots root elements}, for example if the editor have multiple editable areas,
- * each area will be represented by the separate root.
- *
- * All changes in the document are done by {@link module:engine/model/operation/operation~Operation operations}. To create operations in
- * a simple way, use the {@link module:engine/model/batch~Batch} API, for example:
- *
- * const batch = doc.batch();
- * batch.insert( node, position );
- * batch.split( otherPosition );
- *
- * @see module:engine/model/document~Document#batch
- * @mixes module:utils/emittermixin~EmitterMixin
- */
- export default class Document {
- /**
- * Creates an empty document instance with no {@link #roots} (other than
- * the {@link #graveyard graveyard root}).
- */
- constructor( model ) {
- this.model = model;
- /**
- * Document version. It starts from `0` and every operation increases the version number. It is used to ensure that
- * operations are applied on the proper document version.
- * If the {@link module:engine/model/operation/operation~Operation#baseVersion} will not match document version the
- * {@link module:utils/ckeditorerror~CKEditorError model-document-applyOperation-wrong-version} error is thrown.
- *
- * @readonly
- * @member {Number}
- */
- this.version = 0;
- /**
- * Document's history.
- *
- * **Note:** Be aware that deltas applied to the document might get removed or changed.
- *
- * @readonly
- * @member {module:engine/model/history~History}
- */
- this.history = new History( this );
- /**
- * Selection done on this document.
- *
- * @readonly
- * @member {module:engine/model/documentselection~DocumentSelection}
- */
- this.selection = new DocumentSelection( this, this.model );
- /**
- * List of roots that are owned and managed by this document. Use {@link #createRoot} and
- * {@link #getRoot} to manipulate it.
- *
- * @readonly
- * @member {Map}
- */
- this.roots = new Map();
- // Add events that will ensure selection correctness.
- this.selection.on( 'change:range', () => {
- for ( const range of this.selection.getRanges() ) {
- if ( !this._validateSelectionRange( range ) ) {
- /**
- * Range from {@link module:engine/model/documentselection~DocumentSelection document selection}
- * starts or ends at incorrect position.
- *
- * @error document-selection-wrong-position
- * @param {module:engine/model/range~Range} range
- */
- throw new CKEditorError( 'document-selection-wrong-position: ' +
- 'Range from document selection starts or ends at incorrect position.', { range } );
- }
- }
- } );
- // Graveyard tree root. Document always have a graveyard root, which stores removed nodes.
- this.createRoot( '$root', graveyardName );
- this.listenTo( model, 'applyOperation', ( evt, args ) => {
- const operation = args[ 0 ];
- if ( operation.isDocumentOperation && operation.baseVersion !== this.version ) {
- /**
- * Only operations with matching versions can be applied.
- *
- * @error document-applyOperation-wrong-version
- * @param {module:engine/model/operation/operation~Operation} operation
- */
- throw new CKEditorError(
- 'model-document-applyOperation-wrong-version: Only operations with matching versions can be applied.',
- { operation } );
- }
- }, { priority: 'high' } );
- this.listenTo( model, 'applyOperation', ( evt, args ) => {
- const operation = args[ 0 ];
- if ( operation.isDocumentOperation ) {
- this.version++;
- this.history.addDelta( operation.delta );
- this.fire( 'change', operation.type, evt.return, operation.delta.batch, operation.delta.type );
- }
- }, { priority: 'low' } );
- // Temporary compatibility.
- model.delegate( 'changesDone' ).to( this );
- }
- /**
- * Graveyard tree root. Document always have a graveyard root, which stores removed nodes.
- *
- * @readonly
- * @member {module:engine/model/rootelement~RootElement}
- */
- get graveyard() {
- return this.getRoot( graveyardName );
- }
- /**
- * Creates a new top-level root.
- *
- * @param {String} [elementName='$root'] Element name. Defaults to `'$root'` which also have
- * some basic schema defined (`$block`s are allowed inside the `$root`). Make sure to define a proper
- * schema if you use a different name.
- * @param {String} [rootName='main'] Unique root name.
- * @returns {module:engine/model/rootelement~RootElement} Created root.
- */
- createRoot( elementName = '$root', rootName = 'main' ) {
- if ( this.roots.has( rootName ) ) {
- /**
- * Root with specified name already exists.
- *
- * @error model-document-createRoot-name-exists
- * @param {module:engine/model/document~Document} doc
- * @param {String} name
- */
- throw new CKEditorError(
- 'model-document-createRoot-name-exists: Root with specified name already exists.',
- { name: rootName }
- );
- }
- const root = new RootElement( this, elementName, rootName );
- this.roots.set( rootName, root );
- return root;
- }
- /**
- * Removes all events listeners set by document instance.
- */
- destroy() {
- this.selection.destroy();
- this.stopListening();
- }
- /**
- * Returns top-level root by its name.
- *
- * @param {String} [name='main'] Unique root name.
- * @returns {module:engine/model/rootelement~RootElement} Root registered under given name.
- */
- getRoot( name = 'main' ) {
- if ( !this.roots.has( name ) ) {
- /**
- * Root with specified name does not exist.
- *
- * @error model-document-getRoot-root-not-exist
- * @param {String} name
- */
- throw new CKEditorError(
- 'model-document-getRoot-root-not-exist: Root with specified name does not exist.',
- { name }
- );
- }
- return this.roots.get( name );
- }
- /**
- * Checks if root with given name is defined.
- *
- * @param {String} name Name of root to check.
- * @returns {Boolean}
- */
- hasRoot( name ) {
- return this.roots.has( name );
- }
- /**
- * Returns array with names of all roots (without the {@link #graveyard}) added to the document.
- *
- * @returns {Array.<String>} Roots names.
- */
- getRootNames() {
- return Array.from( this.roots.keys() ).filter( name => name != graveyardName );
- }
- /**
- * Basing on given `position`, finds and returns a {@link module:engine/model/range~Range Range} instance that is
- * nearest to that `position` and is a correct range for selection.
- *
- * Correct selection range might be collapsed - when it's located in position where text node can be placed.
- * Non-collapsed range is returned when selection can be placed around element marked as "object" in
- * {@link module:engine/model/schema~Schema schema}.
- *
- * Direction of searching for nearest correct selection range can be specified as:
- * * `both` - searching will be performed in both ways,
- * * `forward` - searching will be performed only forward,
- * * `backward` - searching will be performed only backward.
- *
- * When valid selection range cannot be found, `null` is returned.
- *
- * @param {module:engine/model/position~Position} position Reference position where new selection range should be looked for.
- * @param {'both'|'forward'|'backward'} [direction='both'] Search direction.
- * @returns {module:engine/model/range~Range|null} Nearest selection range or `null` if one cannot be found.
- */
- getNearestSelectionRange( position, direction = 'both' ) {
- const schema = this.model.schema;
- // Return collapsed range if provided position is valid.
- if ( schema.check( { name: '$text', inside: position } ) ) {
- return new Range( position );
- }
- let backwardWalker, forwardWalker;
- if ( direction == 'both' || direction == 'backward' ) {
- backwardWalker = new TreeWalker( { startPosition: position, direction: 'backward' } );
- }
- if ( direction == 'both' || direction == 'forward' ) {
- forwardWalker = new TreeWalker( { startPosition: position } );
- }
- for ( const data of combineWalkers( backwardWalker, forwardWalker ) ) {
- const type = ( data.walker == backwardWalker ? 'elementEnd' : 'elementStart' );
- const value = data.value;
- if ( value.type == type && schema.objects.has( value.item.name ) ) {
- return Range.createOn( value.item );
- }
- if ( schema.check( { name: '$text', inside: value.nextPosition } ) ) {
- return new Range( value.nextPosition );
- }
- }
- return null;
- }
- /**
- * Transforms two sets of deltas by themselves. Returns both transformed sets.
- *
- * @param {Array.<module:engine/model/delta/delta~Delta>} deltasA Array with the first set of deltas to transform. These
- * deltas are considered more important (than `deltasB`) when resolving conflicts.
- * @param {Array.<module:engine/model/delta/delta~Delta>} deltasB Array with the second set of deltas to transform. These
- * deltas are considered less important (than `deltasA`) when resolving conflicts.
- * @param {Boolean} [useContext=false] When set to `true`, transformation will store and use additional context
- * information to guarantee more expected results. Should be used whenever deltas related to already applied
- * deltas are transformed (for example when undoing changes).
- * @returns {Object}
- * @returns {Array.<module:engine/model/delta/delta~Delta>} return.deltasA The first set of deltas transformed
- * by the second set of deltas.
- * @returns {Array.<module:engine/model/delta/delta~Delta>} return.deltasB The second set of deltas transformed
- * by the first set of deltas.
- */
- transformDeltas( deltasA, deltasB, useContext = false ) {
- return deltaTransform.transformDeltaSets( deltasA, deltasB, useContext ? this : null );
- }
- /**
- * Custom toJSON method to solve child-parent circular dependencies.
- *
- * @returns {Object} Clone of this object with the document property changed to string.
- */
- toJSON() {
- const json = clone( this );
- // Due to circular references we need to remove parent reference.
- json.selection = '[engine.model.DocumentSelection]';
- json.model = '[engine.model.Model]';
- return json;
- }
- /**
- * Returns default root for this document which is either the first root that was added to the the document using
- * {@link #createRoot} or the {@link #graveyard graveyard root} if no other roots were created.
- *
- * @protected
- * @returns {module:engine/model/rootelement~RootElement} The default root for this document.
- */
- _getDefaultRoot() {
- for ( const root of this.roots.values() ) {
- if ( root !== this.graveyard ) {
- return root;
- }
- }
- return this.graveyard;
- }
- /**
- * Returns a default range for this selection. The default range is a collapsed range that starts and ends
- * at the beginning of this selection's document's {@link #_getDefaultRoot default root}.
- *
- * @protected
- * @returns {module:engine/model/range~Range}
- */
- _getDefaultRange() {
- const defaultRoot = this._getDefaultRoot();
- // Find the first position where the selection can be put.
- const position = new Position( defaultRoot, [ 0 ] );
- const nearestRange = this.getNearestSelectionRange( position );
- // If valid selection range is not found - return range collapsed at the beginning of the root.
- return nearestRange || new Range( position );
- }
- /**
- * Checks whether given {@link module:engine/model/range~Range range} is a valid range for
- * {@link #selection document's selection}.
- *
- * @private
- * @param {module:engine/model/range~Range} range Range to check.
- * @returns {Boolean} `true` if `range` is valid, `false` otherwise.
- */
- _validateSelectionRange( range ) {
- return validateTextNodePosition( range.start ) && validateTextNodePosition( range.end );
- }
- /**
- * Fired when document changes by applying an operation.
- *
- * There are a few types of change:
- *
- * * 'insert' when nodes are inserted,
- * * 'remove' when nodes are removed,
- * * 'reinsert' when remove is undone,
- * * 'move' when nodes are moved,
- * * 'rename' when element is renamed,
- * * 'marker' when a marker changes (added, removed or its range is changed),
- * * 'addAttribute' when attributes are added,
- * * 'removeAttribute' when attributes are removed,
- * * 'changeAttribute' when attributes change,
- * * 'addRootAttribute' when attribute for root is added,
- * * 'removeRootAttribute' when attribute for root is removed,
- * * 'changeRootAttribute' when attribute for root changes.
- *
- * @event change
- * @param {String} type Change type, possible option: 'insert', 'remove', 'reinsert', 'move', 'attribute'.
- * @param {Object} data Additional information about the change.
- * @param {module:engine/model/range~Range} [data.range] Range in model containing changed nodes. Note that the range state is
- * after changes has been done, i.e. for 'remove' the range will be in the {@link #graveyard graveyard root}.
- * The range is not defined for root, rename and marker types.
- * @param {module:engine/model/position~Position} [data.sourcePosition] Change source position.
- * Exists for 'remove', 'reinsert' and 'move'.
- * Note that this position state is before changes has been done, i.e. for 'reinsert' the source position will be in the
- * {@link #graveyard graveyard root}.
- * @param {String} [data.key] Only for attribute types. Key of changed / inserted / removed attribute.
- * @param {*} [data.oldValue] Only for 'removeAttribute', 'removeRootAttribute', 'changeAttribute' or
- * 'changeRootAttribute' type.
- * @param {*} [data.newValue] Only for 'addAttribute', 'addRootAttribute', 'changeAttribute' or
- * 'changeRootAttribute' type.
- * @param {module:engine/model/rootelement~RootElement} [data.root] Root element which attributes got changed. This is defined
- * only for root types.
- * @param {module:engine/model/batch~Batch} batch A {@link module:engine/model/batch~Batch batch}
- * of changes which this change is a part of.
- */
- /**
- * Fired when all queued document changes are done. See {@link #enqueueChanges}.
- *
- * @event changesDone
- */
- }
- mix( Document, EmitterMixin );
- // Checks whether given range boundary position is valid for document selection, meaning that is not between
- // unicode surrogate pairs or base character and combining marks.
- function validateTextNodePosition( rangeBoundary ) {
- const textNode = rangeBoundary.textNode;
- if ( textNode ) {
- const data = textNode.data;
- const offset = rangeBoundary.offset - textNode.startOffset;
- return !isInsideSurrogatePair( data, offset ) && !isInsideCombinedSymbol( data, offset );
- }
- return true;
- }
- // Generator function returning values from provided walkers, switching between them at each iteration. If only one walker
- // is provided it will return data only from that walker.
- //
- // @param {module:engine/module/treewalker~TreeWalker} [backward] Walker iterating in backward direction.
- // @param {module:engine/module/treewalker~TreeWalker} [forward] Walker iterating in forward direction.
- // @returns {Iterable.<Object>} Object returned at each iteration contains `value` and `walker` (informing which walker returned
- // given value) fields.
- function* combineWalkers( backward, forward ) {
- let done = false;
- while ( !done ) {
- done = true;
- if ( backward ) {
- const step = backward.next();
- if ( !step.done ) {
- done = false;
- yield {
- walker: backward,
- value: step.value
- };
- }
- }
- if ( forward ) {
- const step = forward.next();
- if ( !step.done ) {
- done = false;
- yield {
- walker: forward,
- value: step.value
- };
- }
- }
- }
- }
|