feat: added examples

Author: lskramarov

packages/components-dev/popover/module.ts

@@ -28,7 +28,10 @@ import { DevThemeToggle } from '../theme-toggle';
     selector: 'dev-examples',
     imports: [PopoverExamplesModule],
     template: `
+        <popover-scrolling-and-layering-example />
+        <br />
         <popover-paddings-example />
+        <br />
         <popover-small-example />
         <!--        <popover-width-example />-->
         <!--        <popover-common-example />-->

packages/components-dev/select/module.ts

@@ -20,6 +20,9 @@ import { DEV_OPTIONS } from './mock';
     selector: 'dev-examples',
     imports: [SelectExamplesModule],
     template: `
+        <select-scrolling-and-layering-example />
+        <hr />
+
         <select-with-multiline-matcher-example />
         <hr />
 

packages/components/core/pop-up/constants.ts

@@ -63,6 +63,12 @@ export type KbqPopUpSizeValues = KbqEnumValues<PopUpSizes>;
  */
 export const defaultOffsetY: number = 4;
 
+/**
+ * Default value when configuring overlay in popups (Autocomplete, Datepicker, Dropdown, Select, Tags Autocomplete,
+ * Tags Input, Timezone, TreeSelect).
+ */
+export const defaultOffsetX: number = 0;
+
 /**
  * Variable used for offsetY(X) calculations when applying Angular Overlay
  *

packages/components/popover/popover.component.ts

@@ -44,7 +44,7 @@ import {
     POSITION_TO_CSS_MAP,
     PopUpSizes,
     PopUpTriggers,
-    applyPopupMargins
+    applyPopupMargins, defaultOffsetY, defaultOffsetX
 } from '@koobiq/components/core';
 import { KbqIconModule } from '@koobiq/components/icon';
 import { NEVER, fromEvent, merge } from 'rxjs';
@@ -399,6 +399,16 @@ export class KbqPopoverTrigger extends KbqPopUpTrigger<KbqPopoverComponent> impl
 
     @Output('kbqPopoverVisibleChange') readonly visibleChange = new EventEmitter<boolean>();
 
+    /** Calculates the vertical offset relative to the overlay container. */
+    get offsetY(): number {
+        return defaultOffsetY - (this.overlayContainerRects?.y ?? 0);
+    }
+
+    /** Calculates the horizontal offset relative to the overlay container. */
+    get offsetX(): number {
+        return defaultOffsetX - (this.overlayContainerRects?.x ?? 0);
+    }
+
     protected originSelector = '.kbq-popover';
 
     protected get overlayConfig(): OverlayConfig {
@@ -409,6 +419,8 @@ export class KbqPopoverTrigger extends KbqPopUpTrigger<KbqPopoverComponent> impl
         };
     }
 
+    private overlayContainerRects?: DOMRect;
+
     ngOnInit(): void {
         super.ngOnInit();
 
@@ -431,11 +443,21 @@ export class KbqPopoverTrigger extends KbqPopUpTrigger<KbqPopoverComponent> impl
                 }
             });
         }
+
+        this.overlayContainerRects = this.overlayContainer?.getContainerElement().parentElement?.getBoundingClientRect();
     }
 
+    /**
+     * Overrides the base `show` method to display the overlay component with the
+     * specified entry delay and apply default positioning offsets.
+     */
     override show(delay: number = this.enterDelay) {
         super.show(delay);
 
+        this.strategy
+            .withDefaultOffsetX(this.offsetX)
+            .withDefaultOffsetY(this.offsetY)
+
         this.ngZone.onStable
             .asObservable()
             .pipe(take(1))

packages/components/popover/popover.en.md

@@ -82,6 +82,13 @@ The close button can be placed in the header or in the top right corner when the
 
 <!-- example(popover-close) -->
 
+### Layering
+By default, the popover is hidden beneath the horizontal Navbar and Topbar; in other cases, it appears above adjacent elements.
+
+To prevent the popover from overlapping a required element during scrolling and instead have it hidden beneath it, adjust its position using a custom z-index or offset parameters.
+
+<!-- example(popover-scrolling-and-layering) -->
+
 ### Recommendations
 
 When a short text without interactive elements needs to be shown in a popup, use a [tooltip](/en/components/tooltip).

packages/components/popover/popover.ru.md

@@ -82,6 +82,13 @@
 
 <!-- example(popover-close) -->
 
+### Наслоение
+По умолчанию поповер скрывается под горизонтальный Navbar и Topbar, в остальных случаях показывается поверх соседних элементов.
+
+Чтобы поповер не перекрывал нужный вам элемент при прокрутке, а скрывался под ним, настройте положение через кастомный z-index или параметры смещения.
+
+<!-- example(popover-scrolling-and-layering) -->
+
 ### Рекомендации
 
 Когда нужно показать во всплывающем окне короткий текст без интерактивных элементов, то используйте [тултип](/ru/components/tooltip).

packages/components/select/select.component.ts

@@ -82,6 +82,7 @@ import {
     KbqSelectTrigger,
     KbqVirtualOption,
     defaultOffsetY,
+    defaultOffsetX,
     getKbqSelectDynamicMultipleError,
     getKbqSelectNonArrayValueError,
     getKbqSelectNonFunctionValueError,
@@ -248,35 +249,42 @@ export class KbqSelect
     /** Strategy that will be used to handle scrolling while the select panel is open. */
     scrollStrategy = this.scrollStrategyFactory();
 
-    /**
-     * The y-offset of the overlay panel in relation to the trigger's top start corner.
-     * This must be adjusted to align the selected option text over the trigger text.
-     * when the panel opens. Will change based on the y-position of the selected option.
-     */
-    offsetY = defaultOffsetY;
+    /** Calculates the vertical offset relative to the overlay container. */
+    get offsetY(): number {
+        return defaultOffsetY - (this.overlayContainerRects?.y ?? 0);
+    }
+
+    /** Calculates the horizontal offset relative to the overlay container. */
+    get offsetX(): number {
+        return defaultOffsetX - (this.overlayContainerRects?.x ?? 0);
+    }
 
     /**
      * This position config ensures that the top "start" corner of the overlay
      * is aligned with the top "start" of the origin by default (overlapping
      * the trigger completely). If the panel cannot fit below the trigger, it
      * will fall back to a position above the trigger.
      */
-    positions: ConnectedPosition[] = [
-        {
-            originX: 'start',
-            originY: 'bottom',
-            overlayX: 'start',
-            overlayY: 'top',
-            offsetY: this.offsetY
-        },
-        {
-            originX: 'start',
-            originY: 'top',
-            overlayX: 'start',
-            overlayY: 'bottom',
-            offsetY: -this.offsetY
-        }
-    ];
+    get positions(): ConnectedPosition[] {
+        return [
+            {
+                originX: 'start',
+                originY: 'bottom',
+                overlayX: 'start',
+                overlayY: 'top',
+                offsetY: this.offsetY,
+                offsetX: this.offsetX
+            },
+            {
+                originX: 'start',
+                originY: 'top',
+                overlayX: 'start',
+                overlayY: 'bottom',
+                offsetY: -this.offsetY,
+                offsetX: -this.offsetX
+            }
+        ];
+    }
 
     /**
      * Trigger - is a clickable field to open select dropdown panel
@@ -661,6 +669,8 @@ export class KbqSelect
     /** Origin for the overlay panel. */
     protected overlayOrigin?: CdkOverlayOrigin | ElementRef;
 
+    private overlayContainerRects?: DOMRect;
+
     constructor(
         private readonly _changeDetectorRef: ChangeDetectorRef,
         private readonly _ngZone: NgZone,
@@ -764,6 +774,8 @@ export class KbqSelect
                 filter(() => !this.keyManager.activeItem)
             )
             .subscribe(() => this.keyManager.updateActiveItem(0));
+
+        this.overlayContainerRects = this.overlayContainer?.getContainerElement().parentElement?.getBoundingClientRect();
     }
 
     ngOnDestroy() {

packages/components/select/select.en.md

@@ -142,6 +142,13 @@ Add `cdk-virtual-scroll-viewport` to your component template to display only vis
 
 <!-- example(select-virtual-scroll) -->
 
+### Layering
+By default, the dropdown menu is hidden beneath the horizontal Navbar and Topbar; in other cases, it appears above adjacent elements.
+
+To prevent the menu from overlapping a required element during scrolling and instead have it hidden beneath it, adjust its position using a custom z-index or offset parameters.
+
+<!-- example(select-scrolling-and-layering) -->
+
 ### Recommendations
 
 - If you are using a select without a label, we suggest adding a placeholder to indicate what information the user should select. For example, “Country.”

packages/components/select/select.html

@@ -95,7 +95,6 @@
     [cdkConnectedOverlayBackdropClass]="backdropClass"
     [cdkConnectedOverlayHasBackdrop]="hasBackdrop"
     [cdkConnectedOverlayMinWidth]="overlayMinWidth"
-    [cdkConnectedOverlayOffsetY]="offsetY"
     [cdkConnectedOverlayOpen]="panelOpen"
     [cdkConnectedOverlayOrigin]="overlayOrigin || fallbackOverlayOrigin"
     [cdkConnectedOverlayPanelClass]="overlayPanelClass"

packages/components/select/select.ru.md

@@ -141,6 +141,13 @@ import { kbqSelectOptionsProvider } from '@koobiq/components/select';
 
 <!-- example(select-virtual-scroll) -->
 
+### Наслоение
+По умолчанию выпадающее меню скрывается под горизонтальный Navbar и Topbar, в остальных случаях показывается поверх соседних элементов.
+
+Чтобы меню не перекрывало нужный вам элемент при прокрутке, а скрывалось под ним, настройте положение через кастомный z-index или параметры смещения.
+
+<!-- example(select-scrolling-and-layering) -->
+
 ### Рекомендации
 
 - Если вы используете селект без лейбла, то советуем добавить placeholder для указания, какую информацию пользователь должен выбрать. Например, «Страна».