ng-primitives 0.112.3 → 0.114.0

package/portal/index.d.ts

@@ -4,7 +4,7 @@ import * as _angular_core from '@angular/core';
 import { WritableSignal, TemplateRef, Type, Injector, ViewContainerRef, Signal, Provider, ValueProvider, ApplicationRef } from '@angular/core';
 import { FocusOrigin } from '@angular/cdk/a11y';
 import { Subject } from 'rxjs';
-import { ViewportRuler } from '@angular/cdk/overlay';
+import { ViewportRuler } from '@angular/cdk/scrolling';
 
 /**
  * Options for configuring flip behavior to keep the floating element in view.
@@ -278,11 +278,12 @@ declare class NgpOverlay<T = unknown> implements CooldownOverlay {
     private config;
     private readonly disposables;
     private readonly document;
+    private readonly viewportRuler;
     private readonly destroyRef;
     private readonly viewContainerRef;
-    private readonly viewportRuler;
     private readonly focusMonitor;
     private readonly cooldownManager;
+    private readonly registry;
     /** Access any parent overlays */
     private readonly parentOverlay;
     /** Track child overlays for outside click detection */
@@ -506,6 +507,160 @@ interface OverlayTriggerOptions {
     origin?: FocusOrigin;
 }
 
+/**
+ * A dismiss guard can be a boolean or a callback that returns a boolean (sync or async).
+ * - `true` → always dismiss
+ * - `false` → never dismiss
+ * - `(target) => boolean | Promise<boolean>` → custom logic per interaction
+ */
+type NgpDismissGuard<T = Element> = boolean | ((target: T) => boolean | Promise<boolean>);
+/**
+ * Dismiss policy for an overlay entry.
+ * Determines how the overlay responds to outside clicks and escape key presses.
+ * @internal
+ */
+interface NgpDismissPolicy {
+    /** Whether clicking outside should close this overlay, or a guard function */
+    outsidePress: NgpDismissGuard<Element>;
+    /** Whether pressing Escape should close this overlay, or a guard function */
+    escapeKey: NgpDismissGuard<KeyboardEvent>;
+}
+/**
+ * An entry in the overlay registry representing a single visible overlay.
+ * @internal
+ */
+interface NgpOverlayEntry {
+    /** Unique overlay ID */
+    id: string;
+    /** Parent overlay ID, null for root overlays */
+    parentId: string | null;
+    /** Reference to the overlay instance for calling hide()/hideImmediate() */
+    overlay: NgpOverlayRef;
+    /** Function that returns the portal DOM elements */
+    getElements: () => HTMLElement[];
+    /** The trigger element */
+    triggerElement: HTMLElement;
+    /** Optional anchor element */
+    anchorElement?: HTMLElement | null;
+    /** Per-instance dismiss configuration */
+    dismissPolicy: NgpDismissPolicy;
+    /** Optional subject that receives pointer events that occur outside the overlay */
+    outsidePointerEvents$?: Subject<MouseEvent>;
+}
+/**
+ * Minimal overlay reference needed by the registry.
+ * This avoids a circular dependency with NgpOverlay.
+ * @internal
+ */
+interface NgpOverlayRef {
+    hide(options?: {
+        immediate?: boolean;
+        origin?: FocusOrigin;
+    }): void;
+    hideImmediate(): void;
+}
+/**
+ * Singleton registry that tracks all visible overlays in open order and
+ * provides centralized dismiss routing (outside-click and escape-key).
+ *
+ * Document listeners are attached when the first overlay registers and
+ * detached when the last deregisters, avoiding permanent global listeners.
+ * @internal
+ */
+declare class NgpOverlayRegistry {
+    private readonly document;
+    private readonly ngZone;
+    /** Ordered list of visible overlay entries (oldest first, newest/topmost last) */
+    private readonly entries;
+    /** Set of overlay IDs currently evaluating an async dismiss guard */
+    private readonly pendingGuardIds;
+    /** Cleanup functions for the centralized document listeners */
+    private removeOutsideClickListener?;
+    private removeEscapeKeyListener?;
+    private removeOutsidePointerListeners?;
+    /** Tracks the pointerdown target for CDK-compatible outside pointer event dispatch */
+    private pointerDownTarget;
+    /**
+     * Register an overlay as visible. The entry is appended to the end of the list
+     * (making it the topmost overlay). Attaches document listeners if this is the
+     * first entry.
+     */
+    register(entry: NgpOverlayEntry): void;
+    /**
+     * Remove an overlay from the registry.
+     * Detaches document listeners if no entries remain.
+     */
+    deregister(id: string): void;
+    /**
+     * Close all descendants of the given overlay.
+     * Called by NgpOverlay when it hides to cascade the close to children.
+     */
+    closeDescendants(id: string): void;
+    /**
+     * Get all registered entries.
+     */
+    getEntries(): readonly NgpOverlayEntry[];
+    /**
+     * Get the topmost (most recently opened) overlay entry, or null if none.
+     */
+    getTopmost(): NgpOverlayEntry | null;
+    /**
+     * Find the overlay whose elements contain the given DOM element.
+     * Returns the ID of the most recently opened (topmost) containing overlay, or null.
+     */
+    findContainingOverlay(element: HTMLElement): string | null;
+    /**
+     * Check whether overlay `ancestorId` is an ancestor of overlay `descendantId`
+     * by walking the parentId chain.
+     */
+    isAncestorOf(ancestorId: string, descendantId: string): boolean;
+    /**
+     * Get all descendants of the given overlay (children, grandchildren, etc.)
+     * by walking parentId chains of all entries.
+     */
+    getDescendants(id: string): NgpOverlayEntry[];
+    /**
+     * Attach centralized document listeners for outside-click and escape-key.
+     * Runs outside Angular zone to avoid unnecessary change detection on every
+     * mouse/keyboard event.
+     */
+    private attachListeners;
+    /**
+     * Detach centralized document listeners.
+     */
+    private detachListeners;
+    /**
+     * Outside-click dismiss: only the topmost overlay responds.
+     */
+    private handleOutsideClick;
+    /**
+     * Escape-key dismiss: only the topmost overlay responds.
+     */
+    private handleEscapeKey;
+    /**
+     * CDK-compatible outside pointer event dispatch.
+     * Iterates overlays from topmost to oldest (like CDK's OverlayOutsideClickDispatcher).
+     * For each overlay with an outsidePointerEvents$ subject, emits the event if the
+     * click was outside its elements. Stops iterating when an overlay contains the click.
+     */
+    private handleOutsidePointerEvent;
+    /**
+     * Get the composed event target, piercing shadow DOM boundaries.
+     */
+    private getComposedTarget;
+    /**
+     * Check whether any of the given elements contain the target, piercing shadow DOM.
+     */
+    private containsElement;
+    /**
+     * Evaluate a dismiss guard and call the dismiss function if allowed.
+     * Supports boolean values and sync/async guard functions.
+     */
+    private evaluateGuardAndDismiss;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgpOverlayRegistry, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NgpOverlayRegistry>;
+}
+
 /**
  * The state interface for the overlay arrow.
  */
@@ -759,5 +914,5 @@ declare class NoopScrollStrategy implements ScrollStrategy {
     disable(): void;
 }
 
-export { BlockScrollStrategy, CloseScrollStrategy, NgpComponentPortal, NgpOverlay, NgpOverlayArrowStateToken, NgpOverlayCooldownManager, NgpPortal, NgpTemplatePortal, NoopScrollStrategy, coerceFlip, coerceOffset, coerceShift, createOverlay, createPortal, injectOverlay, injectOverlayArrowState, injectOverlayContext, ngpOverlayArrow, provideOverlayArrowState, provideOverlayContext };
-export type { NgpFlip, NgpFlipInput, NgpFlipOptions, NgpOffset, NgpOffsetInput, NgpOffsetOptions, NgpOverlayArrowProps, NgpOverlayArrowState, NgpOverlayConfig, NgpOverlayContent, NgpOverlayTemplateContext, NgpPosition, NgpShift, NgpShiftInput, NgpShiftOptions, ScrollStrategy };
+export { BlockScrollStrategy, CloseScrollStrategy, NgpComponentPortal, NgpOverlay, NgpOverlayArrowStateToken, NgpOverlayCooldownManager, NgpOverlayRegistry, NgpPortal, NgpTemplatePortal, NoopScrollStrategy, coerceFlip, coerceOffset, coerceShift, createOverlay, createPortal, injectOverlay, injectOverlayArrowState, injectOverlayContext, ngpOverlayArrow, provideOverlayArrowState, provideOverlayContext };
+export type { NgpDismissGuard, NgpDismissPolicy, NgpFlip, NgpFlipInput, NgpFlipOptions, NgpOffset, NgpOffsetInput, NgpOffsetOptions, NgpOverlayArrowProps, NgpOverlayArrowState, NgpOverlayConfig, NgpOverlayContent, NgpOverlayEntry, NgpOverlayRef, NgpOverlayTemplateContext, NgpPosition, NgpShift, NgpShiftInput, NgpShiftOptions, ScrollStrategy };