@globalpayments/vega 2.77.0 → 2.77.1

package/dist/collection/helpers/slimmers/element-appender/element-appender-slimmer.js

@@ -173,6 +173,7 @@ export class ElementAppenderSlimmer extends VegaSlimmer {
   show() {
     this.elementAppender && this.elementAppender.show();
     this[this.isDropdownShowName] = true;
+    this.setAriaOwns();
   }
   hide() {
     this.elementAppender && this.elementAppender.hide();
@@ -182,6 +183,7 @@ export class ElementAppenderSlimmer extends VegaSlimmer {
     });
   }
   destroy() {
+    this.removeAriaOwns();
     this.destroyElementAppender();
     this[this.isDropdownShowName] = false;
   }
@@ -264,6 +266,31 @@ export class ElementAppenderSlimmer extends VegaSlimmer {
       return new NoneTriggerStrategy();
     }
   }
+  /**
+   * Sets `ariaOwnsElements` on the target element to reference the appendable element directly.
+   * Uses the Element Reflection API which works across shadow DOM boundaries by using
+   * direct element references instead of IDREF strings.
+   * This ensures screen readers (e.g. VoiceOver) can navigate to the portal-appended
+   * content immediately after the trigger, rather than at the end of the document.
+   */
+  setAriaOwns() {
+    if (this.showConfig) {
+      const target = this.showConfig.target;
+      const appendableElement = this.showConfig.appendableElement;
+      if (target && appendableElement) {
+        target.ariaOwnsElements = [appendableElement];
+      }
+    }
+  }
+  /**
+   * Removes `ariaOwnsElements` from the target element when the popup is hidden or destroyed.
+   */
+  removeAriaOwns() {
+    var _a;
+    if ((_a = this.showConfig) === null || _a === void 0 ? void 0 : _a.target) {
+      this.showConfig.target.ariaOwnsElements = [];
+    }
+  }
 }
 ElementAppenderSlimmer.DELAY_HIDE_TIME = 100;
 __decorate([

package/dist/collection/helpers/slimmers/element-appender/test/element-appender-slimmer.test.js

@@ -568,4 +568,54 @@ describe('ElementAppender slimmer test suite', () => {
       expect(child2.appendableElement).toHaveClass('vega-force-hidden');
     });
   });
+  describe('AriaOwns management', () => {
+    test('should set ariaOwnsElements on target when show is called', () => {
+      const mockedComponent = new MockedComponent();
+      const target = new MockHTMLElement('body', 'div');
+      const appendableElement = new MockHTMLElement('body', 'div');
+      appendableElement.classList.add('vega-force-hidden');
+      mockedComponent.target = target;
+      mockedComponent.appendableElement = appendableElement;
+      mockedComponent.componentDidLoad();
+      mockedComponent.show();
+      expect(target.ariaOwnsElements).toEqual([
+        appendableElement,
+      ]);
+    });
+    test('should remove ariaOwnsElements from target when destroy is called', () => {
+      const mockedComponent = new MockedComponent();
+      const target = new MockHTMLElement('body', 'div');
+      const appendableElement = new MockHTMLElement('body', 'div');
+      appendableElement.classList.add('vega-force-hidden');
+      mockedComponent.target = target;
+      mockedComponent.appendableElement = appendableElement;
+      mockedComponent.componentDidLoad();
+      mockedComponent.show();
+      expect(target.ariaOwnsElements).toEqual([
+        appendableElement,
+      ]);
+      mockedComponent.destroy();
+      expect(target.ariaOwnsElements).toEqual([]);
+    });
+    test('should not throw when show is called without showConfig', () => {
+      const mockedComponent = new MockedComponent();
+      mockedComponent.target = null;
+      mockedComponent.appendableElement = null;
+      spyOn(LogUtility, 'error');
+      mockedComponent.componentDidLoad();
+      expect(() => mockedComponent.show()).not.toThrow();
+    });
+    test('should not throw when destroy is called without target', () => {
+      const mockedComponent = new MockedComponent();
+      mockedComponent.target = null;
+      mockedComponent.appendableElement = null;
+      spyOn(LogUtility, 'error');
+      mockedComponent.componentDidLoad();
+      expect(() => mockedComponent.destroy()).not.toThrow();
+    });
+    test('should not throw when destroy is called before componentDidLoad', () => {
+      const mockedComponent = new MockedComponent();
+      expect(() => mockedComponent.destroy()).not.toThrow();
+    });
+  });
 });

package/dist/collection/helpers/slimmers/mutation-observer/aria-attributes-value-mapper.js

@@ -102,7 +102,7 @@ export class AriaAttributesValueMapper extends MutationObserverSlimmer {
         }
       }
       if (finalValue === null || finalValue === undefined || String(finalValue).trim() === '') {
-        finalValue = defaultValue !== null && defaultValue !== void 0 ? defaultValue : '';
+        finalValue = defaultValue;
       }
       try {
         if (String(finalValue).trim() === '') {
@@ -110,8 +110,15 @@ export class AriaAttributesValueMapper extends MutationObserverSlimmer {
           return;
         }
         const existing = target.getAttribute(ariaAttr);
-        if (existing !== finalValue) {
-          target.setAttribute(ariaAttr, finalValue);
+        if (finalValue === null || finalValue === undefined) {
+          if (existing !== null) {
+            target.removeAttribute(ariaAttr);
+          }
+          return;
+        }
+        const stringValue = String(finalValue);
+        if (existing !== stringValue) {
+          target.setAttribute(ariaAttr, stringValue);
         }
       }
       catch (e) {

package/dist/collection/helpers/slimmers/mutation-observer/data-tab-index-value-mapper.js

@@ -0,0 +1,80 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { MapToComponentMethod } from 'vega-slimmer/core';
+import { MutationObserverSlimmer } from './mutation-observer-slimmer';
+/**
+ * Maps host data-tabindex to inner native input tabindex.
+ */
+export class DataTabIndexValueMapper extends MutationObserverSlimmer {
+  /**
+   * Constructor for DataTabIndexValueMapper
+   *
+   * @param {() => HTMLElement} targetGetter - Function to get the target HTMLElement
+   */
+  constructor(targetGetter) {
+    super({
+      options: { attributes: true, attributeFilter: [DataTabIndexValueMapper.OBSERVED_ATTRIBUTE] },
+      // eslint-disable-next-line jsdoc/require-jsdoc
+      callback: () => {
+        this.performMapping();
+      },
+    });
+    this.targetGetter = targetGetter;
+  }
+  /**
+   * Component lifecycle - [componentDidLoad]
+   */
+  componentDidLoad() {
+    this.performMapping();
+    super.componentDidLoad && super.componentDidLoad();
+  }
+  /**
+   * Component lifecycle - [componentDidRender]
+   */
+  componentDidRender() {
+    this.performMapping();
+  }
+  /**
+   * Performs the mapping of host data-tabindex to target element's tabindex.
+   * If the host attribute value is null, undefined, or empty string, it removes the tabindex attribute from the target.
+   * Otherwise, it sets the target's tabindex to the host attribute value.
+   */
+  performMapping() {
+    const target = this.targetGetter ? this.targetGetter() : null;
+    if (!target)
+      return;
+    const hostValue = this.host.getAttribute(DataTabIndexValueMapper.OBSERVED_ATTRIBUTE);
+    if (this.shouldRemoveTabIndex(hostValue)) {
+      target.removeAttribute('tabindex');
+      return;
+    }
+    const tabIndexValue = String(hostValue);
+    if (target.getAttribute('tabindex') !== tabIndexValue) {
+      target.setAttribute('tabindex', tabIndexValue);
+    }
+  }
+  /**
+   * Determines whether the tabindex attribute should be removed from the target element.
+   *
+   * @param {string | null} hostValue - The value of the host element's data-tabindex attribute
+   * @returns {boolean} True if the tabindex should be removed, false otherwise
+   */
+  shouldRemoveTabIndex(hostValue) {
+    if (hostValue === null || hostValue === undefined) {
+      return true;
+    }
+    const normalizedValue = String(hostValue).trim().toLowerCase();
+    return normalizedValue === '' || normalizedValue === 'null' || normalizedValue === 'undefined';
+  }
+}
+DataTabIndexValueMapper.OBSERVED_ATTRIBUTE = 'data-tabindex';
+__decorate([
+  MapToComponentMethod('componentDidLoad')
+], DataTabIndexValueMapper.prototype, "componentDidLoad", null);
+__decorate([
+  MapToComponentMethod('componentDidRender')
+], DataTabIndexValueMapper.prototype, "componentDidRender", null);

package/dist/collection/helpers/slimmers/mutation-observer/test/aria-attributes-value-mapper.test.js

@@ -168,7 +168,7 @@ describe('AriaAttributesValueMapper', () => {
       comp.componentDidLoad();
     }).not.toThrow();
   });
-  it('should set empty string when no defaultValue provided', () => {
+  it('should omit aria attribute when no defaultValue provided', () => {
     const comp = new MockedComponent();
     const button = document.createElement('button');
     // no dependencies present on host and no defaultValue in map
@@ -177,8 +177,47 @@ describe('AriaAttributesValueMapper', () => {
     }));
     comp.connectedCallback();
     comp.componentDidLoad();
-    // should set attribute to empty string when no defaultValue provided
-    expect(button.getAttribute('aria-label')).toBe(null);
+    expect(button.hasAttribute('aria-label')).toBeFalsy();
+  });
+  it('should omit aria attribute when defaultValue is null', () => {
+    const comp = new MockedComponent();
+    const button = document.createElement('button');
+    comp.setMapper(new AriaAttributesValueMapper(() => button, {
+      'aria-label': {
+        dependency: ['data-aria-label', 'label'],
+        defaultValue: null,
+      },
+    }));
+    comp.connectedCallback();
+    comp.componentDidLoad();
+    expect(button.hasAttribute('aria-label')).toBeFalsy();
+  });
+  it('should omit aria attribute when defaultValue is undefined', () => {
+    const comp = new MockedComponent();
+    const button = document.createElement('button');
+    comp.setMapper(new AriaAttributesValueMapper(() => button, {
+      'aria-label': {
+        dependency: ['data-aria-label', 'label'],
+        defaultValue: undefined,
+      },
+    }));
+    comp.connectedCallback();
+    comp.componentDidLoad();
+    expect(button.hasAttribute('aria-label')).toBeFalsy();
+  });
+  it('should remove existing aria attribute when resolved value is undefined', () => {
+    const comp = new MockedComponent();
+    const button = document.createElement('button');
+    button.setAttribute('aria-label', 'legacy-value');
+    comp.setMapper(new AriaAttributesValueMapper(() => button, {
+      'aria-label': {
+        dependency: ['data-aria-label', 'label'],
+        defaultValue: undefined,
+      },
+    }));
+    comp.connectedCallback();
+    comp.componentDidLoad();
+    expect(button.hasAttribute('aria-label')).toBeFalsy();
   });
   it('should handle empty mutations array (pass undefined to performMapping)', () => {
     const comp = new MockedComponent();
@@ -193,4 +232,17 @@ describe('AriaAttributesValueMapper', () => {
     MockedMutationObserver.mock.instances[0].trigger([]);
     expect(button.getAttribute('aria-label')).toBe('test');
   });
+  it('should be null for aria attribute when defaultValue is empty string', () => {
+    const comp = new MockedComponent();
+    const button = document.createElement('button');
+    comp.setMapper(new AriaAttributesValueMapper(() => button, {
+      'aria-label': {
+        dependency: ['data-aria-label', 'label'],
+        defaultValue: '',
+      },
+    }));
+    comp.connectedCallback();
+    comp.componentDidLoad();
+    expect(button.getAttribute('aria-label')).toBe(null);
+  });
 });

package/dist/collection/helpers/slimmers/mutation-observer/test/data-tab-index-value-mapper.test.js

@@ -0,0 +1,120 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { MockHTMLElement } from '@stencil/core/mock-doc';
+import { InjectVegaSlimmer } from 'vega-slimmer/core';
+import { MockedMutationObserver } from '../../../../utils/spec-utils';
+import { DataTabIndexValueMapper } from '../data-tab-index-value-mapper';
+describe('DataTabIndexValueMapper', () => {
+  beforeEach(() => {
+    global.MutationObserver = MockedMutationObserver;
+    MockedMutationObserver.mockClear();
+  });
+  class MockedComponent {
+    constructor() {
+      this.host = new MockHTMLElement('body', 'mocked-component');
+    }
+    connectedCallback() {
+      return;
+    }
+    componentDidLoad() {
+      return;
+    }
+    setMapper(mapper) {
+      this.dataTabIndexValueMapper = mapper;
+    }
+  }
+  __decorate([
+    InjectVegaSlimmer()
+  ], MockedComponent.prototype, "dataTabIndexValueMapper", void 0);
+  it('should map host data-tabindex to native input tabindex on load', () => {
+    const comp = new MockedComponent();
+    const input = document.createElement('input');
+    comp.host.setAttribute('data-tabindex', '-1');
+    comp.setMapper(new DataTabIndexValueMapper(() => input));
+    comp.connectedCallback();
+    comp.componentDidLoad();
+    expect(input.getAttribute('tabindex')).toBe('-1');
+    expect(MockedMutationObserver.mock.instances[0].observe).toHaveBeenCalledWith(comp.host, {
+      attributes: true,
+      attributeFilter: ['data-tabindex'],
+    });
+  });
+  it('should update native input tabindex when host data-tabindex changes', () => {
+    const comp = new MockedComponent();
+    const input = document.createElement('input');
+    comp.host.setAttribute('data-tabindex', '0');
+    comp.setMapper(new DataTabIndexValueMapper(() => input));
+    comp.connectedCallback();
+    comp.componentDidLoad();
+    expect(input.getAttribute('tabindex')).toBe('0');
+    comp.host.setAttribute('data-tabindex', '-1');
+    MockedMutationObserver.mock.instances[0].trigger([{ attributeName: 'data-tabindex', oldValue: '0' }]);
+    expect(input.getAttribute('tabindex')).toBe('-1');
+  });
+  it('should remove native input tabindex when host data-tabindex is empty or missing', () => {
+    const comp = new MockedComponent();
+    const input = document.createElement('input');
+    comp.host.setAttribute('data-tabindex', '0');
+    comp.setMapper(new DataTabIndexValueMapper(() => input));
+    comp.connectedCallback();
+    comp.componentDidLoad();
+    expect(input.getAttribute('tabindex')).toBe('0');
+    comp.host.setAttribute('data-tabindex', '');
+    MockedMutationObserver.mock.instances[0].trigger([{ attributeName: 'data-tabindex', oldValue: '0' }]);
+    expect(input.hasAttribute('tabindex')).toBeFalsy();
+    comp.host.removeAttribute('data-tabindex');
+    MockedMutationObserver.mock.instances[0].trigger([{ attributeName: 'data-tabindex', oldValue: '' }]);
+    expect(input.hasAttribute('tabindex')).toBeFalsy();
+  });
+  it('should remove native input tabindex when host data-tabindex is "null" or "undefined" string', () => {
+    const comp = new MockedComponent();
+    const input = document.createElement('input');
+    comp.host.setAttribute('data-tabindex', '0');
+    comp.setMapper(new DataTabIndexValueMapper(() => input));
+    comp.connectedCallback();
+    comp.componentDidLoad();
+    expect(input.getAttribute('tabindex')).toBe('0');
+    comp.host.setAttribute('data-tabindex', 'null');
+    MockedMutationObserver.mock.instances[0].trigger([{ attributeName: 'data-tabindex', oldValue: '0' }]);
+    expect(input.hasAttribute('tabindex')).toBeFalsy();
+    comp.host.setAttribute('data-tabindex', 'undefined');
+    MockedMutationObserver.mock.instances[0].trigger([
+      { attributeName: 'data-tabindex', oldValue: 'null' },
+    ]);
+    expect(input.hasAttribute('tabindex')).toBeFalsy();
+  });
+  it('should return early when targetGetter returns null', () => {
+    const comp = new MockedComponent();
+    comp.host.setAttribute('data-tabindex', '0');
+    comp.setMapper(new DataTabIndexValueMapper(() => null));
+    expect(() => {
+      comp.connectedCallback();
+      comp.componentDidLoad();
+      MockedMutationObserver.mock.instances[0].trigger([
+        { attributeName: 'data-tabindex', oldValue: null },
+      ]);
+    }).not.toThrow();
+  });
+  it('should return early when targetGetter field is null', () => {
+    const comp = new MockedComponent();
+    const input = document.createElement('input');
+    comp.host.setAttribute('data-tabindex', '1');
+    const mapper = new DataTabIndexValueMapper(() => input);
+    // force the private readonly field to null so ternary fallback branch is executed
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    mapper.targetGetter = null;
+    comp.setMapper(mapper);
+    expect(() => {
+      comp.connectedCallback();
+      comp.componentDidLoad();
+      MockedMutationObserver.mock.instances[0].trigger([
+        { attributeName: 'data-tabindex', oldValue: null },
+      ]);
+    }).not.toThrow();
+    expect(input.hasAttribute('tabindex')).toBeFalsy();
+  });
+});

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

@@ -27,19 +27,24 @@ export class BasePositionCalculationStrategy extends VegaSlimmer {
    * returns an ElementPositionBox.
    */
   getPositionBox(placement, alignment) {
-    const placements = placement || this.getPlacements();
-    const alignments = alignment || this.getAlignments();
+    const placements = placement && placement.length > 0 ? placement : this.getPlacements();
+    const alignments = alignment && alignment.length > 0 ? alignment : this.getAlignments();
     const targetBox = this.getTargetBoundBox();
     const elementBox = this.getElementBoundBox();
     const containerBox = this.getElementScrollDimension();
     const suitablePlacement = this.getSuitablePlacement(containerBox, elementBox, targetBox, placements);
-    const suitableAlignment = this.getSuitableAlignment(containerBox, elementBox, targetBox, suitablePlacement, alignments);
-    const positionBox = this.calculatePosition(elementBox, targetBox, suitablePlacement, suitableAlignment);
-    const translocationBox = this.getTranslocationBox(suitablePlacement);
+    const activePlacement = suitablePlacement || placements[0];
+    const suitableAlignment = this.getSuitableAlignment(containerBox, elementBox, targetBox, activePlacement, alignments);
+    const activeAlignment = suitableAlignment || alignments[0];
+    const positionBox = this.calculatePosition(elementBox, targetBox, activePlacement, activeAlignment);
+    const translocationBox = this.getTranslocationBox(activePlacement);
     positionBox.placement = suitablePlacement;
     positionBox.alignment = suitableAlignment;
     positionBox.left += translocationBox.X;
     positionBox.top += translocationBox.Y;
+    if (!this.showConfig.positionRelativeTo) {
+      this.adjustPositionForViewport(positionBox, elementBox, targetBox, activePlacement);
+    }
     return positionBox;
   }
   /**
@@ -178,7 +183,7 @@ export class BasePositionCalculationStrategy extends VegaSlimmer {
    * @param {ElementBoundBox} elementBox - The box of the element to be placed.
    * @param {ElementBoundBox} targetBox - The box of the target element.
    * @param {PlacementType[]} placements - The placements that we want to try.
-   * @returns {PlacementType} A function that takes in a containerBox, elementBox, targetBox, placements, and element.
+   * @returns {Nullable<PlacementType>} A function that takes in a containerBox, elementBox, targetBox, placements, and element.
    */
   getSuitablePlacement(containerBox, elementBox, targetBox, placements) {
     const defaultPlacement = placements[0];
@@ -191,7 +196,7 @@ export class BasePositionCalculationStrategy extends VegaSlimmer {
                 No enough space found for placing element and we will keep using the defined placement:
                 ${defaultPlacement}
             `);
-      return defaultPlacement;
+      return null;
     }
   }
   /**
@@ -257,6 +262,115 @@ export class BasePositionCalculationStrategy extends VegaSlimmer {
       left: this.calculateLeft(elementBox, targetBox, placement, alignment),
     };
   }
+  /**
+   * Keeps the vertical position within the visible viewport
+   *
+   * @param {number} top - The calculated top position.
+   * @param {number} elementHeight - The height of the element.
+   * @returns {number} The top position constrained to the viewport.
+   */
+  keepVerticallyInView(top, elementHeight) {
+    return Math.max(0, Math.min(top, window.innerHeight - elementHeight));
+  }
+  /**
+   * Keeps the horizontal position within the visible viewport
+   *
+   * @param {number} left - The calculated left position.
+   * @param {number} elementWidth - The width of the element.
+   * @returns {number} The left position constrained to the viewport.
+   */
+  keepHorizontallyInView(left, elementWidth) {
+    return Math.max(0, Math.min(left, window.innerWidth - elementWidth));
+  }
+  /**
+   * Checks if the target element is visible in the viewport
+   *
+   * @param {ElementBoundBox} targetBox - The bounding box of the target element.
+   * @returns {boolean} True if target is visible in viewport.
+   */
+  isTargetInView(targetBox) {
+    const innerHeight = window.innerHeight;
+    const innerWidth = window.innerWidth;
+    const targetBottom = targetBox.top + targetBox.height;
+    const targetRight = targetBox.left + targetBox.width;
+    return (targetBox.top <= innerHeight &&
+      targetBottom >= 0 &&
+      targetBox.left <= innerWidth &&
+      targetRight >= 0);
+  }
+  /**
+   * Corrects `positionBox` so the element stays within the viewport after translocation.
+   * Only runs when the target is visible; skips correction entirely if the target has
+   * scrolled out of view so the element simply follows it.
+   *
+   * @param {ElementPositionBox} positionBox - The final position box to adjust (mutated in place).
+   * @param {ElementBoundBox} elementBox - Dimensions of the positioned element.
+   * @param {ElementBoundBox} targetBox - Bounding box of the target element.
+   * @param {PlacementType} placement - Active placement used to select the correction axis.
+   */
+  adjustPositionForViewport(positionBox, elementBox, targetBox, placement) {
+    if (!this.isTargetInView(targetBox)) {
+      return;
+    }
+    if (placement === 'top' || placement === 'bottom') {
+      positionBox.top = this.adjustForVerticalOverflow(positionBox.top, elementBox.height, targetBox.height);
+    }
+    else if (placement === 'left' || placement === 'right') {
+      positionBox.left = this.adjustForHorizontalOverflow(positionBox.left, elementBox.width, targetBox.width);
+    }
+    positionBox.top = this.keepVerticallyInView(positionBox.top, elementBox.height);
+    positionBox.left = this.keepHorizontallyInView(positionBox.left, elementBox.width);
+  }
+  /**
+   * Nudges `top` so the element stays within the viewport vertically.
+   * Only corrects when the overflow is less than `targetHeight` to keep the element
+   * visually anchored to its target; larger overflows are handled by `keepVerticallyInView`.
+   *
+   * @param {number} top - The calculated top position.
+   * @param {number} elementHeight - Height of the positioned element.
+   * @param {number} targetHeight - Height of the target, used as the max correctable overflow.
+   * @returns {number} The adjusted top position.
+   */
+  adjustForVerticalOverflow(top, elementHeight, targetHeight) {
+    // Pixels the element bleeds past the bottom of the viewport (positive = overflow).
+    const overflowBottom = top + elementHeight - window.innerHeight;
+    // Pixels the element bleeds past the top of the viewport (positive = overflow).
+    const overflowTop = -top;
+    // Only nudge when overflow is smaller than targetHeight; larger overflows are left to
+    // keepVerticallyInView to hard-clamp, since nudging that far would detach from the target.
+    if (overflowBottom > 0 && overflowBottom < targetHeight) {
+      return top - overflowBottom; // shift up until bottom edge is flush with viewport bottom
+    }
+    if (overflowTop > 0 && overflowTop < targetHeight) {
+      return top + overflowTop; // shift down until top edge is flush with viewport top
+    }
+    return top;
+  }
+  /**
+   * Nudges `left` so the element stays within the viewport horizontally.
+   * Only corrects when the overflow is less than `targetWidth` to keep the element
+   * visually anchored to its target; larger overflows are handled by `keepHorizontallyInView`.
+   *
+   * @param {number} left - The calculated left position.
+   * @param {number} elementWidth - Width of the positioned element.
+   * @param {number} targetWidth - Width of the target, used as the max correctable overflow.
+   * @returns {number} The adjusted left position.
+   */
+  adjustForHorizontalOverflow(left, elementWidth, targetWidth) {
+    // Pixels the element bleeds past the right edge of the viewport (positive = overflow).
+    const overflowRight = left + elementWidth - window.innerWidth;
+    // Pixels the element bleeds past the left edge of the viewport (positive = overflow).
+    const overflowLeft = -left;
+    // Only nudge when overflow is smaller than targetWidth; larger overflows are left to
+    // keepHorizontallyInView to hard-clamp, since nudging that far would detach from the target.
+    if (overflowRight > 0 && overflowRight < targetWidth) {
+      return left - overflowRight; // shift left until right edge is flush with viewport right
+    }
+    if (overflowLeft > 0 && overflowLeft < targetWidth) {
+      return left + overflowLeft; // shift right until left edge is flush with viewport left
+    }
+    return left;
+  }
   /**
    * It returns the translocation of the element relative to the target element
    *
@@ -301,7 +415,7 @@ export class BasePositionCalculationStrategy extends VegaSlimmer {
    * @param {ElementBoundBox} targetBox - The box of the element that the element to be positioned is aligned to.
    * @param {PlacementType} placement - The placement of the element relative to the target.
    * @param {PositionAlignmentType[]} alignments - An array of alignments to try.
-   * @returns {PositionAlignmentType} the alignment that is suitable for the element.
+   * @returns {Nullable<PositionAlignmentType>} the alignment that is suitable for the element.
    */
   getSuitableAlignment(containerBox, elementBox, targetBox, placement, alignments) {
     const defaultAlignment = alignments[0];
@@ -314,7 +428,7 @@ export class BasePositionCalculationStrategy extends VegaSlimmer {
                 No enough space found for placing element and we will keep using the defined alignment:
                 ${defaultAlignment}
             `);
-      return defaultAlignment;
+      return null;
     }
   }
   /**

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

@@ -63,10 +63,20 @@ export class PositionCalculationController extends VegaSlimmer {
     }
     appendableElement.style.left = `${positionBox.left}px`;
     appendableElement.style.top = `${positionBox.top}px`;
-    appendableElement.classList.remove('vega-placement-left', 'vega-placement-right', 'vega-placement-top', 'vega-placement-bottom');
-    appendableElement.classList.remove('vega-alignment-start', 'vega-alignment-center', 'vega-alignment-end');
-    appendableElement.classList.add(`vega-placement-${positionBox.placement}`);
-    appendableElement.classList.add(`vega-alignment-${positionBox.alignment}`);
+    appendableElement.classList.remove('vega-placement-left', 'vega-placement-right', 'vega-placement-top', 'vega-placement-bottom', 'vega-no-suitable-placement');
+    appendableElement.classList.remove('vega-alignment-start', 'vega-alignment-center', 'vega-alignment-end', 'vega-no-suitable-alignment');
+    if (positionBox.placement) {
+      appendableElement.classList.add(`vega-placement-${positionBox.placement}`);
+    }
+    else {
+      appendableElement.classList.add(`vega-no-suitable-placement`);
+    }
+    if (positionBox.alignment) {
+      appendableElement.classList.add(`vega-alignment-${positionBox.alignment}`);
+    }
+    else {
+      appendableElement.classList.add(`vega-no-suitable-alignment`);
+    }
   }
   /**
    * It sets the width of the appendable element to the width of the target element if the

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

@@ -9,6 +9,7 @@ import { BasePositionCalculationStrategy } from './base-position-calculation-str
 import { ScreenScrollPositionUpdate } from './screen-scroll-position-update';
 import { tryGetDocument } from '../../../utils/try-get-document';
 import { FeatureFlag } from '../../feature-control/feature-flag-controller';
+import { isNonNullable } from '../../../types/type-guard';
 /**
  * calculate position by screen container
  */
@@ -93,9 +94,17 @@ export class ScreenPositionCalculationStrategy extends BasePositionCalculationSt
    */
   getPosition(usePreviousPlacement) {
     const stayPlacement = usePreviousPlacement ? this.usePreviousPlacement : false;
-    const positionBox = stayPlacement
-      ? this.getPositionBox([this.previousPositionBox.placement], [this.previousPositionBox.alignment])
-      : this.getPositionBox();
+    let positionBox;
+    if (stayPlacement) {
+      positionBox = this.getPositionBox([this.previousPositionBox.placement].filter(isNonNullable), [this.previousPositionBox.alignment].filter(isNonNullable));
+      if (!FeatureFlag.isEnabled('VEGA_ELEMENT_APPENDER.AUTO_PLACEMENT')) {
+        positionBox.placement = this.previousPositionBox.placement;
+        positionBox.alignment = this.previousPositionBox.alignment;
+      }
+    }
+    else {
+      positionBox = this.getPositionBox();
+    }
     this.previousPositionBox = positionBox;
     return positionBox;
   }
@@ -154,7 +163,7 @@ export class ScreenPositionCalculationStrategy extends BasePositionCalculationSt
    * @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.
+   * @returns {Nullable<PlacementType>} The chosen placement.
    */
   getSuitablePlacement(containerBox, elementBox, targetBox, placements) {
     const alignments = this.getAlignments();