ng-hub-ui-portal
Version:
A flexible Angular portal library for dynamic content rendering with advanced positioning and interaction control
401 lines (392 loc) • 16.5 kB
TypeScript
import * as i0 from '@angular/core';
import { Injector, OnInit, OnDestroy, ComponentRef, EventEmitter } from '@angular/core';
import { ContentRef } from 'ng-hub-ui-utils';
import { Subject, Observable } from 'rxjs';
/**
* Options available when opening new portal windows with `HubPortal.open()` method.
*/
interface HubPortalOptions {
/**
* If `true`, portal opening and closing will be animated.
*
* @since 8.0.0
*/
animation?: boolean;
/**
* `aria-labelledby` attribute value to set on the portal window.
*
* @since 2.2.0
*/
ariaLabelledBy?: string;
/**
* `aria-describedby` attribute value to set on the portal window.
*
* @since 6.1.0
*/
ariaDescribedBy?: string;
/**
* Callback right before the portal will be dismissed.
*
* If this function returns:
* * `false`
* * a promise resolved with `false`
* * a promise that is rejected
*
* then the portal won't be dismissed.
*/
beforeDismiss?: () => boolean | Promise<boolean>;
/**
* A selector specifying the element all new portal windows should be appended to.
* Since v5.3.0 it is also possible to pass the reference to an `HTMLElement`.
*
* If not specified, will be `body`.
*/
container?: string | HTMLElement;
/**
* The `Injector` to use for portal content.
*/
injector?: Injector;
/**
* If `true`, the portal will be closed when `Escape` key is pressed
*
* Default value is `true`.
*/
keyboard?: boolean;
/**
* Scrollable portal content (false by default).
*
* @since 5.0.0
*/
scrollable?: boolean;
/**
* A custom class to append to the portal window.
*/
windowClass?: string;
/**
* A custom class to append to the portal dialog.
*
* @since 9.1.0
*/
portalDialogClass?: string;
/**
* A custom class to append to the portal content.
*
* @since 9.1.0
*/
portalContentClass?: string;
/**
* Allows to specify a custom selector for the header element of the portal window. This can be useful if you want to target
* a specific element within the portal to act as the header, for example, to apply custom styling or functionality to it. By
* providing a CSS selector string, you can target the desired header element within the portal content.
*/
headerSelector?: string;
/**
* Allows to specify a custom selector for the footer element of the portal window. This can be useful if you want to target
* a specific element within the portal to act as the footer, for example, to apply custom styling or functionality to it. By
* providing a CSS selector string, you can target the desired footer element within the portal content.
*/
footerSelector?: string;
/** Used to specify a custom selector for elements that can trigger the dismissal of the portal window. By providing a CSS selector
* string for `dismissSelector`, you can target specific elements within the portal content that, when interacted with (e.g., clicked),
* will close or dismiss the portal window.
*/
dismissSelector?: string;
/**
* Used to specify a custom selector for elements that can trigger the closing of the portal window. By providing a CSS selector
* string for `closeSelector`, you can target specific elements within the portal content that, when interacted with (e.g., clicked),
* will close the portal window. This allows for customization of the elements that can act as close buttons for the portal.
*/
closeSelector?: string;
}
/**
* Options that can be changed on an opened portal with `HubPortalRef.update()` and `HubActivePortal.update()` methods.
*
* @since 14.2.0
*/
type HubPortalUpdatableOptions = Pick<HubPortalOptions, 'ariaLabelledBy' | 'ariaDescribedBy' | 'windowClass' | 'portalDialogClass' | 'portalContentClass'>;
/**
* A configuration service for the [`HubPortal`](#/components/portal/api#HubPortal) service.
*
* You can inject this service, typically in your root component, and customize the values of its properties in
* order to provide default values for all portals used in the application.
*
* @since 3.1.0
*/
declare class HubPortalConfig implements Required<HubPortalOptions> {
private _animation?;
ariaLabelledBy: string;
ariaDescribedBy: string;
beforeDismiss: () => boolean | Promise<boolean>;
container: string | HTMLElement;
injector: Injector;
keyboard: boolean;
scrollable: boolean;
windowClass: string;
portalDialogClass: string;
portalContentClass: string;
headerSelector: string;
footerSelector: string;
dismissSelector: string;
closeSelector: string;
get animation(): boolean;
set animation(animation: boolean);
static ɵfac: i0.ɵɵFactoryDeclaration<HubPortalConfig, never>;
static ɵprov: i0.ɵɵInjectableDeclaration<HubPortalConfig>;
}
declare class HubPortalWindow implements OnInit, OnDestroy {
private _document;
private _elRef;
private _zone;
private _closed$;
private _elWithFocus;
private readonly _dialogEl;
readonly animation: i0.InputSignal<boolean>;
readonly ariaLabelledBy: i0.InputSignal<string | undefined>;
readonly ariaDescribedBy: i0.InputSignal<string | undefined>;
readonly scrollable: i0.InputSignal<string | undefined>;
readonly windowClass: i0.InputSignal<string | undefined>;
readonly portalDialogClass: i0.InputSignal<string | undefined>;
readonly portalContentClass: i0.InputSignal<string | undefined>;
singleContent: boolean;
readonly dismissEvent: i0.OutputEmitterRef<void>;
shown: Subject<void>;
hidden: Subject<void>;
dismiss(reason: any): void;
ngOnInit(): void;
ngOnDestroy(): void;
hide(): Observable<any>;
private _show;
private _disableEventHandling;
private _setFocus;
private _restoreFocus;
static ɵfac: i0.ɵɵFactoryDeclaration<HubPortalWindow, never>;
static ɵcmp: i0.ɵɵComponentDeclaration<HubPortalWindow, "hub-portal-window", never, { "animation": { "alias": "animation"; "required": false; "isSignal": true; }; "ariaLabelledBy": { "alias": "ariaLabelledBy"; "required": false; "isSignal": true; }; "ariaDescribedBy": { "alias": "ariaDescribedBy"; "required": false; "isSignal": true; }; "scrollable": { "alias": "scrollable"; "required": false; "isSignal": true; }; "windowClass": { "alias": "windowClass"; "required": false; "isSignal": true; }; "portalDialogClass": { "alias": "portalDialogClass"; "required": false; "isSignal": true; }; "portalContentClass": { "alias": "portalContentClass"; "required": false; "isSignal": true; }; }, { "dismissEvent": "dismiss"; }, never, ["*", "*", "*", "*"], true, never>;
}
/**
* A reference to the currently opened (active) portal.
*
* Instances of this class can be injected into your component passed as portal content.
* So you can `.update()`, `.close()` or `.dismiss()` the portal window from your component.
*/
declare class HubActivePortal {
/**
* Updates options of an opened portal.
*
* @since 14.2.0
*/
update(options: HubPortalUpdatableOptions): void;
/**
* Closes the portal with an optional `result` value.
*
* The `HubPortalRef.result` promise will be resolved with the provided value.
*/
close(result?: any): void;
/**
* Dismisses the portal with an optional `reason` value.
*
* The `HubPortalRef.result` promise will be rejected with the provided value.
*/
dismiss(reason?: any): void;
}
/**
* A reference to the newly opened portal returned by the `HubPortal.open()` method.
*/
declare class HubPortalRef {
private _windowCmptRef;
private _contentRef;
private _beforeDismiss?;
private _closed;
private _dismissed;
private _hidden;
private _resolve;
private _reject;
private _applyWindowOptions;
/**
* Updates options of an opened portal.
*
* @since 14.2.0
*/
update(options: HubPortalUpdatableOptions): void;
/**
* The instance of a component used for the portal content.
*
* When a `TemplateRef` is used as the content or when the portal is closed, will return `undefined`.
*/
get componentInstance(): any;
/**
* The promise that is resolved when the portal is closed and rejected when the portal is dismissed.
*/
result: Promise<any>;
/**
* The observable that emits when the portal is closed via the `.close()` method.
*
* It will emit the result passed to the `.close()` method.
*/
get closed(): Observable<any>;
/**
* The observable that emits when the portal is dismissed via the `.dismiss()` method.
*
* It will emit the reason passed to the `.dismissed()` method by the user.
*/
get dismissed(): Observable<any>;
/**
* The observable that emits when portal window is closed and animations were finished.
* At this point portal element will be removed from the DOM tree.
*
* This observable will be completed after emitting.
*/
get hidden(): Observable<void>;
/**
* The observable that emits when portal is fully visible and animation was finished.
* Portal DOM element is always available synchronously after calling 'portal.open()' service.
*
* This observable will be completed after emitting.
* It will not emit, if portal is closed before open animation is finished.
*/
get shown(): Observable<void>;
constructor(_windowCmptRef: ComponentRef<HubPortalWindow>, _contentRef: ContentRef, _beforeDismiss?: (() => boolean | Promise<boolean>) | undefined);
/**
* Closes the portal with an optional `result` value.
*
* The `HubMobalRef.result` promise will be resolved with the provided value.
*/
close(result?: any): void;
private _dismiss;
/**
* Dismisses the portal with an optional `reason` value.
*
* The `HubPortalRef.result` promise will be rejected with the provided value.
*/
dismiss(reason?: any): void;
private _removePortalElements;
}
/**
* A service for opening portal windows.
*
* Creating a portal is straightforward: create a component or a template and pass it as an argument to
* the `.open()` method.
*/
declare class HubPortal {
private _injector;
private _portalStack;
private _config;
/**
* Opens a new portal window with the specified content and supplied options.
*
* Content can be provided as a `TemplateRef` or a component type. If you pass a component type as content,
* then instances of those components can be injected with an instance of the `HubActivePortal` class. You can then
* use `HubActivePortal` methods to close / dismiss portals from "inside" of your component.
*
* Also see the [`HubPortalOptions`](#/components/portal/api#HubPortalOptions) for the list of supported options.
*/
open(content: any, options?: HubPortalOptions): HubPortalRef;
/**
* The function `toggle` opens a portal with specified content and options while dismissing any existing portals.
*
* @param {any} content - The `content` parameter in the `toggle` function is the content that you want to display within the
* portal. This can be any type of content such as a component, template, or any other HTML element that you want to show in the
* portal.
* @param {HubPortalOptions} options - The `options` parameter in the `toggle` function is an object that allows you to customize
* the behavior of the portal.
*
* @returns The `toggle` function is returning a `HubPortalRef` object.
*/
toggle(content: any, options?: HubPortalOptions): HubPortalRef;
/**
* Returns an observable that holds the active portal instances.
*/
get activeInstances(): i0.EventEmitter<HubPortalRef[]>;
/**
* Dismisses all currently displayed portal windows with the supplied reason.
*
* @since 3.1.0
*/
dismissAll(reason?: any): void;
/**
* Indicates if there are currently any open portal windows in the application.
*
* @since 3.3.0
*/
hasOpenPortals(): boolean;
static ɵfac: i0.ɵɵFactoryDeclaration<HubPortal, never>;
static ɵprov: i0.ɵɵInjectableDeclaration<HubPortal>;
}
declare class HubPortalStack {
private _applicationRef;
private _injector;
private _environmentInjector;
private _document;
private _scrollBar;
private _activeWindowCmptHasChanged;
private _ariaHiddenValues;
private _scrollBarRestoreFn;
private _portalRefs;
private _windowCmpts;
private _activeInstances;
constructor();
private _restoreScrollBar;
private _hideScrollBar;
open(contentInjector: Injector, content: any, options: HubPortalOptions): HubPortalRef;
/**
* Toggles a portal by dismissing all existing portals and waiting for them to be hidden
* before showing the new one.
*
* @param contentInjector - The injector to use for dependency injection
* @param content - The content to display (component, template, or string)
* @param options - Portal configuration options
* @returns A reference to the newly created portal
*/
toggle(contentInjector: Injector, content: any, options: HubPortalOptions): HubPortalRef;
get activeInstances(): EventEmitter<HubPortalRef[]>;
dismissAll(reason?: any): void;
hasOpenPortals(): boolean;
private _createWindowComponent;
private _attachWindowComponent;
private _getContentRef;
private _createFromTemplateRef;
private _createFromString;
private _createFromComponent;
private _setAriaHidden;
private _revertAriaHidden;
private _registerPortalRef;
private _registerWindowCmpt;
/**
* Attaches click event listeners to elements within a container based on a specified dismiss selector to dismiss a portal.
*
* @param {HTMLElement} container - The `container` parameter is an HTMLElement that represents the DOM element which contains the
* portal content.
* @param {HubActivePortal} context - The `context` parameter in the `_addDismissEventListener` function refers to the active portal
* instance that is being displayed. It is used to call the `dismiss` method on the portal instance when a dismissible element is
* clicked.
* @param {HubPortalOptions} options - The `options` parameter is an object that contains configuration options for the portal. It
* may include properties such as `dismissSelector`, which is used to specify a CSS selector for elements that, when clicked, will
* dismiss the portal by calling the `dismiss` method on the `context` object.
*/
private _addDismissEventListener;
/**
* Attaches click event listeners to elements matching a specified selector to close a portal window.
*
* @param {HTMLElement} container - The `container` parameter is an HTMLElement that represents the DOM element which contains the
* portal content.
* @param {HubActivePortal} context - The `context` parameter in the `_addCloseEventListener` function is of type `HubActivePortal`.
* It is used to reference the active portal instance within the function and call the `close()` method on it when a close event is
* triggered.
* @param {HubPortalOptions} options - The `options` parameter is an object that contains configuration options for the portal. It
* may include properties such as `closeSelector`, which is used to specify the selector for elements that can trigger the portal
* to close when clicked.
*/
private _addCloseEventListener;
static ɵfac: i0.ɵɵFactoryDeclaration<HubPortalStack, never>;
static ɵprov: i0.ɵɵInjectableDeclaration<HubPortalStack>;
}
declare enum PortalDismissReasons {
BACKDROP_CLICK = 0,
ESC = 1
}
declare class HubPortalModule {
static ɵfac: i0.ɵɵFactoryDeclaration<HubPortalModule, never>;
static ɵmod: i0.ɵɵNgModuleDeclaration<HubPortalModule, never, never, never>;
static ɵinj: i0.ɵɵInjectorDeclaration<HubPortalModule>;
}
export { HubActivePortal, HubPortal, HubPortalConfig, HubPortalModule, HubPortalRef, HubPortalStack, PortalDismissReasons };
export type { HubPortalOptions, HubPortalUpdatableOptions };