@globalpayments/vega 2.77.0 → 2.77.1

package/dist/types/components/vega-app-header-button/types.d.ts

@@ -1,4 +1,5 @@
 import { BackgroundColorsTokenType, TextColorsTokenType } from '../../types/design-token.type';
+import { ResponsiveType, SizeType } from '../../types/ui.type';
 
 /**
  * Configuration options for the dropdown used by the app header button.
@@ -60,3 +61,20 @@ export type VegaAppHeaderAvatarConfig = {
  * Allowed size values for the app header button.
  */
 export type VegaAppHeaderButtonSize = 'default' | 'small';
+
+/**
+ * Settings for the label displayed in the app header button.
+ *
+ * Allows providing configuration options for the label, such as max width and display rules.
+ */
+export type VegaAppHeaderLabelConfig = {
+	/**
+	 * Maximum width of the label.
+	 */
+	maxWidth?: ResponsiveType<SizeType>;
+
+	/**
+	 * Rule for how to display the label when it exceeds the maximum width. Can be 'ellipsis' or 'newline'.
+	 */
+	displayRule?: 'newline' | 'ellipsis';
+};

package/dist/types/components/vega-app-header-button/vega-app-header-button.d.ts

@@ -2,7 +2,7 @@ import { EventEmitter } from '../../stencil-public-runtime';
 import { BreakpointsTokenType } from '../../types/design-token.type';
 import { ResponsiveType } from '../../types/ui.type';
 import { GlobalSlimmers } from '../../vega-slimmer/vega-slimmer-core';
-import { VegaAppHeaderAvatarConfig, VegaAppHeaderButtonDropdownConfig, VegaAppHeaderButtonSize } from './types';
+import { VegaAppHeaderAvatarConfig, VegaAppHeaderButtonDropdownConfig, VegaAppHeaderButtonSize, VegaAppHeaderLabelConfig } from './types';
 import { PageResizeObserverSlimmer } from '../../helpers/slimmers/page-resize-observer-slimmer';
 import { ChildNodesEventPreventSlimmer } from '../../helpers/event-manager/slimmers/child-nodes-event-prevent-slimmer';
 import { EventEmitSlimmerBase } from '../../helpers/event-manager/slimmers/event-emit-slimmer';
@@ -48,6 +48,12 @@ export declare class VegaAppHeaderButton {
    * @vegaVersion 1.11.0
    */
   size: ResponsiveType<VegaAppHeaderButtonSize>;
+  /**
+   * Specifies the display configuration of the app header button label.
+   *
+   * @vegaVersion 2.77.1
+   */
+  labelConfig: VegaAppHeaderLabelConfig;
   /**
    * Specifies the label or text content of the app header button.
    *
@@ -142,6 +148,7 @@ export declare class VegaAppHeaderButton {
   reset: EventEmitter<string>;
   render(): VegaAppHeaderButton;
   private renderButton;
+  private renderButtonLabel;
   private renderAvatar;
   private renderFallbackTextAvatar;
   /**

package/dist/types/components/vega-button-link/vega-button-link.d.ts

@@ -4,6 +4,7 @@ import { EventEmitSlimmerBase } from '../../helpers/event-manager/slimmers/event
 import { ChildNodesEventPreventSlimmer } from '../../helpers/event-manager/slimmers/child-nodes-event-prevent-slimmer';
 import { VegaComponentUsageRuntimeMetricsSlimmer } from '../../helpers/slimmers/component-usage-runtime-metrics';
 import { VegaButtonLinkTarget } from './types';
+import { AriaAttributesValueMapper } from '../../helpers/slimmers/mutation-observer/aria-attributes-value-mapper';
 /**
  * @vegaVersion 1.0.2
  */
@@ -13,6 +14,7 @@ export declare class VegaButtonLink {
   protected clickEventEmitter: EventEmitSlimmerBase;
   protected eventPrevent: ChildNodesEventPreventSlimmer;
   protected vegaComponentUsageRuntimeMetricsSlimmer: VegaComponentUsageRuntimeMetricsSlimmer<HTMLVegaButtonLinkElement>;
+  protected ariaAttributesValueMapper: AriaAttributesValueMapper;
   host: HTMLVegaButtonLinkElement;
   /**
    * Specifies the URL associated with the button link.

package/dist/types/components/vega-date-picker/slimmers/controllers/vega-date-picker-calendar-open-state-controller.d.ts

@@ -5,6 +5,9 @@ export declare class VegaDatePickerCalendarOpenStateController extends ElementAp
   dropdownConfig: VegaDatePicker['dropdownConfig'];
   vegaDatePickerRenderer: VegaDatePicker['vegaDatePickerRenderer'];
   vegaDatePickerCalendarRenderer: VegaDatePicker['vegaDatePickerCalendarRenderer'];
+  value: VegaDatePicker['value'];
+  format: VegaDatePicker['format'];
+  mode: VegaDatePicker['mode'];
   isCalendarShow: VegaDatePicker['isCalendarShow'];
   isMobileDevice: VegaDatePicker['isMobileDevice'];
   private clearCalendarStateTaskQueue;
@@ -45,6 +48,8 @@ export declare class VegaDatePickerCalendarOpenStateController extends ElementAp
   showCalendar(): Promise<void>;
   /**
    * Hide calendar in both mobile and desktop mode.
+   * After hiding, focuses the input container with a temporary
+   * aria-label so the screen reader announces the selection.
    */
   hideCalendar(): Promise<void>;
   /**
@@ -53,6 +58,22 @@ export declare class VegaDatePickerCalendarOpenStateController extends ElementAp
    * @param {boolean} isShow - is calendar show
    */
   updateIsCalendarShowState(isShow: boolean): void;
+  /**
+   * Focus the input container div with a temporary aria-label.
+   * VoiceOver always reads aria-label on programmatic .focus().
+   *
+   * The role, aria-label, and tabIndex attributes are set imperatively
+   * only during the announcement and removed on blur, so they don't
+   * interfere with VoiceOver navigation while the calendar is open.
+   */
+  private focusContainerWithAnnouncement;
+  /**
+   * Builds an aria announcement string based on the selected date value.
+   *
+   * @param {DatePickerValueType<DatePickerModeType>} value The date picker value to build announcement for
+   * @returns {string} The aria announcement string
+   */
+  private buildAriaAnnouncement;
   /**
    * Clear selecting state in calendar.
    */

package/dist/types/components/vega-date-picker/vega-date-picker-calendar/slimmers/controllers/vega-date-picker-calendar-selection-controller.d.ts

@@ -13,6 +13,7 @@ export declare class VegaDatePickerCalendarSelectionController extends VegaDateP
   clearEventEmitter: VegaDatePickerCalendar['clearEventEmitter'];
   vegaSelectionChangeEventEmitter: VegaDatePickerCalendar['vegaSelectionChangeEventEmitter'];
   allowRepickController: VegaDatePickerCalendar['allowRepickController'];
+  translationSlimmer: VegaDatePickerCalendar['translationSlimmer'];
   private previousCalendarSelection;
   /** componentWillLoad */
   componentWillLoad(): void;

package/dist/types/components/vega-date-picker/vega-date-picker-calendar/slimmers/renderers/vega-date-picker-calendar-renderer.d.ts

@@ -3,6 +3,7 @@ import { VegaDatePickerCalendar } from '../../vega-date-picker-calendar';
 export declare class VegaDatePickerCalendarRenderer extends VegaSlimmer {
   host: VegaDatePickerCalendar['host'];
   clearButton: VegaDatePickerCalendar['clearButton'];
+  calendarSelection: VegaDatePickerCalendar['calendarSelection'];
   monthItemRenderer: VegaDatePickerCalendar['monthItemRenderer'];
   staticHeight: VegaDatePickerCalendar['staticHeight'];
   translationSlimmer: VegaDatePickerCalendar['translationSlimmer'];
@@ -16,4 +17,10 @@ export declare class VegaDatePickerCalendarRenderer extends VegaSlimmer {
   private renderFooter;
   private shouldRenderRangeMonth;
   private clearCalendar;
+  /**
+   * Build aria announcement string based on current calendar selection.
+   *
+   * @returns {string} - Aria announcement string.
+   */
+  private buildAnnouncement;
 }

package/dist/types/components/vega-dropdown/slimmers/controllers/vega-dropdown-appender-controller.d.ts

@@ -24,6 +24,7 @@ export declare class VegaDropdownAppenderController extends ElementAppenderSlimm
   hideEventEmitter: VegaDropdown['hideEventEmitter'];
   isScreenPosition: VegaDropdown['isScreenPosition'];
   private target;
+  private lastFocusedElement;
   /**
    * Component lifecycle - [componentDidLoad]{@link VegaPopover.connectedCallback}
    */
@@ -50,6 +51,16 @@ export declare class VegaDropdownAppenderController extends ElementAppenderSlimm
    * The function `userHide` hides a dropdown if it is currently being shown.
    */
   userHide(): void;
+  /**
+   * Restores focus to the dropdown trigger element.
+   * Should be called after programmatic hide actions (item selection, Escape, reset)
+   * to maintain proper screen reader context per WAI-ARIA menu button pattern.
+   */
+  private focusTriggerForAria;
+  /**
+   * Updates the last focused element by getting the currently active element in the shadow DOM.
+   */
+  private updateLastFocusedElement;
   /**
    * Generate the show configuration for the dropdown.
    *

package/dist/types/components/vega-input/slimmers/controllers/vega-input-render-mode-controller.d.ts

@@ -5,7 +5,6 @@ export declare class VegaInputRenderModeController extends VegaSlimmer {
   host: VegaInput['host'];
   suggestionsDropdownSource: VegaInput['suggestionsDropdownSource'];
   private hasItemsSlot;
-  private hasDropdownSource;
   /** Sets the render mode based on the presence of the items slot. */
   connectedCallback(): void;
   /**

package/dist/types/components/vega-input/slimmers/renderers/vega-input-input-renderer.d.ts

@@ -5,7 +5,6 @@ export declare class VegaInputInputRenderer extends VegaSlimmer {
   private value;
   private disabled;
   private type;
-  private label;
   private name;
   private autocomplete;
   private inputmode;

package/dist/types/components/vega-input/vega-input.d.ts

@@ -21,11 +21,15 @@ import { VegaInputValueController } from './slimmers/controllers/vega-input-valu
 import { VegaInputInputSuggestionsRenderer } from './slimmers/renderers/vega-input-input-suggestions-renderer';
 import { VegaDropdownSourceItem } from '../vega-dropdown/types';
 import { VegaInputRenderModeController } from './slimmers/controllers/vega-input-render-mode-controller';
+import { AriaAttributesValueMapper } from '../../helpers/slimmers/mutation-observer/aria-attributes-value-mapper';
+import { DataTabIndexValueMapper } from '../../helpers/slimmers/mutation-observer/data-tab-index-value-mapper';
 /**
  * @vegaVersion 1.0.5
  */
 export declare class VegaInput {
   protected readonly globalSlimmers: GlobalSlimmers;
+  protected ariaAttributesValueMapper: AriaAttributesValueMapper;
+  protected dataTabIndexValueMapper: DataTabIndexValueMapper;
   protected readonly formFieldController: FormFieldControllerSlimmer<string>;
   protected readonly pageResizeObserverSlimmer: PageResizeObserverSlimmer;
   protected renderModeController: VegaInputRenderModeController;

package/dist/types/components/vega-input-passcode/slimmers/renderers/vega-input-passcode-renderer.d.ts

@@ -26,5 +26,19 @@ export declare class VegaInputPasscodeRenderer extends VegaSlimmer {
   private handleVegaBlur;
   private handleVegaChange;
   private handleVegaPaste;
+  /**
+   * Find the index of the first empty input box for rendering purposes. If all boxes are filled, return -1.
+   *
+   * @param {number} inputLength - the input length of the passcode, which is also the number of input boxes to render
+   * @returns {number} - the index of the first empty input box, or -1 if all boxes are filled
+   */
+  private getFirstEmptyIndexForRender;
+  /**
+   * Determine whether the input box at the given index should be accessible to screen readers. Only the boxes up to and including the first empty box should be accessible, as screen readers will read out all accessible boxes and we don't want them to read out empty boxes that come before filled boxes.
+   *
+   * @param {number} index - the index of the input box to check
+   * @returns {boolean} - true if the input box should be accessible to screen readers, false otherwise
+   */
+  private isInputAccessibleForScreenReader;
   private generateNewInputValue;
 }

package/dist/types/components/vega-rich-text-editor/slimmers/controllers/insert-image-controller.d.ts

@@ -1,6 +1,9 @@
 import { VegaSlimmer } from '../../../../vega-slimmer/vega-slimmer-core';
 import { VegaRichTextEditor } from '../../vega-rich-text-editor';
+import { RTEBlock } from '../../dto/blocks/block.abstract';
 import { RTEImageNode } from '../../dto/nodes/image-node';
+import { RTENode } from '../../dto/nodes/node.abstract';
+import { RTERange } from '../../dto/range';
 /** Used to control the insert image tool button actions */
 export declare class InsertImageController extends VegaSlimmer {
   protected selectionController: VegaRichTextEditor['selectionController'];
@@ -11,9 +14,12 @@ export declare class InsertImageController extends VegaSlimmer {
    * Insert a image to current state
    *
    * @param {string} imageUrl The image url
+   * @param {RTEBlock[]} selectedBlocks The current selected blocks, if not provided, will get from selectionController
+   * @param {RTENode[]} selectedNodes The current selected nodes, if not provided, will get from selectionController
+   * @param {RTERange} currentRange The current selected range, if not provided, will get from selectionController
    * @returns {RTEImageNode} RTEImageNode
    */
-  insertImageToCaretPosition(imageUrl: string): RTEImageNode;
+  insertImageToCaretPosition(imageUrl: string, selectedBlocks?: RTEBlock[], selectedNodes?: RTENode[], currentRange?: RTERange): RTEImageNode;
   /**
    * Add image selected observer
    */

package/dist/types/components/vega-rich-text-editor/slimmers/renderers/tools/image-toolbar-button-slimmer.d.ts

@@ -1,20 +1,48 @@
 import { ToolbarInternalButtonConfig } from './toolbar-button-slimmer.abstract';
 import { VegaRichTextEditor } from '../../../vega-rich-text-editor';
 import { VisualModeToolbarButtonSlimmer } from './visual-mode-toolbar-button-slimmer.abstract';
+export declare type InsertImageType = 'upload' | 'url';
+export declare type InsertImageItem = {
+  key: InsertImageType;
+  label: string;
+};
+export declare type InsertURLForm = {
+  url: string;
+};
 export declare class ImageToolbarButtonSlimmer extends VisualModeToolbarButtonSlimmer {
+  private static readonly items;
   protected insertImageController: VegaRichTextEditor['insertImageController'];
   protected imageInsertedEventEmitter: VegaRichTextEditor['imageInsertedEventEmitter'];
   protected selectionController: VegaRichTextEditor['selectionController'];
-  private inputElementRef;
+  private uploadInputRef;
+  private dropdownRef;
+  private insertURLInputRef;
+  private insertURLModalRef;
   private updateNodeURLMap;
+  private currentRange;
+  private currentSelectedBlocks;
+  private currentSelectedNodes;
   constructor();
   protected renderBtnWrapper(renderBtn: (toolbarInternalButton: ToolbarInternalButtonConfig) => HTMLElement): HTMLElement;
-  protected onClick: () => void;
   protected isSelected(): boolean;
   protected isDisabled(): boolean;
+  private renderDropdownContent;
+  private renderUploadInput;
+  private renderInsertURLModal;
+  private addDropdownObserver;
+  private addModalCancelObserver;
+  private addModalInsertObserver;
+  private insertURLImage;
+  private handleDropdownItemClick;
   /**
    * The below method is e2e-test covered in
    * @see{module:should-update-url-properly-when-upload-images}
    */
   private fileInputChange;
+  /**
+   * The below method is e2e-test covered in
+   * @see{module:should-update-url-properly-when-upload-images}
+   */
+  private applyImageNode;
+  private normalizeSafeImageUrl;
 }

package/dist/types/components.d.ts

@@ -7,7 +7,7 @@
 import { HTMLStencilElement, JSXBase } from "./stencil-public-runtime";
 import { BorderStyleType, BoxDisplayType, CornersType, CssStatesType, ElementAppenderAlignmentType, ElementAppenderPlacementType, FlexAlignItemType, FlexDirectionType, FlexJustifyContentType, FlexWrapType, GapType, GridColumnsType, GridRowsType, HeightType, IconAlignType, MarginType, MaxHeightType, MinHeightType, PaddingType, PlacementType, PositionAlignmentType, ResponsiveType, SizeType, StateVariantType, TextAlignType, TranslocationType, VegaComponentInterface, VegaEATriggerType, VegaFlexProps, WidthType } from "./types/ui.type";
 import { LinkTargetType, VegaAppFooterLink } from "./components/vega-app-footer/types";
-import { VegaAppHeaderAvatarConfig, VegaAppHeaderButtonDropdownConfig, VegaAppHeaderButtonSize } from "./components/vega-app-header-button/types";
+import { VegaAppHeaderAvatarConfig, VegaAppHeaderButtonDropdownConfig, VegaAppHeaderButtonSize, VegaAppHeaderLabelConfig } from "./components/vega-app-header-button/types";
 import { VegaBannerActionButtonType, VegaBannerPropType } from "./components/vega-banner/types";
 import { VegaBarChartOptionsType } from "./components/vega-chart/vega-bar-chart/types";
 import { BackgroundColorsTokenType, BorderColorsTokenType, BordersTokenType, BreakpointsTokenType, ShadowsTokenType, SpacingTokenType, TextColorsTokenType, TypographyTokenType } from "./types/design-token.type";
@@ -199,6 +199,11 @@ export namespace Components {
           * @vegaVersion 1.11.0
          */
         "label": string;
+        /**
+          * Specifies the display configuration of the app header button label.
+          * @vegaVersion 2.77.1
+         */
+        "labelConfig": VegaAppHeaderLabelConfig;
         /**
           * Specifies whether the app header button is displayed in a selected state.
           * @vegaVersion 1.15.0
@@ -5746,6 +5751,11 @@ declare namespace LocalJSX {
           * @vegaVersion 1.11.0
          */
         "label"?: string;
+        /**
+          * Specifies the display configuration of the app header button label.
+          * @vegaVersion 2.77.1
+         */
+        "labelConfig"?: VegaAppHeaderLabelConfig;
         /**
           * An event emitter notifying the click event of an app header button.
           * @eventSemantics namespace:native

package/dist/types/helpers/calendar/utils.d.ts

@@ -1,3 +1,5 @@
+import type { CalendarDate } from './calendar-date';
+import type { Nullable } from '../../types/general';
 /**
  * Get a week days array
  *
@@ -20,3 +22,18 @@ export declare enum WeekdayLongNames {
  * @returns {string} - The system timezone identifier (e.g., "America/New_York")
  */
 export declare const getSystemTimezone: () => string;
+/**
+ * Build an aria announcement string for date picker selection.
+ * TODO: consider to implement i18n for aria announcement .
+ *
+ * @param {object} options - The options for building the announcement.
+ * @param {'single' | 'range'} options.mode - The date picker selection mode.
+ * @param {Nullable<CalendarDate>} options.startDate - The start date.
+ * @param {Nullable<CalendarDate>} [options.endDate] - The end date (used in range mode).
+ * @returns {string} - The aria announcement string.
+ */
+export declare const buildDatePickerAnnouncement: (options: {
+  mode: 'single' | 'range';
+  startDate: Nullable<CalendarDate>;
+  endDate?: Nullable<CalendarDate>;
+}) => string;

package/dist/types/helpers/slimmers/element-appender/element-appender-slimmer.d.ts

@@ -69,5 +69,17 @@ export declare class ElementAppenderSlimmer extends VegaSlimmer {
   private removeShadowRootElementScrolling;
   private executeTriggerStrategy;
   private getTriggerStrategy;
+  /**
+   * 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.
+   */
+  private setAriaOwns;
+  /**
+   * Removes `ariaOwnsElements` from the target element when the popup is hidden or destroyed.
+   */
+  private removeAriaOwns;
 }
 export {};

package/dist/types/helpers/slimmers/mutation-observer/aria-attributes-value-mapper.d.ts

@@ -1,7 +1,8 @@
 import { MutationObserverSlimmer } from './mutation-observer-slimmer';
+import { Nullable } from '../../../types/general';
 export declare type AriaAttrDependency = {
   dependency: string[];
-  defaultValue?: string;
+  defaultValue?: Nullable<string>;
 };
 export declare type AriaAttributesMap = Record<string, AriaAttrDependency>;
 /**

package/dist/types/helpers/slimmers/mutation-observer/data-tab-index-value-mapper.d.ts

@@ -0,0 +1,35 @@
+import { MutationObserverSlimmer } from './mutation-observer-slimmer';
+/**
+ * Maps host data-tabindex to inner native input tabindex.
+ */
+export declare class DataTabIndexValueMapper extends MutationObserverSlimmer {
+  private static readonly OBSERVED_ATTRIBUTE;
+  private readonly targetGetter;
+  /**
+   * Component lifecycle - [componentDidLoad]
+   */
+  componentDidLoad(): void;
+  /**
+   * Component lifecycle - [componentDidRender]
+   */
+  componentDidRender(): void;
+  /**
+   * Constructor for DataTabIndexValueMapper
+   *
+   * @param {() => HTMLElement} targetGetter - Function to get the target HTMLElement
+   */
+  constructor(targetGetter: () => HTMLElement);
+  /**
+   * 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.
+   */
+  private performMapping;
+  /**
+   * 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
+   */
+  private shouldRemoveTabIndex;
+}

package/dist/types/helpers/slimmers/mutation-observer/test/data-tab-index-value-mapper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/helpers/slimmers/position-calculation/base-position-calculation-strategy.d.ts

@@ -1,4 +1,5 @@
 import { VegaSlimmer } from '../../../vega-slimmer/vega-slimmer-core';
+import { Nullable } from '../../../types/general';
 import { ElementBoundBox, ElementPositionBox, ElementScrollDimension, PlacementType, PositionAlignmentType } from '../../../types/ui.type';
 import { ElementAppenderShowConfig } from '../../ui/element-appender';
 /**
@@ -69,9 +70,9 @@ export declare abstract class BasePositionCalculationStrategy extends VegaSlimme
    * @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.
    */
-  protected getSuitablePlacement(containerBox: ElementScrollDimension, elementBox: ElementBoundBox, targetBox: ElementBoundBox, placements: PlacementType[]): PlacementType;
+  protected getSuitablePlacement(containerBox: ElementScrollDimension, elementBox: ElementBoundBox, targetBox: ElementBoundBox, placements: PlacementType[]): Nullable<PlacementType>;
   /**
    * "Get the width, height, and top position of an element."
    *
@@ -104,6 +105,62 @@ export declare abstract class BasePositionCalculationStrategy extends VegaSlimme
    * @returns {ElementPositionBox} An object with top and left properties.
    */
   private calculatePosition;
+  /**
+   * 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.
+   */
+  private keepVerticallyInView;
+  /**
+   * 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.
+   */
+  private keepHorizontallyInView;
+  /**
+   * 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.
+   */
+  private isTargetInView;
+  /**
+   * 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.
+   */
+  private adjustPositionForViewport;
+  /**
+   * 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.
+   */
+  private adjustForVerticalOverflow;
+  /**
+   * 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.
+   */
+  private adjustForHorizontalOverflow;
   /**
    * It returns the translocation of the element relative to the target element
    *
@@ -119,7 +176,7 @@ export declare abstract class BasePositionCalculationStrategy extends VegaSlimme
    * @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.
    */
   private getSuitableAlignment;
   /**

package/dist/types/helpers/slimmers/position-calculation/screen-position-calculation-strategy.d.ts

@@ -1,6 +1,7 @@
 import { ElementAppenderShowConfig } from '../../ui/element-appender';
 import { ElementBoundBox, ElementPositionBox, ElementScrollDimension, PlacementType, PositionAlignmentType } from '../../../types/ui.type';
 import { BasePositionCalculationStrategy } from './base-position-calculation-strategy';
+import { Nullable } from '../../../types/general';
 /**
  * calculate position by screen container
  */
@@ -68,7 +69,7 @@ export declare class ScreenPositionCalculationStrategy extends BasePositionCalcu
    * @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.
    */
-  protected getSuitablePlacement(containerBox: ElementScrollDimension, elementBox: ElementBoundBox, targetBox: ElementBoundBox, placements: PlacementType[]): PlacementType;
+  protected getSuitablePlacement(containerBox: ElementScrollDimension, elementBox: ElementBoundBox, targetBox: ElementBoundBox, placements: PlacementType[]): Nullable<PlacementType>;
 }

package/dist/types/helpers/slimmers/position-calculation/test/body-position-calculation-strategy.test.d.ts

@@ -10,6 +10,6 @@ export declare class PositionCalculationMockedComponent {
   private isScreenPosition;
   constructor();
   setIsScreenPosition(isScreenPosition: boolean): void;
-  getPositionBox(container: HTMLElement, element: HTMLElement, target: HTMLElement, placement?: PlacementType | PlacementType[], alignment?: PositionAlignmentType | PositionAlignmentType[], translocation?: TranslocationType): ElementPositionBox;
+  getPositionBox(container: HTMLElement, element: HTMLElement, target: HTMLElement, placement?: PlacementType | PlacementType[], alignment?: PositionAlignmentType | PositionAlignmentType[], translocation?: TranslocationType, positionRelativeTo?: string): ElementPositionBox;
   private setHtml;
 }

package/dist/types/helpers/translation/interface.d.ts

@@ -80,11 +80,20 @@ export type StaticTranslationKey =
 	| 'Thu-short'
 	| 'Fri-short'
 	| 'Sat-short'
+	| 'Sun-full'
+	| 'Mon-full'
+	| 'Tue-full'
+	| 'Wed-full'
+	| 'Thu-full'
+	| 'Fri-full'
+	| 'Sat-full'
 	| 'Day'
 	| 'Week'
 	| 'Month'
 	| 'Today'
 	| 'Clear'
+	| 'Previous month'
+	| 'Next month'
 	// Common end
 	| 'Viewing'
 	| 'Show'
@@ -127,6 +136,10 @@ export type StaticTranslationKey =
 	| 'Less Indent'
 	| 'Link'
 	| 'Image'
+	| 'Upload from computer'
+	| 'Insert via URL'
+	| 'Image via URL'
+	| 'Insert'
 	| 'Clear Style'
 	| 'URL'
 	| 'Text'
@@ -150,6 +163,8 @@ export type StaticTranslationKey =
 	| 'Copy Code'
 	| 'Code Block'
 	| 'Copied'
+	| 'date picker'
+	| 'Selected result'
 	| 'Repeat every {0} days'
 	| 'Repeat daily'
 	| 'Repeat every {0} weeks on {1}'

package/dist/types/types/components.type.d.ts

@@ -41,6 +41,7 @@ export {
 	VegaAppHeaderAvatarConfig,
 	VegaAppHeaderButtonDropdownConfig,
 	VegaAppHeaderButtonSize,
+	VegaAppHeaderLabelConfig,
 } from '../components/vega-app-header-button/types';
 export { VegaBannerActionButtonType, VegaBannerPropType } from '../components/vega-banner/types';
 export { VegaBarChartOptionsType } from '../components/vega-chart/vega-bar-chart/types';

package/dist/types/types/ui.type.d.ts

@@ -5,6 +5,7 @@ import { HTMLStencilElement } from '../stencil-public-runtime';
 import { GridColumns, GridRows } from '../constants/tokens/tailwind.extend';
 import { JSX as LocalJSX } from '../components';
 import { VegaEATriggerStrategy } from '../helpers/slimmers/element-appender/trigger-strategies/trigger-strategy.interface';
+import { Nullable } from './general';
 /**
  * Represents the portion of the browser viewport currently visible.
  */
@@ -338,11 +339,11 @@ export declare type ElementPositionBox = {
   /**
    * Placement position configuration.
    */
-  placement?: PlacementType;
+  placement?: Nullable<PlacementType>;
   /**
    * Position alignment configuration.
    */
-  alignment?: PositionAlignmentType;
+  alignment?: Nullable<PositionAlignmentType>;
   /**
    * Distance from top edge in pixels.
    */

package/dist/types/utils/e2e-utils.d.ts

@@ -97,6 +97,7 @@ export declare const getScreenshotDiffResults: (page: E2EPage, desc: string, sel
  * @param {number} config.timeout --sets the content timeout
  * @param {InjectFeatureFlagsConfig} config.featureFlags -inject feature flags.
  * @param {string} config.timezone -sets the browser timezone (defaults to 'Asia/Shanghai' for consistent behavior across environments).
+ * @param {boolean} config.isMobile - whether to set the viewport to a mobile device size (defaults to false).
  */
 export declare const initVegaE2EPage: (content: string, config?: {
   wrapped?: boolean;
@@ -105,6 +106,7 @@ export declare const initVegaE2EPage: (content: string, config?: {
   timeout?: number;
   featureFlags?: InjectFeatureFlagsConfig;
   timezone?: string;
+  isMobile?: boolean;
 }) => Promise<E2EPage>;
 /**
  * NOTE: This method is only for **E2E** test cases.