feat(overlay): add placement and offset

RivaIvanova · RivaIvanova · commit ce011638e704 · 2025-06-04T18:15:51.000+03:00
diff --git a/projects/igniteui-angular/src/lib/services/overlay/position/base-fit-position-strategy.ts b/projects/igniteui-angular/src/lib/services/overlay/position/base-fit-position-strategy.ts
@@ -42,24 +42,26 @@ export abstract class BaseFitPositionStrategy extends ConnectedPositioningStrate
      * @param connectedFit connectedFit to update
      */
     protected updateViewPortFit(connectedFit: ConnectedFit) {
+        const horizontalOffset = Util.getHorizontalOffset(connectedFit, this.settings);
         connectedFit.left = this.calculateLeft(
             connectedFit.targetRect,
             connectedFit.contentElementRect,
             this.settings.horizontalStartPoint,
             this.settings.horizontalDirection,
-            connectedFit.horizontalOffset ? connectedFit.horizontalOffset : 0);
+            horizontalOffset);
         connectedFit.right = connectedFit.left + connectedFit.contentElementRect.width;
         connectedFit.fitHorizontal = {
             back: Math.round(connectedFit.left),
             forward: Math.round(connectedFit.viewPortRect.width - connectedFit.right)
         };
 
+        const verticalOffset = Util.getVerticalOffset(connectedFit, this.settings);
         connectedFit.top = this.calculateTop(
             connectedFit.targetRect,
             connectedFit.contentElementRect,
             this.settings.verticalStartPoint,
             this.settings.verticalDirection,
-            connectedFit.verticalOffset ? connectedFit.verticalOffset : 0);
+            verticalOffset);
         connectedFit.bottom = connectedFit.top + connectedFit.contentElementRect.height;
         connectedFit.fitVertical = {
             back: Math.round(connectedFit.top),
diff --git a/projects/igniteui-angular/src/lib/services/overlay/position/connected-positioning-strategy.ts b/projects/igniteui-angular/src/lib/services/overlay/position/connected-positioning-strategy.ts
@@ -27,10 +27,17 @@ export class ConnectedPositioningStrategy implements IPositionStrategy {
     verticalStartPoint: VerticalAlignment.Bottom,
     openAnimation: scaleInVerTop,
     closeAnimation: scaleOutVerTop,
-    minSize: { width: 0, height: 0 }
+    minSize: { width: 0, height: 0 },
+    offset: 0
   };
 
   constructor(settings?: PositionSettings) {
+
+    if (Util.canUsePlacement(settings)) {
+        const placementPositionSettings = Util.getPositionSettingsByPlacement(settings.placement);
+        settings = Object.assign({}, settings, placementPositionSettings);
+    }
+
     this.settings = Object.assign({}, this._defaultSettings, settings);
   }
 
@@ -81,8 +88,9 @@ export class ConnectedPositioningStrategy implements IPositionStrategy {
    * @param elementRect Bounding rectangle of the element
    */
   protected setStyle(element: HTMLElement, targetRect: Partial<DOMRect>, elementRect: Partial<DOMRect>, connectedFit: ConnectedFit) {
-    const horizontalOffset = connectedFit.horizontalOffset ? connectedFit.horizontalOffset : 0;
-    const verticalOffset = connectedFit.verticalOffset ? connectedFit.verticalOffset : 0;
+    const horizontalOffset = Util.getHorizontalOffset(connectedFit, this.settings);
+    const verticalOffset = Util.getVerticalOffset(connectedFit, this.settings);
+
     const startPoint: Point = {
       x: targetRect.right + targetRect.width * this.settings.horizontalStartPoint + horizontalOffset,
       y: targetRect.bottom + targetRect.height * this.settings.verticalStartPoint + verticalOffset
diff --git a/projects/igniteui-angular/src/lib/services/overlay/position/global-position-strategy.ts b/projects/igniteui-angular/src/lib/services/overlay/position/global-position-strategy.ts
@@ -1,5 +1,5 @@
 import { fadeIn, fadeOut } from 'igniteui-angular/animations';
-import { HorizontalAlignment, PositionSettings, Util, VerticalAlignment } from './../utilities';
+import { HorizontalAlignment, Placement, PositionSettings, Util, VerticalAlignment } from './../utilities';
 import { IPositionStrategy } from './IPositionStrategy';
 
 /**
@@ -23,6 +23,16 @@ export class GlobalPositionStrategy implements IPositionStrategy {
     };
 
     constructor(settings?: PositionSettings) {
+
+        if (Util.canUsePlacement(settings)) {
+            const placement = this.shouldFlip(settings.placement)
+                ? this.getOppositePlacement(settings.placement)
+                : settings.placement;
+
+            const placementPositionSettings = Util.getPositionSettingsByPlacement(placement);
+            settings = Object.assign({}, settings, placementPositionSettings);
+        }
+
         this.settings = Object.assign({}, this._defaultSettings, settings);
     }
 
@@ -83,5 +93,24 @@ export class GlobalPositionStrategy implements IPositionStrategy {
                 break;
         }
     }
-}
 
+    private shouldFlip(placement: Placement): boolean {
+        const endStartPositionsRegExp = /^(?:top|bottom|right|left)-(?:start|end)$/;
+        return endStartPositionsRegExp.test(placement);
+    }
+
+    private getOppositePlacement(placement: Placement): Placement {
+        const oppositePlacements: { [key: string]: string } = {
+            [Placement.TopStart]: Placement.TopEnd,
+            [Placement.TopEnd]: Placement.TopStart,
+            [Placement.BottomStart]: Placement.BottomEnd,
+            [Placement.BottomEnd]: Placement.BottomStart,
+            [Placement.LeftStart]: Placement.LeftEnd,
+            [Placement.LeftEnd]: Placement.LeftStart,
+            [Placement.RightStart]: Placement.RightEnd,
+            [Placement.RightEnd]: Placement.RightStart,
+        };
+
+        return oppositePlacements[placement] as Placement;
+    }
+}
diff --git a/projects/igniteui-angular/src/lib/services/overlay/utilities.ts b/projects/igniteui-angular/src/lib/services/overlay/utilities.ts
@@ -20,6 +20,24 @@ export enum VerticalAlignment {
     Bottom = 0
 }
 
+/**
+ * Defines the possible positions for the element relative to its target.
+ */
+export enum Placement {
+    Top = 'top',
+    TopStart = 'top-start',
+    TopEnd = 'top-end',
+    Bottom = 'bottom',
+    BottomStart = 'bottom-start',
+    BottomEnd = 'bottom-end',
+    Right = 'right',
+    RightStart = 'right-start',
+    RightEnd = 'right-end',
+    Left = 'left',
+    LeftStart = 'left-start',
+    LeftEnd = 'left-end'
+}
+
 /**
  * Defines the possible values of the overlays' position strategy.
  */
@@ -87,6 +105,10 @@ export interface PositionSettings {
     closeAnimation?: AnimationReferenceMetadata;
     /** The size up to which element may shrink when shown in elastic position strategy */
     minSize?: Size;
+    /** Where to place the element relative to its target. Used to set the direction and starting point. */
+    placement?: Placement;
+    /** The offset of the element from the target in pixels when shown in connected position strategy. */
+    offset?: number;
 }
 
 export interface OverlaySettings {
@@ -261,4 +283,176 @@ export class Util {
         clonedObj.settings = cloneValue(clonedObj.settings);
         return clonedObj;
     }
+
+    /**
+     * Gets the position settings that correspond to the given placement.
+     *
+     * @param placement Placement for which to get the corresponding position settings.
+     */
+    public static getPositionSettingsByPlacement(placement: Placement): PositionSettings {
+        return PositionsMap.get(placement);
+    }
+
+    /**
+     * Gets the placement that correspond to the given position settings.
+     * Returns `undefined` if the position settings do not match any of the predefined placement values.
+     *
+     * @param settings Position settings for which to get the corresponding placement.
+     */
+    public static getPlacementByPositionSettings(settings: PositionSettings): Placement {
+        const { horizontalDirection, horizontalStartPoint, verticalDirection, verticalStartPoint } = settings;
+
+        const mapArray = Array.from(PositionsMap.entries());
+        const placement = mapArray.find(
+            ([_, val]) =>
+                val.horizontalDirection === horizontalDirection &&
+                val.horizontalStartPoint === horizontalStartPoint &&
+                val.verticalDirection === verticalDirection &&
+                val.verticalStartPoint === verticalStartPoint
+        );
+
+        return placement ? placement[0] : undefined;
+    }
+
+    /**
+     * Returns `false` if a direction or starting point is specified by
+     * `horizontalDirection`, `horizontalStartPoint`, `verticalDirection`, or `verticalStartPoint`.
+     *
+     * @param settings Position settings for which to check if any directions or starting points are defined.
+     */
+    public static canUsePlacement(settings: PositionSettings): boolean {
+        return settings
+            && settings.placement
+            && settings.horizontalDirection == null
+            && settings.horizontalStartPoint == null
+            && settings.verticalDirection == null
+            && settings.verticalStartPoint == null;
+    }
+
+    /**
+     * Gets horizontal offset by connectedFit `horizontalOffset` or position settings `offset`.
+     * ConnectedFit `horizontalOffset` has priority.
+     */
+    public static getHorizontalOffset(connectedFit: ConnectedFit, settings: PositionSettings): number {
+        if (connectedFit.horizontalOffset != null) {
+            return connectedFit.horizontalOffset;
+        }
+
+        if (
+            settings.horizontalDirection === HorizontalAlignment.Left &&
+            settings.horizontalStartPoint === HorizontalAlignment.Left
+        ) {
+            return -settings.offset;
+        } else if (
+            settings.horizontalDirection === HorizontalAlignment.Right &&
+            settings.horizontalStartPoint === HorizontalAlignment.Right
+        ) {
+            return settings.offset;
+        }
+
+        return 0;
+    }
+
+    /**
+     * Gets vertical offset by connectedFit `verticalOffset` or position settings `offset`.
+     * ConnectedFit `verticalOffset` has priority.
+     */
+    public static getVerticalOffset(connectedFit: ConnectedFit, settings: PositionSettings): number {
+        if (connectedFit.verticalOffset != null) {
+            return connectedFit.verticalOffset;
+        }
+
+        if (
+            settings.verticalDirection === VerticalAlignment.Top &&
+            settings.verticalStartPoint === VerticalAlignment.Top
+        ) {
+            return -settings.offset;
+        } else if (
+            settings.verticalDirection === VerticalAlignment.Bottom &&
+            settings.verticalStartPoint === VerticalAlignment.Bottom
+        ) {
+            return settings.offset;
+        }
+
+        return 0;
+    }
+
 }
+
+/**
+ * Maps the predefined placement values to the corresponding directions and starting points.
+ */
+export const PositionsMap = new Map<Placement, PositionSettings>([
+    [Placement.Top, {
+        horizontalDirection: HorizontalAlignment.Center,
+        horizontalStartPoint: HorizontalAlignment.Center,
+        verticalDirection: VerticalAlignment.Top,
+        verticalStartPoint: VerticalAlignment.Top,
+    }],
+    [Placement.TopStart, {
+        horizontalDirection: HorizontalAlignment.Right,
+        horizontalStartPoint: HorizontalAlignment.Left,
+        verticalDirection: VerticalAlignment.Top,
+        verticalStartPoint: VerticalAlignment.Top,
+    }],
+    [Placement.TopEnd, {
+        horizontalDirection: HorizontalAlignment.Left,
+        horizontalStartPoint: HorizontalAlignment.Right,
+        verticalDirection: VerticalAlignment.Top,
+        verticalStartPoint: VerticalAlignment.Top,
+    }],
+    [Placement.Bottom, {
+        horizontalDirection: HorizontalAlignment.Center,
+        horizontalStartPoint: HorizontalAlignment.Center,
+        verticalDirection: VerticalAlignment.Bottom,
+        verticalStartPoint: VerticalAlignment.Bottom,
+    }],
+    [Placement.BottomStart, {
+        horizontalDirection: HorizontalAlignment.Right,
+        horizontalStartPoint: HorizontalAlignment.Left,
+        verticalDirection: VerticalAlignment.Bottom,
+        verticalStartPoint: VerticalAlignment.Bottom,
+    }],
+    [Placement.BottomEnd, {
+        horizontalDirection: HorizontalAlignment.Left,
+        horizontalStartPoint: HorizontalAlignment.Right,
+        verticalDirection: VerticalAlignment.Bottom,
+        verticalStartPoint: VerticalAlignment.Bottom,
+    }],
+    [Placement.Right, {
+        horizontalDirection: HorizontalAlignment.Right,
+        horizontalStartPoint: HorizontalAlignment.Right,
+        verticalDirection: VerticalAlignment.Middle,
+        verticalStartPoint: VerticalAlignment.Middle,
+    }],
+    [Placement.RightStart, {
+        horizontalDirection: HorizontalAlignment.Right,
+        horizontalStartPoint: HorizontalAlignment.Right,
+        verticalDirection: VerticalAlignment.Bottom,
+        verticalStartPoint: VerticalAlignment.Top,
+    }],
+    [Placement.RightEnd, {
+        horizontalDirection: HorizontalAlignment.Right,
+        horizontalStartPoint: HorizontalAlignment.Right,
+        verticalDirection: VerticalAlignment.Top,
+        verticalStartPoint: VerticalAlignment.Bottom,
+    }],
+    [Placement.Left, {
+        horizontalDirection: HorizontalAlignment.Left,
+        horizontalStartPoint: HorizontalAlignment.Left,
+        verticalDirection: VerticalAlignment.Middle,
+        verticalStartPoint: VerticalAlignment.Middle,
+    }],
+    [Placement.LeftStart, {
+        horizontalDirection: HorizontalAlignment.Left,
+        horizontalStartPoint: HorizontalAlignment.Left,
+        verticalDirection: VerticalAlignment.Bottom,
+        verticalStartPoint: VerticalAlignment.Top,
+    }],
+    [Placement.LeftEnd, {
+        horizontalDirection: HorizontalAlignment.Left,
+        horizontalStartPoint: HorizontalAlignment.Left,
+        verticalDirection: VerticalAlignment.Top,
+        verticalStartPoint: VerticalAlignment.Bottom,
+    }]
+]);
diff --git a/projects/igniteui-angular/src/lib/services/public_api.ts b/projects/igniteui-angular/src/lib/services/public_api.ts
@@ -11,7 +11,7 @@ export * from './overlay/position';
 export * from './overlay/scroll';
 export {
     AbsolutePosition, HorizontalAlignment, OverlayAnimationEventArgs, OverlayCancelableEventArgs, OverlayClosingEventArgs,
-    OverlayCreateSettings, OverlayEventArgs, OverlaySettings, Point, PositionSettings, RelativePosition, RelativePositionStrategy, VerticalAlignment
+    OverlayCreateSettings, OverlayEventArgs, OverlaySettings, Placement, Point, PositionSettings, RelativePosition, RelativePositionStrategy, VerticalAlignment
 } from './overlay/utilities';
 export * from './transaction/base-transaction';
 export * from './transaction/hierarchical-transaction';
