summaryrefslogtreecommitdiff
path: root/ext/js/app/popup.js
diff options
context:
space:
mode:
authortoasted-nutbread <toasted-nutbread@users.noreply.github.com>2022-05-20 10:28:38 -0400
committerGitHub <noreply@github.com>2022-05-20 10:28:38 -0400
commit31e20c889e467aa4ba64b0b5baf602adc1359371 (patch)
treea033db935a817b2d407ec20843176610a87a6e16 /ext/js/app/popup.js
parentae0ad227c0fd293609a21e5cc1d2a4b85fe7c520 (diff)
ESlint JSdoc (#2148)
* Install eslint-plugin-jsdoc * Initial rules setup * Update lists * Use @returns rather than @return * Remove error throwing code which is never executed * Fix issues relating to @throws * General error fixes * Update Display type documentation * Various doc fixes * Fix invalid tuple syntax * Doc updates * Remove unused * Doc updates * Enable jsdoc/require-returns * Update rules * Update remaining rules
Diffstat (limited to 'ext/js/app/popup.js')
-rw-r--r--ext/js/app/popup.js49
1 files changed, 37 insertions, 12 deletions
diff --git a/ext/js/app/popup.js b/ext/js/app/popup.js
index e3ac4dc3..9ca2165d 100644
--- a/ext/js/app/popup.js
+++ b/ext/js/app/popup.js
@@ -66,7 +66,7 @@ class Popup extends EventDispatcher {
/**
* Creates a new instance.
- * @param {object} details
+ * @param {object} details The details used to construct the new instance.
* @param {string} details.id The ID of the popup.
* @param {number} details.depth The depth of the popup.
* @param {number} details.frameId The ID of the host frame.
@@ -673,9 +673,11 @@ class Popup extends EventDispatcher {
}
/**
- * @param {Rect[]} sourceRects
- * @param {string} writingMode
- * @returns {SizeRect}
+ * Computes the position where the popup should be placed relative to the source content.
+ * @param {Rect[]} sourceRects The rectangles of the source content.
+ * @param {string} writingMode The CSS writing mode of the source text.
+ * @param {Rect} viewport The viewport that the popup can be placed within.
+ * @returns {SizeRect} The calculated rectangle for where to position the popup.
*/
_getPosition(sourceRects, writingMode, viewport) {
const scale = this._contentScale;
@@ -720,7 +722,15 @@ class Popup extends EventDispatcher {
}
/**
- * @returns {SizeRect}
+ * Computes the position where the popup should be placed for horizontal text.
+ * @param {Rect} sourceRect The rectangle of the source content.
+ * @param {number} frameWidth The preferred width of the frame.
+ * @param {number} frameHeight The preferred height of the frame.
+ * @param {Rect} viewport The viewport that the frame can be placed within.
+ * @param {number} horizontalOffset The horizontal offset from the source rect that the popup will be placed.
+ * @param {number} verticalOffset The vertical offset from the source rect that the popup will be placed.
+ * @param {boolean} preferBelow Whether or not the popup is preferred to be placed below the source content.
+ * @returns {SizeRect} The calculated rectangle for where to position the popup.
*/
_getPositionForHorizontalText(sourceRect, frameWidth, frameHeight, viewport, horizontalOffset, verticalOffset, preferBelow) {
const [left, width, after] = this._getConstrainedPosition(
@@ -743,7 +753,15 @@ class Popup extends EventDispatcher {
}
/**
- * @returns {SizeRect}
+ * Computes the position where the popup should be placed for vertical text.
+ * @param {Rect} sourceRect The rectangle of the source content.
+ * @param {number} frameWidth The preferred width of the frame.
+ * @param {number} frameHeight The preferred height of the frame.
+ * @param {Rect} viewport The viewport that the frame can be placed within.
+ * @param {number} horizontalOffset The horizontal offset from the source rect that the popup will be placed.
+ * @param {number} verticalOffset The vertical offset from the source rect that the popup will be placed.
+ * @param {boolean} preferRight Whether or not the popup is preferred to be placed to the right of the source content.
+ * @returns {SizeRect} The calculated rectangle for where to position the popup.
*/
_getPositionForVerticalText(sourceRect, frameWidth, frameHeight, viewport, horizontalOffset, verticalOffset, preferRight) {
const [left, width, after] = this._getConstrainedPositionBinary(
@@ -824,6 +842,11 @@ class Popup extends EventDispatcher {
return [position, size, after];
}
+ /**
+ * Gets the visual viewport.
+ * @param {boolean} useVisualViewport Whether or not the `window.visualViewport` should be used.
+ * @returns {Rect} The rectangle of the visual viewport.
+ */
_getViewport(useVisualViewport) {
const visualViewport = window.visualViewport;
if (visualViewport !== null && typeof visualViewport === 'object') {
@@ -887,8 +910,9 @@ class Popup extends EventDispatcher {
}
/**
- * @param {Rect[]} sourceRects
- * @returns {Rect}
+ * Computes the bounding rectangle for a set of rectangles.
+ * @param {Rect[]} sourceRects An array of rectangles.
+ * @returns {Rect} The bounding rectangle for all of the source rectangles.
*/
_getBoundingSourceRect(sourceRects) {
switch (sourceRects.length) {
@@ -907,10 +931,11 @@ class Popup extends EventDispatcher {
}
/**
- * @param {SizeRect} sizeRect
- * @param {Rect[]} sourceRects
- * @param {number} ignoreIndex
- * @returns {boolean}
+ * Checks whether or not a rectangle is overlapping any other rectangles.
+ * @param {SizeRect} sizeRect The rectangles to check for overlaps.
+ * @param {Rect[]} sourceRects The list of rectangles to compare against.
+ * @param {number} ignoreIndex The index of an item in `sourceRects` to ignore.
+ * @returns {boolean} `true` if `sizeRect` overlaps any one of `sourceRects`, excluding `sourceRects[ignoreIndex]`; `false` otherwise.
*/
_isOverlapping(sizeRect, sourceRects, ignoreIndex) {
const {left, top} = sizeRect;