Merge branch 'ng-select:master' into master

Author: pavankjadda

src/demo/app/examples/examples.ts

@@ -44,6 +44,7 @@ import { SearchEditableExampleComponent } from './search-editable-example/search
 import { TemplatePlaceholderExampleComponent } from './template-placeholder-example/template-placeholder-example.component';
 import { FixedPlaceholderExampleComponent } from './fixed-placeholder-example/fixed-placeholder-example.component';
 import { TemplateClearExampleComponent } from './template-clear-example/template-clear-example.component';
+import { PopoverExampleComponent } from './popover-example/popover-example.component';
 
 export interface Example {
 	component: any;
@@ -235,4 +236,8 @@ export const EXAMPLE_COMPONENTS: { [key: string]: Example } = {
 		component: GroupChildrenExampleComponent,
 		title: 'Items with already grouped children array',
 	},
+	'popover-example': {
+		component: PopoverExampleComponent,
+		title: 'Popover top layer',
+	},
 };

src/demo/app/examples/popover-example/popover-example.component.html

@@ -0,0 +1,46 @@
+<p>
+	By default dropdown panel is rendered in the normal document flow, not in the browser's native
+	<a href="https://developer.mozilla.org/en-US/docs/Web/API/Popover_API" target="_blank">top layer</a>.
+</p>
+
+<p>
+	If ng-select is placed inside an element with <code>overflow: hidden</code>, or inside a component that is already rendered in a
+	top-layer, the dropdown panel can be clipped or appear behind that container.
+</p>
+
+<p>It can be fixed by setting <b>[popover]="true"</b>, which forces the dropdown panel to be displayed in a top-layer.</p>
+
+<h6>Without popover - dropdown stays in normal flow</h6>
+<div class="clipped-box">
+	<ng-select [items]="people()" bindLabel="name" [popover]="false" placeholder="Select a person" [(ngModel)]="selected1"> </ng-select>
+</div>
+
+<br />
+
+<h6>With popover - dropdown is rendered in a top-layer</h6>
+<div class="clipped-box">
+	<ng-select [items]="people()" bindLabel="name" [popover]="true" placeholder="Select a person" [(ngModel)]="selected2"> </ng-select>
+</div>
+
+<br />
+
+<div class="alert alert-info">
+	<strong>Use <code>[popover]="true"</code> when:</strong>
+	<ul class="mb-0 mt-1">
+		<li>
+			The select is inside a container with <code>overflow: hidden</code>, <code>overflow: auto</code> or <code>overflow: clip</code>
+		</li>
+		<li>The select is rendered inside a modal, dialog or any other component already using the HTML top-layer</li>
+		<li>The dropdown appears behind another element because of stacking context or z-index constraints</li>
+	</ul>
+	<br />
+	<strong>Avoid it when:</strong>
+	<ul class="mb-0 mt-1">
+		<li>You are already using <code>appendTo</code>; both options solve similar positioning problems and should not be combined</li>
+		<li>
+			You need to support browsers without the
+			<a href="https://caniuse.com/mdn-api_htmlelement_showpopover" target="_blank">Popover API</a> (Chrome 114+, Firefox 125+, Safari
+			17+)
+		</li>
+	</ul>
+</div>

src/demo/app/examples/popover-example/popover-example.component.scss

@@ -0,0 +1,22 @@
+.clipped-box {
+	padding: 10px;
+	height: 80px;
+	border: 1px solid #999;
+	overflow: hidden;
+}
+
+.alert-info {
+	background-color: #d1ecf1;
+	border-color: #bee5eb;
+	color: #0c5460;
+	padding: 0.75rem 1.25rem;
+	border-radius: 4px;
+
+	ul {
+		padding-left: 1.2rem;
+	}
+
+	a {
+		color: #0c5460;
+	}
+}

src/demo/app/examples/popover-example/popover-example.component.ts

@@ -0,0 +1,19 @@
+import { Component, inject } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { NgSelectComponent } from '@ng-select/ng-select';
+import { DataService, Person } from '../data.service';
+import { toSignal } from '@angular/core/rxjs-interop';
+
+@Component({
+	selector: 'ng-popover-example',
+	templateUrl: './popover-example.component.html',
+	styleUrls: ['./popover-example.component.scss'],
+	imports: [NgSelectComponent, FormsModule],
+})
+export class PopoverExampleComponent {
+	private dataService = inject(DataService);
+
+	people = toSignal<Person[]>(this.dataService.getPeople());
+	selected1: Person;
+	selected2: Person;
+}

src/demo/app/routes.ts

@@ -40,5 +40,10 @@ export const appRoutes: Routes = [
 		component: RouteViewerComponent,
 		data: { title: 'Append to element', examples: 'append-to' },
 	},
+	{
+		path: 'popover',
+		component: RouteViewerComponent,
+		data: { title: 'Popover', examples: 'popover' },
+	},
 	{ path: 'grouping', component: RouteViewerComponent, data: { title: 'Grouping', examples: 'group' } },
 ];

src/ng-select/lib/ng-dropdown-panel.component.ts

@@ -71,6 +71,7 @@ export class NgDropdownPanelComponent implements OnInit, OnChanges {
 	 * Which DOM event to listen to for outside click detection
 	 */
 	readonly outsideClickEvent = input<'click' | 'mousedown'>('click');
+	readonly popover = input(false, { transform: booleanAttribute });
 	readonly update = output<any[]>();
 	readonly scroll = output<{
 		start: number;
@@ -141,6 +142,7 @@ export class NgDropdownPanelComponent implements OnInit, OnChanges {
 		this._appendDropdown();
 		this._setupMousedownListener();
 		this._handleWindowScroll();
+		this._showPopoverIfNeeded();
 	}
 
 	ngOnChanges(changes: SimpleChanges) {
@@ -196,7 +198,7 @@ export class NgDropdownPanelComponent implements OnInit, OnChanges {
 			this._updateDropdownClass('bottom');
 		}
 
-		if (this.appendTo()) {
+		if (this.appendTo() || this.popover()) {
 			this._updateYPosition();
 		}
 
@@ -463,7 +465,7 @@ export class NgDropdownPanelComponent implements OnInit, OnChanges {
 	}
 
 	private _handleWindowScroll() {
-		if (!this.appendTo()) {
+		if (!this.appendTo() && !this.popover()) {
 			return;
 		}
 		this._zone.runOutsideAngular(() => {
@@ -475,4 +477,17 @@ export class NgDropdownPanelComponent implements OnInit, OnChanges {
 				});
 		});
 	}
+
+	private _showPopoverIfNeeded() {
+		if (!this.popover()) {
+			return;
+		}
+		if (typeof this._dropdown.showPopover === 'function') {
+			this._renderer.setAttribute(this._dropdown, 'popover', 'manual');
+			this._dropdown.showPopover();
+			this._parent = globalThis.document.body;
+			this._updateXPosition();
+			this._updateYPosition();
+		}
+	}
 }

src/ng-select/lib/ng-select.component.html

@@ -106,7 +106,8 @@
 		[class.ng-select-multiple]="multiple()"
 		[class]="appendToValue ? (ngClass() ? ngClass() : classes) : null"
 		[id]="dropdownId"
-		[ariaLabelDropdown]="ariaLabelDropdown() ?? config.ariaLabelDropdown">
+		[ariaLabelDropdown]="ariaLabelDropdown() ?? config.ariaLabelDropdown"
+		[popover]="popover()">
 		<ng-container>
 			@for (item of viewPortItems; track trackByOption($index, item)) {
 				<!-- eslint-disable-next-line @angular-eslint/template/click-events-have-key-events, @angular-eslint/template/interactive-supports-focus, @angular-eslint/template/mouse-events-have-key-events -->

src/ng-select/lib/ng-select.component.spec.ts

@@ -1901,6 +1901,96 @@ describe('NgSelectComponent', () => {
 			const listboxElement = fixture.debugElement.nativeElement.querySelector('.ng-dropdown-panel-items[role="listbox"]');
 			expect(listboxElement.getAttribute('aria-label')).toBe('Template Aria Label');
 		}));
+
+		describe('Popover', () => {
+			it('should have popover input with default value false', fakeAsync(() => {
+				const fixture = createTestingModule(NgSelectTestComponent, `<ng-select [items]="cities" bindLabel="name"></ng-select>`);
+
+				const select = fixture.componentInstance.select();
+				expect(select.popover()).toBe(false);
+			}));
+
+			it('should pass popover false to dropdown panel by default', fakeAsync(() => {
+				const fixture = createTestingModule(NgSelectTestComponent, `<ng-select [items]="cities" bindLabel="name"></ng-select>`);
+
+				const select = fixture.componentInstance.select();
+				select.open();
+				tickAndDetectChanges(fixture);
+
+				const dropdownPanel = select.dropdownPanel();
+				expect(dropdownPanel.popover()).toBe(false);
+
+				const panelElement = fixture.debugElement.nativeElement.querySelector('.ng-dropdown-panel');
+				expect(panelElement?.matches(':popover-open')).toBe(false);
+			}));
+
+			it('should pass popover true to dropdown panel when set to true', fakeAsync(() => {
+				const fixture = createTestingModule(
+					NgSelectTestComponent,
+					`<ng-select [items]="cities" bindLabel="name" [popover]="true"></ng-select>`,
+				);
+
+				const select = fixture.componentInstance.select();
+				expect(select.popover()).toBe(true);
+
+				select.open();
+				tickAndDetectChanges(fixture);
+
+				const dropdownPanel = select.dropdownPanel();
+				expect(dropdownPanel.popover()).toBe(true);
+
+				const panelElement = fixture.debugElement.nativeElement.querySelector('.ng-dropdown-panel');
+				expect(panelElement?.matches(':popover-open')).toBe(true);
+			}));
+
+			it('should pass popover false to dropdown panel when explicitly set to false', fakeAsync(() => {
+				const fixture = createTestingModule(
+					NgSelectTestComponent,
+					`<ng-select [items]="cities" bindLabel="name" [popover]="false"></ng-select>`,
+				);
+
+				const select = fixture.componentInstance.select();
+				expect(select.popover()).toBe(false);
+
+				select.open();
+				tickAndDetectChanges(fixture);
+
+				const dropdownPanel = select.dropdownPanel();
+				expect(dropdownPanel.popover()).toBe(false);
+
+				const panelElement = fixture.debugElement.nativeElement.querySelector('.ng-dropdown-panel');
+				expect(panelElement?.matches(':popover-open')).toBe(false);
+			}));
+
+			it('should toggle popover value dynamically', fakeAsync(() => {
+				const fixture = createTestingModule(
+					NgSelectTestComponent,
+					`<ng-select [items]="cities" bindLabel="name" [popover]="popoverEnabled"></ng-select>`,
+				);
+
+				const component = fixture.componentInstance as any;
+				component.popoverEnabled = false;
+				fixture.detectChanges();
+
+				let select = fixture.componentInstance.select();
+				expect(select.popover()).toBe(false);
+
+				component.popoverEnabled = true;
+				fixture.detectChanges();
+
+				select = fixture.componentInstance.select();
+				expect(select.popover()).toBe(true);
+
+				select.open();
+				tickAndDetectChanges(fixture);
+
+				const dropdownPanel = select.dropdownPanel();
+				expect(dropdownPanel.popover()).toBe(true);
+
+				const panelElement = fixture.debugElement.nativeElement.querySelector('.ng-dropdown-panel');
+				expect(panelElement?.matches(':popover-open')).toBe(true);
+			}));
+		});
 	});
 
 	describe('Keyboard events', () => {
@@ -5518,6 +5608,7 @@ class NgSelectTestComponent {
 	typeahead = undefined;
 	preventToggleOnRightClick = false;
 	searchWhileComposing = true;
+	popoverEnabled = false;
 
 	citiesLoading = false;
 	selectedCityId: number;

src/ng-select/lib/ng-select.component.ts

@@ -161,6 +161,7 @@ export class NgSelectComponent implements OnChanges, OnInit, AfterViewInit, Cont
 		},
 	});
 	readonly keyDownFn = input<(_: KeyboardEvent) => boolean>((_: KeyboardEvent) => true);
+	readonly popover = input(false, { transform: booleanAttribute });
 
 	// models
 	readonly bindLabel = model<string>(undefined);