@heartlandone/vega 2.75.0 → 2.76.0

package/dist/collection/helpers/slimmers/position-calculation/base-position-calculation-strategy.js

@@ -7,6 +7,17 @@ import ResponsiveFormatFacade from '../../formatter/responsive-map-formatter/res
  * calculate position
  */
 export class BasePositionCalculationStrategy extends VegaSlimmer {
+  /**
+   * Whether the controller should adjust/recompute position at this time.
+   *
+   * This hook allows strategies to avoid unnecessary work (for example, on scroll) by deciding
+   * whether a re-position is required.
+   *
+   * @returns {boolean} True when the controller should proceed with width/height/position adjustments.
+   */
+  shouldAdjustPosition() {
+    return true;
+  }
   /**
    * Get the position box.
    *
@@ -32,121 +43,46 @@ export class BasePositionCalculationStrategy extends VegaSlimmer {
     return positionBox;
   }
   /**
-   * "Get the width, height, and top position of an element."
-   *
-   * The function takes an element as an argument and returns an object with three properties: width,
-   * height, and top.
-   *
-   * Note: If element is hide, we should temporary change it to `block` to get the bounding client rect of element,
-   * After do that, this element will change to origin `hide`, if not, it will be contained in the calculate of `document.documentElement.scrollHeight`
-   *
-   * @returns {ElementBoundBox} An object with the width, height, and top properties of the element.
-   */
-  getElementBoundBox() {
-    const element = this.showConfig.appendableElement;
-    const isElementHide = element.classList.contains('vega-force-hidden');
-    if (isElementHide)
-      element.classList.remove('vega-force-hidden');
-    const elementRect = element.getBoundingClientRect();
-    if (isElementHide)
-      element.classList.add('vega-force-hidden');
-    return {
-      width: elementRect.width,
-      height: elementRect.height,
-      left: elementRect.left,
-      top: elementRect.top,
-    };
-  }
-  /**
-   * It takes a placement string or array of placements and returns an array of placements
-   * if given placement is single, we should completion the placements with the default {@link Placements}
-   * and make given placement as default.
-   * if given placement is array, we should use it directly, even it partial of {@link Placements}.
-   * if not placement give. we should use {@link Placements}.
-   *
-   * @returns {PlacementType[]} ordered placements.
-   */
-  getPlacements() {
-    const placement = this.showConfig.placement;
-    if (typeof placement === 'string') {
-      const partial = Placements.filter((direction) => direction !== placement);
-      return [placement, ...partial];
-    }
-    else if (Array.isArray(placement)) {
-      return placement;
-    }
-    else {
-      return [...Placements];
-    }
-  }
-  /**
-   * It returns acceptable alignments.
-   *
-   * @returns {PositionAlignmentType[]} acceptable alignments
-   */
-  getAlignments() {
-    const alignment = this.showConfig.alignment;
-    if (typeof alignment === 'string') {
-      const partial = Alignments.filter((item) => item !== alignment);
-      return [alignment, ...partial];
-    }
-    else if (Array.isArray(alignment)) {
-      return alignment;
-    }
-    else {
-      return [...Alignments];
-    }
-  }
-  /**
-   * It takes a placement, a target box, and a element box, and returns an element box
+   * Whether the alignment space is enough
    *
-   * @param {ElementBoundBox} elementBox - The position of the element element.
+   * @param {ElementScrollDimension} containerBox - The bounding box of the container element.
    * @param {ElementBoundBox} targetBox - The position of the target element.
-   * @param {PlacementType} placement - The placement of the element.
-   * @param {PositionAlignmentType} alignment - The alignment of the element
-   * @returns {ElementPositionBox} An object with top and left properties.
-   */
-  calculatePosition(elementBox, targetBox, placement, alignment) {
-    return {
-      top: this.calculateTop(elementBox, targetBox, placement, alignment),
-      left: this.calculateLeft(elementBox, targetBox, placement, alignment),
-    };
-  }
-  /**
-   * It returns the translocation of the element relative to the target element
-   *
-   * @param {PlacementType} placement - The suitable placement of the element.
-   * @returns {TranslocationType} A translocation object with X and Y properties.
+   * @param {ElementBoundBox} elementBox - The box of the element that we're trying to position.
+   * @param {PlacementType} placement - The placement of the element relative to the target.
+   * @param {PlacementType} alignment - The alignment of the element relative to the target.
+   * @returns {boolean} return true if it has enough space, otherwise false
    */
-  getTranslocationBox(placement) {
-    const originPlacement = Array.isArray(this.showConfig.placement)
-      ? this.showConfig.placement[0]
-      : this.showConfig.placement;
-    const translocation = this.getTranslocation();
-    const result = { X: 0, Y: 0 };
-    if (isTranslocationType(translocation)) {
-      let xValue = translocation.X;
-      let yValue = translocation.Y;
-      // If originPlacement and placement is not in same axis, it should reverse axis.
-      if ((originPlacement &&
-        ['left', 'right'].includes(originPlacement) &&
-        ['top', 'bottom'].includes(placement)) ||
-        (originPlacement &&
-          ['top', 'bottom'].includes(originPlacement) &&
-          ['left', 'right'].includes(placement))) {
-        xValue = translocation.Y;
-        yValue = translocation.X;
-      }
-      if (['bottom', 'top'].includes(placement)) {
-        result.Y = placement === 'top' ? -yValue : yValue;
-        result.X = xValue;
+  hasEnoughAlignmentSpace(containerBox, targetBox, elementBox, placement, alignment) {
+    if (['top', 'bottom'].includes(placement)) {
+      switch (alignment) {
+        case 'start': {
+          return targetBox.left + elementBox.width <= containerBox.width;
+        }
+        case 'center': {
+          return (targetBox.left >= (elementBox.width - targetBox.width) / 2 &&
+            targetBox.left + targetBox.width / 2 + elementBox.width / 2 <= containerBox.width);
+        }
+        case 'end': {
+          return targetBox.left + targetBox.width >= elementBox.width;
+        }
       }
-      if (['left', 'right'].includes(placement)) {
-        result.X = placement === 'left' ? -xValue : xValue;
-        result.Y = yValue;
+    }
+    if (['right', 'left'].includes(placement)) {
+      switch (alignment) {
+        case 'start': {
+          return targetBox.top + elementBox.height <= containerBox.height;
+        }
+        case 'center': {
+          return (targetBox.top >= (elementBox.height - targetBox.height) / 2 &&
+            targetBox.top + targetBox.height / 2 + elementBox.height / 2 <= containerBox.height);
+        }
+        case 'end': {
+          return targetBox.top + targetBox.height >= elementBox.height;
+        }
       }
     }
-    return result;
+    /* istanbul ignore next */
+    return false;
   }
   /**
    * Calculate the left position of the element
@@ -216,6 +152,24 @@ export class BasePositionCalculationStrategy extends VegaSlimmer {
         throw new Error(`Unexpected placement: ${placement}. Expected values are top, bottom, left, or right.`);
     }
   }
+  /**
+   * It returns acceptable alignments.
+   *
+   * @returns {PositionAlignmentType[]} acceptable alignments
+   */
+  getAlignments() {
+    const alignment = this.showConfig.alignment;
+    if (typeof alignment === 'string') {
+      const partial = Alignments.filter((item) => item !== alignment);
+      return [alignment, ...partial];
+    }
+    else if (Array.isArray(alignment)) {
+      return alignment;
+    }
+    else {
+      return [...Alignments];
+    }
+  }
   /**
    * It takes a list of placements and returns the first placement that has enough space to place the
    * element
@@ -240,6 +194,105 @@ export class BasePositionCalculationStrategy extends VegaSlimmer {
       return defaultPlacement;
     }
   }
+  /**
+   * "Get the width, height, and top position of an element."
+   *
+   * The function takes an element as an argument and returns an object with three properties: width,
+   * height, and top.
+   *
+   * Note: If element is hide, we should temporary change it to `block` to get the bounding client rect of element,
+   * After do that, this element will change to origin `hide`, if not, it will be contained in the calculate of `document.documentElement.scrollHeight`
+   *
+   * @returns {ElementBoundBox} An object with the width, height, and top properties of the element.
+   */
+  getElementBoundBox() {
+    const element = this.showConfig.appendableElement;
+    const isElementHide = element.classList.contains('vega-force-hidden');
+    if (isElementHide)
+      element.classList.remove('vega-force-hidden');
+    const elementRect = element.getBoundingClientRect();
+    if (isElementHide)
+      element.classList.add('vega-force-hidden');
+    return {
+      width: elementRect.width,
+      height: elementRect.height,
+      left: elementRect.left,
+      top: elementRect.top,
+    };
+  }
+  /**
+   * It takes a placement string or array of placements and returns an array of placements
+   * if given placement is single, we should completion the placements with the default {@link Placements}
+   * and make given placement as default.
+   * if given placement is array, we should use it directly, even it partial of {@link Placements}.
+   * if not placement give. we should use {@link Placements}.
+   *
+   * @returns {PlacementType[]} ordered placements.
+   */
+  getPlacements() {
+    const placement = this.showConfig.placement;
+    if (typeof placement === 'string') {
+      const partial = Placements.filter((direction) => direction !== placement);
+      return [placement, ...partial];
+    }
+    else if (Array.isArray(placement)) {
+      return placement;
+    }
+    else {
+      return [...Placements];
+    }
+  }
+  /**
+   * It takes a placement, a target box, and a element box, and returns an element box
+   *
+   * @param {ElementBoundBox} elementBox - The position of the element element.
+   * @param {ElementBoundBox} targetBox - The position of the target element.
+   * @param {PlacementType} placement - The placement of the element.
+   * @param {PositionAlignmentType} alignment - The alignment of the element
+   * @returns {ElementPositionBox} An object with top and left properties.
+   */
+  calculatePosition(elementBox, targetBox, placement, alignment) {
+    return {
+      top: this.calculateTop(elementBox, targetBox, placement, alignment),
+      left: this.calculateLeft(elementBox, targetBox, placement, alignment),
+    };
+  }
+  /**
+   * It returns the translocation of the element relative to the target element
+   *
+   * @param {PlacementType} placement - The suitable placement of the element.
+   * @returns {TranslocationType} A translocation object with X and Y properties.
+   */
+  getTranslocationBox(placement) {
+    const originPlacement = Array.isArray(this.showConfig.placement)
+      ? this.showConfig.placement[0]
+      : this.showConfig.placement;
+    const translocation = this.getTranslocation();
+    const result = { X: 0, Y: 0 };
+    if (isTranslocationType(translocation)) {
+      let xValue = translocation.X;
+      let yValue = translocation.Y;
+      // If originPlacement and placement is not in same axis, it should reverse axis.
+      if ((originPlacement &&
+        ['left', 'right'].includes(originPlacement) &&
+        ['top', 'bottom'].includes(placement)) ||
+        (originPlacement &&
+          ['top', 'bottom'].includes(originPlacement) &&
+          ['left', 'right'].includes(placement))) {
+        xValue = translocation.Y;
+        yValue = translocation.X;
+      }
+      if (['bottom', 'top'].includes(placement)) {
+        result.Y = placement === 'top' ? -yValue : yValue;
+        result.X = xValue;
+      }
+      if (['left', 'right'].includes(placement)) {
+        result.X = placement === 'left' ? -xValue : xValue;
+        result.Y = yValue;
+      }
+    }
+    return result;
+  }
   /**
    * It takes a list of alignments and returns the suitable one that has enough space to fit the element
    *
@@ -264,48 +317,6 @@ export class BasePositionCalculationStrategy extends VegaSlimmer {
       return defaultAlignment;
     }
   }
-  /**
-   * Whether the alignment space is enough
-   *
-   * @param {ElementScrollDimension} containerBox - The bounding box of the container element.
-   * @param {ElementBoundBox} targetBox - The position of the target element.
-   * @param {ElementBoundBox} elementBox - The box of the element that we're trying to position.
-   * @param {PlacementType} placement - The placement of the element relative to the target.
-   * @param {PlacementType} alignment - The alignment of the element relative to the target.
-   * @returns {boolean} return true if it has enough space, otherwise false
-   */
-  hasEnoughAlignmentSpace(containerBox, targetBox, elementBox, placement, alignment) {
-    if (['top', 'bottom'].includes(placement)) {
-      switch (alignment) {
-        case 'start': {
-          return targetBox.left + elementBox.width <= containerBox.width;
-        }
-        case 'center': {
-          return (targetBox.left >= (elementBox.width - targetBox.width) / 2 &&
-            targetBox.left + targetBox.width / 2 + elementBox.width / 2 <= containerBox.width);
-        }
-        case 'end': {
-          return targetBox.left + targetBox.width >= elementBox.width;
-        }
-      }
-    }
-    if (['right', 'left'].includes(placement)) {
-      switch (alignment) {
-        case 'start': {
-          return targetBox.top + elementBox.height <= containerBox.height;
-        }
-        case 'center': {
-          return (targetBox.top >= (elementBox.height - targetBox.height) / 2 &&
-            targetBox.top + targetBox.height / 2 + elementBox.height / 2 <= containerBox.height);
-        }
-        case 'end': {
-          return targetBox.top + targetBox.height >= elementBox.height;
-        }
-      }
-    }
-    /* istanbul ignore next */
-    return false;
-  }
   /**
    * If the placement is top or left, then the target's top or left position must be greater than or
    * equal to the element's height or width. If the placement is bottom or right, then the container's

package/dist/collection/helpers/slimmers/position-calculation/position-calculation-controller.js

@@ -17,6 +17,13 @@ export class PositionCalculationController extends VegaSlimmer {
     this.bodyPositionStrategy = new BodyPositionCalculationStrategy();
     this.screenPositionStrategy = new ScreenPositionCalculationStrategy();
   }
+  /**
+   * Clears any pending screen-position scroll animation frame callback.
+   * Call this when the appendable is hidden/destroyed.
+   */
+  clearScreenPositionScrollFrame() {
+    this.screenPositionStrategy.clearScrollFrame();
+  }
   /**
    * Sets the calculate postion strategy.
    */
@@ -31,6 +38,8 @@ export class PositionCalculationController extends VegaSlimmer {
    * @param {boolean} [usePreviousPlacement] - Should keep use previous placement and alignment.
    */
   adjustPosition(usePreviousPlacement) {
+    if (!this.positionStrategy.shouldAdjustPosition())
+      return;
     this.adjustWidth();
     this.adjustHeight();
     this.applyPosition(this.positionStrategy.getPosition(usePreviousPlacement));

package/dist/collection/helpers/slimmers/position-calculation/screen-position-calculation-strategy.js

@@ -6,10 +6,83 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { MapToComponentField } from 'vega-slimmer/core';
 import { BasePositionCalculationStrategy } from './base-position-calculation-strategy';
+import { ScreenScrollPositionUpdate } from './screen-scroll-position-update';
+import { tryGetDocument } from '../../../utils/try-get-document';
+import { FeatureFlag } from '../../feature-control/feature-flag-controller';
 /**
  * calculate position by screen container
  */
 export class ScreenPositionCalculationStrategy extends BasePositionCalculationStrategy {
+  constructor() {
+    super(...arguments);
+    this.scrollFrameRequestId = null;
+    this.usePreviousPlacement = false;
+    this.scrollPositionUpdateStrategy = new ScreenScrollPositionUpdate();
+  }
+  /**
+   * For screen-positioned appendable we may get a lot of scroll events.
+   * This hook throttles the check with requestAnimationFrame and only allows an adjust when
+   * the strategy determines we should update.
+   *
+   * @returns {boolean} True when controller should perform a position adjustment.
+   */
+  shouldAdjustPosition() {
+    if (this.scrollFrameRequestId !== null) {
+      return false;
+    }
+    if (!FeatureFlag.isEnabled('VEGA_ELEMENT_APPENDER.AUTO_PLACEMENT')) {
+      this.usePreviousPlacement = true;
+      return true;
+    }
+    if (!this.previousTargetRect) {
+      this.previousTargetRect = this.showConfig.target.getBoundingClientRect();
+      this.usePreviousPlacement = false;
+      return true;
+    }
+    /**
+     * This avoids doing expensive DOM reads on every scroll event, while still
+     * updating placement/alignment when the trigger moves and the appendable
+     * would be clipped by the viewport (auto placement).
+     *
+     * The below method is e2e-test covered in @see{module:the-screen-position-scroll-RAFCallback-trigger-as-expected}
+     */
+    /* istanbul ignore next */
+    this.scrollFrameRequestId = requestAnimationFrame(() => {
+      var _a;
+      this.scrollFrameRequestId = null;
+      let viewportWidth = window.innerWidth;
+      let viewportHeight = window.innerHeight;
+      if (this.showConfig.positionRelativeTo) {
+        const containerDom = (_a = tryGetDocument()) === null || _a === void 0 ? void 0 : _a.querySelector(this.showConfig.positionRelativeTo);
+        if (containerDom) {
+          viewportWidth = containerDom.getBoundingClientRect().width;
+          viewportHeight = containerDom.getBoundingClientRect().height;
+        }
+      }
+      const currentTargetRect = this.showConfig.target.getBoundingClientRect();
+      const appendableRect = this.showConfig.appendableElement.getBoundingClientRect();
+      const { shouldUpdate } = this.scrollPositionUpdateStrategy.shouldUpdatePosition({
+        currentTargetRect,
+        previousTargetRect: this.previousTargetRect,
+        appendableRect,
+        viewportWidth,
+        viewportHeight,
+      });
+      this.usePreviousPlacement = !shouldUpdate;
+      this.previousTargetRect = currentTargetRect;
+    });
+    return true;
+  }
+  /**
+   * Clears any pending scroll animation frame callback.
+   * Call this when popover is hidden/destroyed to avoid leaks and stale callbacks.
+   */
+  clearScrollFrame() {
+    if (this.scrollFrameRequestId !== null) {
+      cancelAnimationFrame(this.scrollFrameRequestId);
+      this.scrollFrameRequestId = null;
+    }
+  }
   /**
    * Get the position of the element in the container according to the target element and the placement
    * If give a translocation, it will apply the translocation to the result.
@@ -19,7 +92,8 @@ export class ScreenPositionCalculationStrategy extends BasePositionCalculationSt
    * returns an ElementPositionBox.
    */
   getPosition(usePreviousPlacement) {
-    const positionBox = usePreviousPlacement
+    const stayPlacement = usePreviousPlacement ? this.usePreviousPlacement : false;
+    const positionBox = stayPlacement
       ? this.getPositionBox([this.previousPositionBox.placement], [this.previousPositionBox.alignment])
       : this.getPositionBox();
     this.previousPositionBox = positionBox;
@@ -53,6 +127,43 @@ export class ScreenPositionCalculationStrategy extends BasePositionCalculationSt
       height: window.innerHeight,
     };
   }
+  /**
+   * Whether the alignment space is enough
+   *
+   * @param {ElementScrollDimension} containerBox - The bounding box of the container element.
+   * @param {ElementBoundBox} targetBox - The position of the target element.
+   * @param {ElementBoundBox} elementBox - The box of the element that we're trying to position.
+   * @param {PlacementType} placement - The placement of the element relative to the target.
+   * @param {PlacementType} alignment - The alignment of the element relative to the target.
+   * @returns {boolean} return true if it has enough space, otherwise false
+   */
+  hasEnoughAlignmentSpace(containerBox, targetBox, elementBox, placement, alignment) {
+    const left = this.calculateLeft(elementBox, targetBox, placement, alignment);
+    const top = this.calculateTop(elementBox, targetBox, placement, alignment);
+    return (left >= 0 &&
+      top >= 0 &&
+      left + elementBox.width <= containerBox.width &&
+      top + elementBox.height <= containerBox.height);
+  }
+  /**
+   * Screen-specific suitable placement selection.
+   * Tries to find a placement that has enough alignment space within the viewport first,
+   * otherwise falls back to the base strategy.
+   *
+   * @param {ElementScrollDimension} containerBox - The bounding box of the container.
+   * @param {ElementBoundBox} elementBox - The box of the element to place.
+   * @param {ElementBoundBox} targetBox - The box of the target element.
+   * @param {PlacementType[]} placements - Ordered list of placements to try.
+   * @returns {PlacementType} The chosen placement.
+   */
+  getSuitablePlacement(containerBox, elementBox, targetBox, placements) {
+    const alignments = this.getAlignments();
+    const suitablePlacement = placements.find((placement) => alignments.some((alignment) => this.hasEnoughAlignmentSpace(containerBox, targetBox, elementBox, placement, alignment)));
+    if (suitablePlacement) {
+      return suitablePlacement;
+    }
+    return super.getSuitablePlacement(containerBox, elementBox, targetBox, placements);
+  }
 }
 __decorate([
   MapToComponentField()

package/dist/collection/helpers/slimmers/position-calculation/screen-scroll-position-update.js

@@ -0,0 +1,53 @@
+/**
+ * Updates position on scroll When the target rect changes, we recompute placement/alignment.
+ */
+export class ScreenScrollPositionUpdate {
+  constructor() {
+    this.viewportWidth = window.innerWidth;
+    this.viewportHeight = window.innerHeight;
+  }
+  /**
+   * Determines whether the appendable element's position should update on scroll.
+   *
+   * @param {ScrollPositionUpdateStrategyContext} context - Current/previous rectangles plus viewport size.
+   * @returns {ScrollPositionUpdateDecision} Decision that indicates whether to recompute position.
+   */
+  shouldUpdatePosition(context) {
+    const { previousTargetRect, currentTargetRect, appendableRect, viewportWidth, viewportHeight, } = context;
+    this.viewportWidth = viewportWidth;
+    this.viewportHeight = viewportHeight;
+    const targetChanged = !previousTargetRect ||
+      currentTargetRect.left !== previousTargetRect.left ||
+      currentTargetRect.top !== previousTargetRect.top;
+    const isTargetWithinViewport = !this.isRectOutsideViewport(currentTargetRect);
+    const isAppendableNotEntirelyInViewport = !this.isRectEntirelyWithinViewport(appendableRect);
+    return {
+      shouldUpdate: targetChanged && isTargetWithinViewport && isAppendableNotEntirelyInViewport,
+    };
+  }
+  /**
+   * Whether the rect is fully within the viewport bounds.
+   *
+   * @param {DOMRect} rect - The DOMRect to check.
+   * @returns {boolean} True when rect is fully within the viewport.
+   */
+  isRectEntirelyWithinViewport(rect) {
+    return (rect.left >= 0 &&
+      rect.top >= 0 &&
+      rect.right <= this.viewportWidth &&
+      rect.bottom <= this.viewportHeight);
+  }
+  /**
+   * Whether the element is fully outside the viewport.
+   * If true, the rect has "disappeared" from the viewport.
+   *
+   * @param {DOMRect} rect - The DOMRect to check.
+   * @returns {boolean} True when rect is completely outside viewport bounds.
+   */
+  isRectOutsideViewport(rect) {
+    return (rect.right <= 0 ||
+      rect.bottom <= 0 ||
+      rect.left >= this.viewportWidth ||
+      rect.top >= this.viewportHeight);
+  }
+}