/**
* @license
* Copyright The Closure Library Authors.
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Utilties for working with ranges.
*/
goog.provide('goog.editor.range');
goog.provide('goog.editor.range.Point');
goog.require('goog.dom');
goog.require('goog.dom.NodeType');
goog.require('goog.dom.Range');
goog.require('goog.dom.RangeEndpoint');
goog.require('goog.dom.SavedCaretRange');
goog.require('goog.editor.node');
goog.require('goog.editor.style');
goog.require('goog.iter');
goog.require('goog.userAgent');
goog.requireType('goog.dom.AbstractRange');
goog.requireType('goog.dom.TagName');
/**
* Given a range and an element, create a narrower range that is limited to the
* boundaries of the element. If the range starts (or ends) outside the
* element, the narrowed range's start point (or end point) will be the
* leftmost (or rightmost) leaf of the element.
* @param {goog.dom.AbstractRange} range The range.
* @param {Element} el The element to limit the range to.
* @return {goog.dom.AbstractRange} A new narrowed range, or null if the
* element does not contain any part of the given range.
*/
goog.editor.range.narrow = function(range, el) {
'use strict';
var startContainer = range.getStartNode();
var endContainer = range.getEndNode();
if (startContainer && endContainer) {
var isElement = function(node) {
'use strict';
return node == el;
};
var hasStart = goog.dom.getAncestor(startContainer, isElement, true);
var hasEnd = goog.dom.getAncestor(endContainer, isElement, true);
if (hasStart && hasEnd) {
// The range is contained entirely within this element.
return range.clone();
} else if (hasStart) {
// The range starts inside the element, but ends outside it.
var leaf = goog.editor.node.getRightMostLeaf(el);
return goog.dom.Range.createFromNodes(
range.getStartNode(), range.getStartOffset(), leaf,
goog.editor.node.getLength(leaf));
} else if (hasEnd) {
// The range starts outside the element, but ends inside it.
return goog.dom.Range.createFromNodes(
goog.editor.node.getLeftMostLeaf(el), 0, range.getEndNode(),
range.getEndOffset());
}
}
// The selection starts and ends outside the element.
return null;
};
/**
* Given a range, expand the range to include outer tags if the full contents of
* those tags are entirely selected. This essentially changes the dom position,
* but not the visible position of the range.
* Ex. <code><li>foo</li></code> if "foo" is selected, instead of returning
* start and end nodes as the foo text node, return the li.
* @param {goog.dom.AbstractRange} range The range.
* @param {Node=} opt_stopNode Optional node to stop expanding past.
* @return {!goog.dom.AbstractRange} The expanded range.
*/
goog.editor.range.expand = function(range, opt_stopNode) {
'use strict';
// Expand the start out to the common container.
var expandedRange = goog.editor.range.expandEndPointToContainer_(
range, goog.dom.RangeEndpoint.START, opt_stopNode);
// Expand the end out to the common container.
expandedRange = goog.editor.range.expandEndPointToContainer_(
expandedRange, goog.dom.RangeEndpoint.END, opt_stopNode);
var startNode = expandedRange.getStartNode();
var endNode = expandedRange.getEndNode();
var startOffset = expandedRange.getStartOffset();
var endOffset = expandedRange.getEndOffset();
// If we have reached a common container, now expand out.
if (startNode == endNode) {
while (endNode != opt_stopNode && startOffset == 0 &&
endOffset == goog.editor.node.getLength(endNode)) {
// Select the parent instead.
var parentNode = endNode.parentNode;
startOffset =
Array.prototype.indexOf.call(parentNode.childNodes, endNode);
endOffset = startOffset + 1;
endNode = parentNode;
}
startNode = endNode;
}
return goog.dom.Range.createFromNodes(
startNode, startOffset, endNode, endOffset);
};
/**
* Given a range, expands the start or end points as far out towards the
* range's common container (or stopNode, if provided) as possible, while
* perserving the same visible position.
*
* @param {goog.dom.AbstractRange} range The range to expand.
* @param {goog.dom.RangeEndpoint} endpoint The endpoint to expand.
* @param {Node=} opt_stopNode Optional node to stop expanding past.
* @return {!goog.dom.AbstractRange} The expanded range.
* @private
*/
goog.editor.range.expandEndPointToContainer_ = function(
range, endpoint, opt_stopNode) {
'use strict';
var expandStart = endpoint == goog.dom.RangeEndpoint.START;
var node = expandStart ? range.getStartNode() : range.getEndNode();
var offset = expandStart ? range.getStartOffset() : range.getEndOffset();
var container = range.getContainerElement();
// Expand the node out until we reach the container or the stop node.
while (node != container && node != opt_stopNode) {
// It is only valid to expand the start if we are at the start of a node
// (offset 0) or expand the end if we are at the end of a node
// (offset length).
if (expandStart && offset != 0 ||
!expandStart && offset != goog.editor.node.getLength(node)) {
break;
}
var parentNode = node.parentNode;
var index = Array.prototype.indexOf.call(parentNode.childNodes, node);
offset = expandStart ? index : index + 1;
node = parentNode;
}
return goog.dom.Range.createFromNodes(
expandStart ? node : range.getStartNode(),
expandStart ? offset : range.getStartOffset(),
expandStart ? range.getEndNode() : node,
expandStart ? range.getEndOffset() : offset);
};
/**
* Cause the window's selection to be the start of this node.
* @param {Node} node The node to select the start of.
*/
goog.editor.range.selectNodeStart = function(node) {
'use strict';
goog.dom.Range.createCaret(goog.editor.node.getLeftMostLeaf(node), 0)
.select();
};
/**
* Position the cursor immediately to the left or right of "node".
* In Firefox, the selection parent is outside of "node", so the cursor can
* effectively be moved to the end of a link node, without being considered
* inside of it.
* Note: This does not always work in WebKit. In particular, if you try to
* place a cursor to the right of a link, typing still puts you in the link.
* Bug: http://bugs.webkit.org/show_bug.cgi?id=17697
* @param {Node} node The node to position the cursor relative to.
* @param {boolean} toLeft True to place it to the left, false to the right.
* @return {!goog.dom.AbstractRange} The newly selected range.
*/
goog.editor.range.placeCursorNextTo = function(node, toLeft) {
'use strict';
var parent = node.parentNode;
var offset =
Array.prototype.indexOf.call(parent.childNodes, node) + (toLeft ? 0 : 1);
var point =
goog.editor.range.Point.createDeepestPoint(parent, offset, toLeft, true);
var range = goog.dom.Range.createCaret(point.node, point.offset);
range.select();
return range;
};
/**
* Normalizes the node, preserving the selection of the document.
*
* May also normalize things outside the node, if it is more efficient to do so.
*
* @param {Node} node The node to normalize.
*/
goog.editor.range.selectionPreservingNormalize = function(node) {
'use strict';
var doc = goog.dom.getOwnerDocument(node);
var selection = goog.dom.Range.createFromWindow(goog.dom.getWindow(doc));
var normalizedRange =
goog.editor.range.rangePreservingNormalize(node, selection);
if (normalizedRange) {
normalizedRange.select();
}
};
/**
* Manually normalizes the node in IE, since native normalize in IE causes
* transient problems.
* @param {Node} node The node to normalize.
* @private
*/
goog.editor.range.normalizeNodeIe_ = function(node) {
'use strict';
var lastText = null;
var child = node.firstChild;
while (child) {
var next = child.nextSibling;
if (child.nodeType == goog.dom.NodeType.TEXT) {
if (child.nodeValue == '') {
node.removeChild(child);
} else if (lastText) {
lastText.nodeValue += child.nodeValue;
node.removeChild(child);
} else {
lastText = child;
}
} else {
goog.editor.range.normalizeNodeIe_(child);
lastText = null;
}
child = next;
}
};
/**
* Normalizes the given node.
* @param {Node} node The node to normalize.
*/
goog.editor.range.normalizeNode = function(node) {
'use strict';
if (goog.userAgent.IE) {
goog.editor.range.normalizeNodeIe_(node);
} else {
node.normalize();
}
};
/**
* Normalizes the node, preserving a range of the document.
*
* May also normalize things outside the node, if it is more efficient to do so.
*
* @param {Node} node The node to normalize.
* @param {goog.dom.AbstractRange?} range The range to normalize.
* @return {goog.dom.AbstractRange?} The range, adjusted for normalization.
*/
goog.editor.range.rangePreservingNormalize = function(node, range) {
'use strict';
if (range) {
var rangeFactory = goog.editor.range.normalize(range);
// WebKit has broken selection affinity, so carets tend to jump out of the
// beginning of inline elements. This means that if we're doing the
// normalize as the result of a range that will later become the selection,
// we might not normalize something in the range after it is read back from
// the selection. We can't just normalize the parentNode here because WebKit
// can move the selection range out of multiple inline parents.
var container = goog.editor.style.getContainer(range.getContainerElement());
}
if (container) {
goog.editor.range.normalizeNode(
goog.dom.findCommonAncestor(container, node));
} else if (node) {
goog.editor.range.normalizeNode(node);
}
if (rangeFactory) {
return rangeFactory();
} else {
return null;
}
};
/**
* Get the deepest point in the DOM that's equivalent to the endpoint of the
* given range.
*
* @param {goog.dom.AbstractRange} range A range.
* @param {boolean} atStart True for the start point, false for the end point.
* @return {!goog.editor.range.Point} The end point, expressed as a node
* and an offset.
*/
goog.editor.range.getDeepEndPoint = function(range, atStart) {
'use strict';
return atStart ? goog.editor.range.Point.createDeepestPoint(
range.getStartNode(), range.getStartOffset()) :
goog.editor.range.Point.createDeepestPoint(
range.getEndNode(), range.getEndOffset());
};
/**
* Given a range in the current DOM, create a factory for a range that
* represents the same selection in a normalized DOM. The factory function
* should be invoked after the DOM is normalized.
*
* All browsers do a bad job preserving ranges across DOM normalization.
* The issue is best described in this 5-year-old bug report:
* https://bugzilla.mozilla.org/show_bug.cgi?id=191864
* For most applications, this isn't a problem. The browsers do a good job
* handling un-normalized text, so there's usually no reason to normalize.
*
* The exception to this rule is the rich text editing commands
* execCommand and queryCommandValue, which will fail often if there are
* un-normalized text nodes.
*
* The factory function creates new ranges so that we can normalize the DOM
* without problems. It must be created before any normalization happens,
* and invoked after normalization happens.
*
* @param {goog.dom.AbstractRange} range The range to normalize. It may
* become invalid after body.normalize() is called.
* @return {function(): goog.dom.AbstractRange} A factory for a normalized
* range. Should be called after body.normalize() is called.
*/
goog.editor.range.normalize = function(range) {
'use strict';
var isReversed = range.isReversed();
var anchorPoint = goog.editor.range.normalizePoint_(
goog.editor.range.getDeepEndPoint(range, !isReversed));
var anchorParent = anchorPoint.getParentPoint();
var anchorPreviousSibling = anchorPoint.node.previousSibling;
if (anchorPoint.node.nodeType == goog.dom.NodeType.TEXT) {
anchorPoint.node = null;
}
var focusPoint = goog.editor.range.normalizePoint_(
goog.editor.range.getDeepEndPoint(range, isReversed));
var focusParent = focusPoint.getParentPoint();
var focusPreviousSibling = focusPoint.node.previousSibling;
if (focusPoint.node.nodeType == goog.dom.NodeType.TEXT) {
focusPoint.node = null;
}
return function() {
'use strict';
if (!anchorPoint.node && anchorPreviousSibling) {
// If anchorPoint.node was previously an empty text node with no siblings,
// anchorPreviousSibling may not have a nextSibling since that node will
// no longer exist. Do our best and point to the end of the previous
// element.
anchorPoint.node = anchorPreviousSibling.nextSibling;
if (!anchorPoint.node) {
anchorPoint =
goog.editor.range.Point.getPointAtEndOfNode(anchorPreviousSibling);
}
}
if (!focusPoint.node && focusPreviousSibling) {
// If focusPoint.node was previously an empty text node with no siblings,
// focusPreviousSibling may not have a nextSibling since that node will no
// longer exist. Do our best and point to the end of the previous
// element.
focusPoint.node = focusPreviousSibling.nextSibling;
if (!focusPoint.node) {
focusPoint =
goog.editor.range.Point.getPointAtEndOfNode(focusPreviousSibling);
}
}
return goog.dom.Range.createFromNodes(
anchorPoint.node || anchorParent.node.firstChild || anchorParent.node,
anchorPoint.offset,
focusPoint.node || focusParent.node.firstChild || focusParent.node,
focusPoint.offset);
};
};
/**
* Given a point in the current DOM, adjust it to represent the same point in
* a normalized DOM.
*
* See the comments on goog.editor.range.normalize for more context.
*
* @param {goog.editor.range.Point} point A point in the document.
* @return {!goog.editor.range.Point} The same point, for easy chaining.
* @private
*/
goog.editor.range.normalizePoint_ = function(point) {
'use strict';
var previous;
if (point.node.nodeType == goog.dom.NodeType.TEXT) {
// If the cursor position is in a text node,
// look at all the previous text siblings of the text node,
// and set the offset relative to the earliest text sibling.
for (var current = point.node.previousSibling;
current && current.nodeType == goog.dom.NodeType.TEXT;
current = current.previousSibling) {
point.offset += goog.editor.node.getLength(current);
}
previous = current;
} else {
previous = point.node.previousSibling;
}
var parent = point.node.parentNode;
point.node = previous ? previous.nextSibling : parent.firstChild;
return point;
};
/**
* Checks if a range is completely inside an editable region.
* @param {goog.dom.AbstractRange} range The range to test.
* @return {boolean} Whether the range is completely inside an editable region.
*/
goog.editor.range.isEditable = function(range) {
'use strict';
var rangeContainer = range.getContainerElement();
// Closure's implementation of getContainerElement() is a little too
// smart in IE when exactly one element is contained in the range.
// It assumes that there's a user whose intent was actually to select
// all that element's children, so it returns the element itself as its
// own containing element.
// This little sanity check detects this condition so we can account for it.
var rangeContainerIsOutsideRange =
range.getStartNode() != rangeContainer.parentElement;
return (rangeContainerIsOutsideRange &&
goog.editor.node.isEditableContainer(rangeContainer)) ||
goog.editor.node.isEditable(rangeContainer);
};
/**
* Returns whether the given range intersects with any instance of the given
* tag.
* @param {goog.dom.AbstractRange} range The range to check.
* @param {!goog.dom.TagName} tagName The name of the tag.
* @return {boolean} Whether the given range intersects with any instance of
* the given tag.
*/
goog.editor.range.intersectsTag = function(range, tagName) {
'use strict';
if (goog.dom.getAncestorByTagNameAndClass(
range.getContainerElement(), tagName)) {
return true;
}
return goog.iter.some(range, function(node) {
'use strict';
return node.tagName == tagName;
});
};
/**
* One endpoint of a range, represented as a Node and and offset.
* @param {Node} node The node containing the point.
* @param {number} offset The offset of the point into the node.
* @constructor
* @final
*/
goog.editor.range.Point = function(node, offset) {
'use strict';
/**
* The node containing the point.
* @type {Node}
*/
this.node = node;
/**
* The offset of the point into the node.
* @type {number}
*/
this.offset = offset;
};
/**
* Gets the point of this point's node in the DOM.
* @return {!goog.editor.range.Point} The node's point.
*/
goog.editor.range.Point.prototype.getParentPoint = function() {
'use strict';
var parent = this.node.parentNode;
return new goog.editor.range.Point(
parent, Array.prototype.indexOf.call(parent.childNodes, this.node));
};
/**
* Construct the deepest possible point in the DOM that's equivalent
* to the given point, expressed as a node and an offset.
* @param {Node} node The node containing the point.
* @param {number} offset The offset of the point from the node.
* @param {boolean=} opt_trendLeft Notice that a (node, offset) pair may be
* equivalent to more than one descendant (node, offset) pair in the DOM.
* By default, we trend rightward. If this parameter is true, then we
* trend leftward. The tendency to fall rightward by default is for
* consistency with other range APIs (like placeCursorNextTo).
* @param {boolean=} opt_stopOnChildlessElement If true, and we encounter
* a Node which is an Element that cannot have children, we return a Point
* based on its parent rather than that Node itself.
* @return {!goog.editor.range.Point} A new point.
*/
goog.editor.range.Point.createDeepestPoint = function(
node, offset, opt_trendLeft, opt_stopOnChildlessElement) {
'use strict';
while (node.nodeType == goog.dom.NodeType.ELEMENT) {
var child = node.childNodes[offset];
if (!child && !node.lastChild) {
break;
} else if (child) {
var prevSibling = child.previousSibling;
if (opt_trendLeft && prevSibling) {
if (opt_stopOnChildlessElement &&
goog.editor.range.Point.isTerminalElement_(prevSibling)) {
break;
}
node = prevSibling;
offset = goog.editor.node.getLength(node);
} else {
if (opt_stopOnChildlessElement &&
goog.editor.range.Point.isTerminalElement_(child)) {
break;
}
node = child;
offset = 0;
}
} else {
if (opt_stopOnChildlessElement &&
goog.editor.range.Point.isTerminalElement_(node.lastChild)) {
break;
}
node = node.lastChild;
offset = goog.editor.node.getLength(node);
}
}
return new goog.editor.range.Point(node, offset);
};
/**
* Return true if the specified node is an Element that is not expected to have
* children. The createDeepestPoint() method should not traverse into
* such elements.
* @param {Node} node .
* @return {boolean} True if the node is an Element that does not contain
* child nodes (e.g. BR, IMG).
* @private
*/
goog.editor.range.Point.isTerminalElement_ = function(node) {
'use strict';
return (
node.nodeType == goog.dom.NodeType.ELEMENT &&
!goog.dom.canHaveChildren(node));
};
/**
* Construct a point at the very end of the given node.
* @param {Node} node The node to create a point for.
* @return {!goog.editor.range.Point} A new point.
*/
goog.editor.range.Point.getPointAtEndOfNode = function(node) {
'use strict';
return new goog.editor.range.Point(node, goog.editor.node.getLength(node));
};
/**
* Saves the range by inserting carets into the HTML.
*
* Unlike the regular saveUsingCarets, this SavedRange normalizes text nodes.
* Browsers have other bugs where they don't handle split text nodes in
* contentEditable regions right.
*
* @param {goog.dom.AbstractRange} range The abstract range object.
* @return {!goog.dom.SavedCaretRange} A saved caret range that normalizes
* text nodes.
*/
goog.editor.range.saveUsingNormalizedCarets = function(range) {
'use strict';
return new goog.editor.range.NormalizedCaretRange_(range);
};
/**
* Saves the range using carets, but normalizes text nodes when carets
* are removed.
* @see goog.editor.range.saveUsingNormalizedCarets
* @param {goog.dom.AbstractRange} range The range being saved.
* @constructor
* @extends {goog.dom.SavedCaretRange}
* @private
*/
goog.editor.range.NormalizedCaretRange_ = function(range) {
'use strict';
goog.dom.SavedCaretRange.call(this, range);
};
goog.inherits(
goog.editor.range.NormalizedCaretRange_, goog.dom.SavedCaretRange);
/**
* Normalizes text nodes whenever carets are removed from the document.
* @param {goog.dom.AbstractRange=} opt_range A range whose offsets have already
* been adjusted for caret removal; it will be adjusted and returned if it
* is also affected by post-removal operations, such as text node
* normalization.
* @return {goog.dom.AbstractRange|undefined} The adjusted range, if opt_range
* was provided.
* @override
*/
goog.editor.range.NormalizedCaretRange_.prototype.removeCarets = function(
opt_range) {
'use strict';
var startCaret = this.getCaret(true);
var endCaret = this.getCaret(false);
var node = startCaret && endCaret ?
goog.dom.findCommonAncestor(startCaret, endCaret) :
startCaret || endCaret;
goog.editor.range.NormalizedCaretRange_.superClass_.removeCarets.call(this);
if (opt_range) {
return goog.editor.range.rangePreservingNormalize(node, opt_range);
} else if (node) {
goog.editor.range.selectionPreservingNormalize(node);
}
};
Codebase Browser
chromium