1
// Copyright 2008 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15
/**
16
 * @fileoverview Utilties for working with ranges.
17
 *
18
 * @author [email protected] (Nick Santos)
19
 */
20

21
goog.provide('goog.editor.range');
22
goog.provide('goog.editor.range.Point');
23

24
goog.require('goog.array');
25
goog.require('goog.dom');
26
goog.require('goog.dom.NodeType');
27
goog.require('goog.dom.Range');
28
goog.require('goog.dom.RangeEndpoint');
29
goog.require('goog.dom.SavedCaretRange');
30
goog.require('goog.editor.node');
31
goog.require('goog.editor.style');
32
goog.require('goog.iter');
33
goog.require('goog.userAgent');
34

35

36
/**
37
 * Given a range and an element, create a narrower range that is limited to the
38
 * boundaries of the element. If the range starts (or ends) outside the
39
 * element, the narrowed range's start point (or end point) will be the
40
 * leftmost (or rightmost) leaf of the element.
41
 * @param {goog.dom.AbstractRange} range The range.
42
 * @param {Element} el The element to limit the range to.
43
 * @return {goog.dom.AbstractRange} A new narrowed range, or null if the
44
 *     element does not contain any part of the given range.
45
 */
46
goog.editor.range.narrow = function(range, el) {
47
  var startContainer = range.getStartNode();
48
  var endContainer = range.getEndNode();
49

50
  if (startContainer && endContainer) {
51
    var isElement = function(node) { return node == el; };
52
    var hasStart = goog.dom.getAncestor(startContainer, isElement, true);
53
    var hasEnd = goog.dom.getAncestor(endContainer, isElement, true);
54

55
    if (hasStart && hasEnd) {
56
      // The range is contained entirely within this element.
57
      return range.clone();
58
    } else if (hasStart) {
59
      // The range starts inside the element, but ends outside it.
60
      var leaf = goog.editor.node.getRightMostLeaf(el);
61
      return goog.dom.Range.createFromNodes(
62
          range.getStartNode(), range.getStartOffset(), leaf,
63
          goog.editor.node.getLength(leaf));
64
    } else if (hasEnd) {
65
      // The range starts outside the element, but ends inside it.
66
      return goog.dom.Range.createFromNodes(
67
          goog.editor.node.getLeftMostLeaf(el), 0, range.getEndNode(),
68
          range.getEndOffset());
69
    }
70
  }
71

72
  // The selection starts and ends outside the element.
73
  return null;
74
};
75

76

77
/**
78
 * Given a range, expand the range to include outer tags if the full contents of
79
 * those tags are entirely selected.  This essentially changes the dom position,
80
 * but not the visible position of the range.
81
 * Ex. <code><li>foo</li></code> if "foo" is selected, instead of returning
82
 * start and end nodes as the foo text node, return the li.
83
 * @param {goog.dom.AbstractRange} range The range.
84
 * @param {Node=} opt_stopNode Optional node to stop expanding past.
85
 * @return {!goog.dom.AbstractRange} The expanded range.
86
 */
87
goog.editor.range.expand = function(range, opt_stopNode) {
88
  // Expand the start out to the common container.
89
  var expandedRange = goog.editor.range.expandEndPointToContainer_(
90
      range, goog.dom.RangeEndpoint.START, opt_stopNode);
91
  // Expand the end out to the common container.
92
  expandedRange = goog.editor.range.expandEndPointToContainer_(
93
      expandedRange, goog.dom.RangeEndpoint.END, opt_stopNode);
94

95
  var startNode = expandedRange.getStartNode();
96
  var endNode = expandedRange.getEndNode();
97
  var startOffset = expandedRange.getStartOffset();
98
  var endOffset = expandedRange.getEndOffset();
99

100
  // If we have reached a common container, now expand out.
101
  if (startNode == endNode) {
102
    while (endNode != opt_stopNode && startOffset == 0 &&
103
           endOffset == goog.editor.node.getLength(endNode)) {
104
      // Select the parent instead.
105
      var parentNode = endNode.parentNode;
106
      startOffset = goog.array.indexOf(parentNode.childNodes, endNode);
107
      endOffset = startOffset + 1;
108
      endNode = parentNode;
109
    }
110
    startNode = endNode;
111
  }
112

113
  return goog.dom.Range.createFromNodes(
114
      startNode, startOffset, endNode, endOffset);
115
};
116

117

118
/**
119
 * Given a range, expands the start or end points as far out towards the
120
 * range's common container (or stopNode, if provided) as possible, while
121
 * perserving the same visible position.
122
 *
123
 * @param {goog.dom.AbstractRange} range The range to expand.
124
 * @param {goog.dom.RangeEndpoint} endpoint The endpoint to expand.
125
 * @param {Node=} opt_stopNode Optional node to stop expanding past.
126
 * @return {!goog.dom.AbstractRange} The expanded range.
127
 * @private
128
 */
129
goog.editor.range.expandEndPointToContainer_ = function(
130
    range, endpoint, opt_stopNode) {
131
  var expandStart = endpoint == goog.dom.RangeEndpoint.START;
132
  var node = expandStart ? range.getStartNode() : range.getEndNode();
133
  var offset = expandStart ? range.getStartOffset() : range.getEndOffset();
134
  var container = range.getContainerElement();
135

136
  // Expand the node out until we reach the container or the stop node.
137
  while (node != container && node != opt_stopNode) {
138
    // It is only valid to expand the start if we are at the start of a node
139
    // (offset 0) or expand the end if we are at the end of a node
140
    // (offset length).
141
    if (expandStart && offset != 0 ||
142
        !expandStart && offset != goog.editor.node.getLength(node)) {
143
      break;
144
    }
145

146
    var parentNode = node.parentNode;
147
    var index = goog.array.indexOf(parentNode.childNodes, node);
148
    offset = expandStart ? index : index + 1;
149
    node = parentNode;
150
  }
151

152
  return goog.dom.Range.createFromNodes(
153
      expandStart ? node : range.getStartNode(),
154
      expandStart ? offset : range.getStartOffset(),
155
      expandStart ? range.getEndNode() : node,
156
      expandStart ? range.getEndOffset() : offset);
157
};
158

159

160
/**
161
 * Cause the window's selection to be the start of this node.
162
 * @param {Node} node The node to select the start of.
163
 */
164
goog.editor.range.selectNodeStart = function(node) {
165
  goog.dom.Range.createCaret(goog.editor.node.getLeftMostLeaf(node), 0)
166
      .select();
167
};
168

169

170
/**
171
 * Position the cursor immediately to the left or right of "node".
172
 * In Firefox, the selection parent is outside of "node", so the cursor can
173
 * effectively be moved to the end of a link node, without being considered
174
 * inside of it.
175
 * Note: This does not always work in WebKit. In particular, if you try to
176
 * place a cursor to the right of a link, typing still puts you in the link.
177
 * Bug: http://bugs.webkit.org/show_bug.cgi?id=17697
178
 * @param {Node} node The node to position the cursor relative to.
179
 * @param {boolean} toLeft True to place it to the left, false to the right.
180
 * @return {!goog.dom.AbstractRange} The newly selected range.
181
 */
182
goog.editor.range.placeCursorNextTo = function(node, toLeft) {
183
  var parent = node.parentNode;
184
  var offset = goog.array.indexOf(parent.childNodes, node) + (toLeft ? 0 : 1);
185
  var point =
186
      goog.editor.range.Point.createDeepestPoint(parent, offset, toLeft, true);
187
  var range = goog.dom.Range.createCaret(point.node, point.offset);
188
  range.select();
189
  return range;
190
};
191

192

193
/**
194
 * Normalizes the node, preserving the selection of the document.
195
 *
196
 * May also normalize things outside the node, if it is more efficient to do so.
197
 *
198
 * @param {Node} node The node to normalize.
199
 */
200
goog.editor.range.selectionPreservingNormalize = function(node) {
201
  var doc = goog.dom.getOwnerDocument(node);
202
  var selection = goog.dom.Range.createFromWindow(goog.dom.getWindow(doc));
203
  var normalizedRange =
204
      goog.editor.range.rangePreservingNormalize(node, selection);
205
  if (normalizedRange) {
206
    normalizedRange.select();
207
  }
208
};
209

210

211
/**
212
 * Manually normalizes the node in IE, since native normalize in IE causes
213
 * transient problems.
214
 * @param {Node} node The node to normalize.
215
 * @private
216
 */
217
goog.editor.range.normalizeNodeIe_ = function(node) {
218
  var lastText = null;
219
  var child = node.firstChild;
220
  while (child) {
221
    var next = child.nextSibling;
222
    if (child.nodeType == goog.dom.NodeType.TEXT) {
223
      if (child.nodeValue == '') {
224
        node.removeChild(child);
225
      } else if (lastText) {
226
        lastText.nodeValue += child.nodeValue;
227
        node.removeChild(child);
228
      } else {
229
        lastText = child;
230
      }
231
    } else {
232
      goog.editor.range.normalizeNodeIe_(child);
233
      lastText = null;
234
    }
235
    child = next;
236
  }
237
};
238

239

240
/**
241
 * Normalizes the given node.
242
 * @param {Node} node The node to normalize.
243
 */
244
goog.editor.range.normalizeNode = function(node) {
245
  if (goog.userAgent.IE) {
246
    goog.editor.range.normalizeNodeIe_(node);
247
  } else {
248
    node.normalize();
249
  }
250
};
251

252

253
/**
254
 * Normalizes the node, preserving a range of the document.
255
 *
256
 * May also normalize things outside the node, if it is more efficient to do so.
257
 *
258
 * @param {Node} node The node to normalize.
259
 * @param {goog.dom.AbstractRange?} range The range to normalize.
260
 * @return {goog.dom.AbstractRange?} The range, adjusted for normalization.
261
 */
262
goog.editor.range.rangePreservingNormalize = function(node, range) {
263
  if (range) {
264
    var rangeFactory = goog.editor.range.normalize(range);
265
    // WebKit has broken selection affinity, so carets tend to jump out of the
266
    // beginning of inline elements. This means that if we're doing the
267
    // normalize as the result of a range that will later become the selection,
268
    // we might not normalize something in the range after it is read back from
269
    // the selection. We can't just normalize the parentNode here because WebKit
270
    // can move the selection range out of multiple inline parents.
271
    var container = goog.editor.style.getContainer(range.getContainerElement());
272
  }
273

274
  if (container) {
275
    goog.editor.range.normalizeNode(
276
        goog.dom.findCommonAncestor(container, node));
277
  } else if (node) {
278
    goog.editor.range.normalizeNode(node);
279
  }
280

281
  if (rangeFactory) {
282
    return rangeFactory();
283
  } else {
284
    return null;
285
  }
286
};
287

288

289
/**
290
 * Get the deepest point in the DOM that's equivalent to the endpoint of the
291
 * given range.
292
 *
293
 * @param {goog.dom.AbstractRange} range A range.
294
 * @param {boolean} atStart True for the start point, false for the end point.
295
 * @return {!goog.editor.range.Point} The end point, expressed as a node
296
 *    and an offset.
297
 */
298
goog.editor.range.getDeepEndPoint = function(range, atStart) {
299
  return atStart ?
300
      goog.editor.range.Point.createDeepestPoint(
301
          range.getStartNode(), range.getStartOffset()) :
302
      goog.editor.range.Point.createDeepestPoint(
303
          range.getEndNode(), range.getEndOffset());
304
};
305

306

307
/**
308
 * Given a range in the current DOM, create a factory for a range that
309
 * represents the same selection in a normalized DOM. The factory function
310
 * should be invoked after the DOM is normalized.
311
 *
312
 * All browsers do a bad job preserving ranges across DOM normalization.
313
 * The issue is best described in this 5-year-old bug report:
314
 * https://bugzilla.mozilla.org/show_bug.cgi?id=191864
315
 * For most applications, this isn't a problem. The browsers do a good job
316
 * handling un-normalized text, so there's usually no reason to normalize.
317
 *
318
 * The exception to this rule is the rich text editing commands
319
 * execCommand and queryCommandValue, which will fail often if there are
320
 * un-normalized text nodes.
321
 *
322
 * The factory function creates new ranges so that we can normalize the DOM
323
 * without problems. It must be created before any normalization happens,
324
 * and invoked after normalization happens.
325
 *
326
 * @param {goog.dom.AbstractRange} range The range to normalize. It may
327
 *    become invalid after body.normalize() is called.
328
 * @return {function(): goog.dom.AbstractRange} A factory for a normalized
329
 *    range. Should be called after body.normalize() is called.
330
 */
331
goog.editor.range.normalize = function(range) {
332
  var isReversed = range.isReversed();
333
  var anchorPoint = goog.editor.range.normalizePoint_(
334
      goog.editor.range.getDeepEndPoint(range, !isReversed));
335
  var anchorParent = anchorPoint.getParentPoint();
336
  var anchorPreviousSibling = anchorPoint.node.previousSibling;
337
  if (anchorPoint.node.nodeType == goog.dom.NodeType.TEXT) {
338
    anchorPoint.node = null;
339
  }
340

341
  var focusPoint = goog.editor.range.normalizePoint_(
342
      goog.editor.range.getDeepEndPoint(range, isReversed));
343
  var focusParent = focusPoint.getParentPoint();
344
  var focusPreviousSibling = focusPoint.node.previousSibling;
345
  if (focusPoint.node.nodeType == goog.dom.NodeType.TEXT) {
346
    focusPoint.node = null;
347
  }
348

349
  return function() {
350
    if (!anchorPoint.node && anchorPreviousSibling) {
351
      // If anchorPoint.node was previously an empty text node with no siblings,
352
      // anchorPreviousSibling may not have a nextSibling since that node will
353
      // no longer exist.  Do our best and point to the end of the previous
354
      // element.
355
      anchorPoint.node = anchorPreviousSibling.nextSibling;
356
      if (!anchorPoint.node) {
357
        anchorPoint =
358
            goog.editor.range.Point.getPointAtEndOfNode(anchorPreviousSibling);
359
      }
360
    }
361

362
    if (!focusPoint.node && focusPreviousSibling) {
363
      // If focusPoint.node was previously an empty text node with no siblings,
364
      // focusPreviousSibling may not have a nextSibling since that node will no
365
      // longer exist.  Do our best and point to the end of the previous
366
      // element.
367
      focusPoint.node = focusPreviousSibling.nextSibling;
368
      if (!focusPoint.node) {
369
        focusPoint =
370
            goog.editor.range.Point.getPointAtEndOfNode(focusPreviousSibling);
371
      }
372
    }
373

374
    return goog.dom.Range.createFromNodes(
375
        anchorPoint.node || anchorParent.node.firstChild || anchorParent.node,
376
        anchorPoint.offset,
377
        focusPoint.node || focusParent.node.firstChild || focusParent.node,
378
        focusPoint.offset);
379
  };
380
};
381

382

383
/**
384
 * Given a point in the current DOM, adjust it to represent the same point in
385
 * a normalized DOM.
386
 *
387
 * See the comments on goog.editor.range.normalize for more context.
388
 *
389
 * @param {goog.editor.range.Point} point A point in the document.
390
 * @return {!goog.editor.range.Point} The same point, for easy chaining.
391
 * @private
392
 */
393
goog.editor.range.normalizePoint_ = function(point) {
394
  var previous;
395
  if (point.node.nodeType == goog.dom.NodeType.TEXT) {
396
    // If the cursor position is in a text node,
397
    // look at all the previous text siblings of the text node,
398
    // and set the offset relative to the earliest text sibling.
399
    for (var current = point.node.previousSibling;
400
         current && current.nodeType == goog.dom.NodeType.TEXT;
401
         current = current.previousSibling) {
402
      point.offset += goog.editor.node.getLength(current);
403
    }
404

405
    previous = current;
406
  } else {
407
    previous = point.node.previousSibling;
408
  }
409

410
  var parent = point.node.parentNode;
411
  point.node = previous ? previous.nextSibling : parent.firstChild;
412
  return point;
413
};
414

415

416
/**
417
 * Checks if a range is completely inside an editable region.
418
 * @param {goog.dom.AbstractRange} range The range to test.
419
 * @return {boolean} Whether the range is completely inside an editable region.
420
 */
421
goog.editor.range.isEditable = function(range) {
422
  var rangeContainer = range.getContainerElement();
423

424
  // Closure's implementation of getContainerElement() is a little too
425
  // smart in IE when exactly one element is contained in the range.
426
  // It assumes that there's a user whose intent was actually to select
427
  // all that element's children, so it returns the element itself as its
428
  // own containing element.
429
  // This little sanity check detects this condition so we can account for it.
430
  var rangeContainerIsOutsideRange =
431
      range.getStartNode() != rangeContainer.parentElement;
432

433
  return (rangeContainerIsOutsideRange &&
434
          goog.editor.node.isEditableContainer(rangeContainer)) ||
435
      goog.editor.node.isEditable(rangeContainer);
436
};
437

438

439
/**
440
 * Returns whether the given range intersects with any instance of the given
441
 * tag.
442
 * @param {goog.dom.AbstractRange} range The range to check.
443
 * @param {!goog.dom.TagName} tagName The name of the tag.
444
 * @return {boolean} Whether the given range intersects with any instance of
445
 *     the given tag.
446
 */
447
goog.editor.range.intersectsTag = function(range, tagName) {
448
  if (goog.dom.getAncestorByTagNameAndClass(
449
          range.getContainerElement(), tagName)) {
450
    return true;
451
  }
452

453
  return goog.iter.some(
454
      range, function(node) { return node.tagName == tagName; });
455
};
456

457

458

459
/**
460
 * One endpoint of a range, represented as a Node and and offset.
461
 * @param {Node} node The node containing the point.
462
 * @param {number} offset The offset of the point into the node.
463
 * @constructor
464
 * @final
465
 */
466
goog.editor.range.Point = function(node, offset) {
467
  /**
468
   * The node containing the point.
469
   * @type {Node}
470
   */
471
  this.node = node;
472

473
  /**
474
   * The offset of the point into the node.
475
   * @type {number}
476
   */
477
  this.offset = offset;
478
};
479

480

481
/**
482
 * Gets the point of this point's node in the DOM.
483
 * @return {!goog.editor.range.Point} The node's point.
484
 */
485
goog.editor.range.Point.prototype.getParentPoint = function() {
486
  var parent = this.node.parentNode;
487
  return new goog.editor.range.Point(
488
      parent, goog.array.indexOf(parent.childNodes, this.node));
489
};
490

491

492
/**
493
 * Construct the deepest possible point in the DOM that's equivalent
494
 * to the given point, expressed as a node and an offset.
495
 * @param {Node} node The node containing the point.
496
 * @param {number} offset The offset of the point from the node.
497
 * @param {boolean=} opt_trendLeft Notice that a (node, offset) pair may be
498
 *     equivalent to more than one descendent (node, offset) pair in the DOM.
499
 *     By default, we trend rightward. If this parameter is true, then we
500
 *     trend leftward. The tendency to fall rightward by default is for
501
 *     consistency with other range APIs (like placeCursorNextTo).
502
 * @param {boolean=} opt_stopOnChildlessElement If true, and we encounter
503
 *     a Node which is an Element that cannot have children, we return a Point
504
 *     based on its parent rather than that Node itself.
505
 * @return {!goog.editor.range.Point} A new point.
506
 */
507
goog.editor.range.Point.createDeepestPoint = function(
508
    node, offset, opt_trendLeft, opt_stopOnChildlessElement) {
509
  while (node.nodeType == goog.dom.NodeType.ELEMENT) {
510
    var child = node.childNodes[offset];
511
    if (!child && !node.lastChild) {
512
      break;
513
    } else if (child) {
514
      var prevSibling = child.previousSibling;
515
      if (opt_trendLeft && prevSibling) {
516
        if (opt_stopOnChildlessElement &&
517
            goog.editor.range.Point.isTerminalElement_(prevSibling)) {
518
          break;
519
        }
520
        node = prevSibling;
521
        offset = goog.editor.node.getLength(node);
522
      } else {
523
        if (opt_stopOnChildlessElement &&
524
            goog.editor.range.Point.isTerminalElement_(child)) {
525
          break;
526
        }
527
        node = child;
528
        offset = 0;
529
      }
530
    } else {
531
      if (opt_stopOnChildlessElement &&
532
          goog.editor.range.Point.isTerminalElement_(node.lastChild)) {
533
        break;
534
      }
535
      node = node.lastChild;
536
      offset = goog.editor.node.getLength(node);
537
    }
538
  }
539

540
  return new goog.editor.range.Point(node, offset);
541
};
542

543

544
/**
545
 * Return true if the specified node is an Element that is not expected to have
546
 * children. The createDeepestPoint() method should not traverse into
547
 * such elements.
548
 * @param {Node} node .
549
 * @return {boolean} True if the node is an Element that does not contain
550
 *     child nodes (e.g. BR, IMG).
551
 * @private
552
 */
553
goog.editor.range.Point.isTerminalElement_ = function(node) {
554
  return (
555
      node.nodeType == goog.dom.NodeType.ELEMENT &&
556
      !goog.dom.canHaveChildren(node));
557
};
558

559

560
/**
561
 * Construct a point at the very end of the given node.
562
 * @param {Node} node The node to create a point for.
563
 * @return {!goog.editor.range.Point} A new point.
564
 */
565
goog.editor.range.Point.getPointAtEndOfNode = function(node) {
566
  return new goog.editor.range.Point(node, goog.editor.node.getLength(node));
567
};
568

569

570
/**
571
 * Saves the range by inserting carets into the HTML.
572
 *
573
 * Unlike the regular saveUsingCarets, this SavedRange normalizes text nodes.
574
 * Browsers have other bugs where they don't handle split text nodes in
575
 * contentEditable regions right.
576
 *
577
 * @param {goog.dom.AbstractRange} range The abstract range object.
578
 * @return {!goog.dom.SavedCaretRange} A saved caret range that normalizes
579
 *     text nodes.
580
 */
581
goog.editor.range.saveUsingNormalizedCarets = function(range) {
582
  return new goog.editor.range.NormalizedCaretRange_(range);
583
};
584

585

586

587
/**
588
 * Saves the range using carets, but normalizes text nodes when carets
589
 * are removed.
590
 * @see goog.editor.range.saveUsingNormalizedCarets
591
 * @param {goog.dom.AbstractRange} range The range being saved.
592
 * @constructor
593
 * @extends {goog.dom.SavedCaretRange}
594
 * @private
595
 */
596
goog.editor.range.NormalizedCaretRange_ = function(range) {
597
  goog.dom.SavedCaretRange.call(this, range);
598
};
599
goog.inherits(
600
    goog.editor.range.NormalizedCaretRange_, goog.dom.SavedCaretRange);
601

602

603
/**
604
 * Normalizes text nodes whenever carets are removed from the document.
605
 * @param {goog.dom.AbstractRange=} opt_range A range whose offsets have already
606
 *     been adjusted for caret removal; it will be adjusted and returned if it
607
 *     is also affected by post-removal operations, such as text node
608
 *     normalization.
609
 * @return {goog.dom.AbstractRange|undefined} The adjusted range, if opt_range
610
 *     was provided.
611
 * @override
612
 */
613
goog.editor.range.NormalizedCaretRange_.prototype.removeCarets = function(
614
    opt_range) {
615
  var startCaret = this.getCaret(true);
616
  var endCaret = this.getCaret(false);
617
  var node = startCaret && endCaret ?
618
      goog.dom.findCommonAncestor(startCaret, endCaret) :
619
      startCaret || endCaret;
620

621
  goog.editor.range.NormalizedCaretRange_.superClass_.removeCarets.call(this);
622

623
  if (opt_range) {
624
    return goog.editor.range.rangePreservingNormalize(node, opt_range);
625
  } else if (node) {
626
    goog.editor.range.selectionPreservingNormalize(node);
627
  }
628
};
629

630