@almoamendev/ngx-md3 0.0.16 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almoamendev/ngx-md3",
-  "version": "0.0.16",
+  "version": "0.2.0",
   "description": "MD3-style Angular components & style library",
   "author": "Murtadha (Hussain) Almoamen",
   "license": "MIT",

package/types/almoamendev-ngx-md3.d.ts

@@ -1,9 +1,10 @@
 import * as _angular_core from '@angular/core';
-import { ViewContainerRef, Injector, ElementRef, AfterViewInit, OnDestroy, OnInit, Renderer2, Signal, InputSignal, AfterContentInit, Type, ComponentRef, InjectionToken, TemplateRef } from '@angular/core';
+import { ViewContainerRef, Injector, ElementRef, AfterViewInit, OnDestroy, OnInit, Renderer2, Signal, InputSignal, InjectionToken, Type, AfterContentInit, ComponentRef, TemplateRef } from '@angular/core';
 import { FlexibleConnectedPositionStrategyOrigin, ConnectedPosition, OverlayRef } from '@angular/cdk/overlay';
 import * as i1 from '@angular/cdk/scrolling';
 import { AbstractControl } from '@angular/forms';
 import * as i1$1 from '@angular/router';
+import { CdkDialogContainer, DialogRef as DialogRef$1 } from '@angular/cdk/dialog';
 import { Observable } from 'rxjs';
 import { CdkPortalOutlet } from '@angular/cdk/portal';
 
@@ -43,6 +44,12 @@ type ListLeadingType = 'icon' | 'avatar' | 'media' | 'selection-input';
 
 type ListLeadingSize = 'image' | 'small-video' | 'large-video';
 
+/**
+ * What happens to a dialog that is already open when a new dialog opens.
+ * - close: the open dialogs are closed before the new one opens.
+ * - hide: the dialog on top is hidden and shown again once the new one closes.
+ */
+type PreviousDialog = 'close' | 'hide';
 interface DialogConfig<D = unknown> {
     /**
      * Optional data passed to the component opened inside the dialog.
@@ -55,6 +62,11 @@ interface DialogConfig<D = unknown> {
      */
     bindDataToInputs?: boolean;
     disableCloseEvents?: boolean;
+    /**
+     * What happens to a dialog that is already open when this dialog opens.
+     * A hidden dialog keeps its state and is shown again once this dialog closes.
+     */
+    previousDialog?: PreviousDialog;
     role?: DialogRole;
     ariaLabel?: string;
     ariaLabelledBy?: string;
@@ -68,6 +80,27 @@ interface DialogConfig<D = unknown> {
     viewContainerRef?: ViewContainerRef;
     injector?: Injector;
 }
+/**
+ * What DialogRef needs from the shell hosting a dialog. Implemented by both the
+ * regular dialog and the full screen dialog, so the reference can drive either.
+ */
+interface DialogContainer {
+    /** Element that plays the enter and exit transition. */
+    readonly surfaceElement: HTMLElement | null;
+    /** Starts the enter animation. Delayed when the dialog replaces another one. */
+    startEnterAnimation(): void;
+    /** Shows or hides the surface, which is what drives both transitions. */
+    setActive(value: boolean): void;
+    /** Moves focus back inside the dialog when it is not there already. */
+    recaptureFocus(): void;
+}
+
+/**
+ * Configuration of a full screen dialog. It is the dialog configuration without
+ * `previousDialog`: a full screen dialog always replaces the one that is open,
+ * because only one of them can be open at a time.
+ */
+type FullScreenDialogConfig<D = unknown> = Omit<DialogConfig<D>, 'previousDialog'>;
 
 type MenuPositionX = 'start' | 'end' | 'before' | 'after' | 'center';
 type MenuPositionY = 'above' | 'below' | 'center';
@@ -934,17 +967,24 @@ declare class SupportingText {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SupportingText, "[md3-supporting-text]", never, {}, {}, never, never, true, never>;
 }
 
-declare class Dialog implements AfterContentInit {
-    private readonly portalOutlet;
+/**
+ * Material 3 dialog shell. It extends the CDK dialog container, so focus
+ * trapping, focus restoration and the ARIA attributes are handled by the CDK
+ * while this component only owns the MD3 surface and its animation.
+ */
+declare class Dialog extends CdkDialogContainer implements DialogContainer {
+    private readonly surface;
     isActive: _angular_core.WritableSignal<boolean>;
     protected readonly config: DialogConfig<unknown>;
-    protected get role(): string;
-    ngAfterContentInit(): void;
+    get surfaceElement(): HTMLElement | null;
     /**
-     * The service creates this wrapper first, then calls this method to mount
-     * the user supplied component into the dialog container.
+     * Started by DialogService, either right after the dialog is created or
+     * once the dialog it replaces has had its head start. The animation runs on
+     * the next frame so the surface has a real from/to state.
      */
-    attachContent<T>(component: Type<T>, injector: Injector): ComponentRef<T>;
+    startEnterAnimation(): void;
+    setActive(value: boolean): void;
+    recaptureFocus(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Dialog, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<Dialog, "md3-dialog", never, {}, {}, never, never, true, never>;
 }
@@ -953,36 +993,120 @@ declare const DIALOG_DATA: InjectionToken<unknown>;
 declare const DIALOG_CONFIG: InjectionToken<DialogConfig<unknown>>;
 declare const DIALOG_COMPONENT: InjectionToken<Type<unknown>>;
 declare class DialogRef<T = unknown, R = unknown> {
-    private readonly overlayRef;
-    private readonly previouslyFocusedElement;
+    private readonly cdkRef;
+    /** Whether this reference belongs to a full screen dialog. */
+    readonly isFullScreen: boolean;
     private readonly closed;
-    private isClosed;
-    dialogInstance?: Dialog;
+    private readonly closing;
+    private closePromise;
+    private closeStarted;
+    private closeSettled;
+    private hidden;
+    /** Shell hosting the dialog: the regular dialog or the full screen one. */
+    dialogInstance?: DialogContainer;
     /**
      * Filled by DialogService after the user component is attached. Keeping the
      * instance here lets callers imperatively update inputs when that is useful.
      */
     componentInstance?: T;
-    constructor(overlayRef: OverlayRef, previouslyFocusedElement: HTMLElement | null);
-    close(result?: R): void;
-    private startCloseAnimation;
+    /** Overlay hosting the dialog, useful to reach the panel and the scrim. */
+    get overlayRef(): OverlayRef;
+    /** Whether the dialog started closing. Such a dialog cannot be hidden or shown anymore. */
+    get isClosing(): boolean;
+    /** Whether the dialog is currently hidden behind another dialog. */
+    get isHidden(): boolean;
+    constructor(cdkRef: DialogRef$1<R, T>, disableCloseEvents: boolean, 
+    /** Whether this reference belongs to a full screen dialog. */
+    isFullScreen?: boolean);
+    /** Closes the dialog. The promise resolves once the exit animation is done. */
+    close(result?: R): Promise<void>;
+    /**
+     * Hides the dialog with the closing animation while keeping it alive, so
+     * its content, form state and subscriptions survive until show() is called.
+     * The promise resolves once the dialog is out of sight.
+     */
+    hide(): Promise<void>;
+    /**
+     * Brings a hidden dialog back with the opening animation. Focus moves back
+     * into the dialog even when it was never hidden, which is what makes it
+     * usable again once the dialog above it closes.
+     */
+    show(): void;
+    /** Emits when the dialog starts closing, before the exit animation runs. */
+    beforeClosed(): Observable<void>;
     afterClosed(): Observable<R | undefined>;
+    private connectCloseEvents;
+    private toggleHiddenState;
+    private startClosing;
+    private startCloseAnimation;
+    /** Resolves when the surface finished animating, with a timeout as a safety net. */
+    private waitForSurfaceAnimation;
+    /** Emits the result once the CDK reference is closed. Focus is restored by the container. */
+    private settle;
 }
 
 declare class DialogService {
+    private readonly cdkDialog;
     private readonly overlay;
     private readonly injector;
     private readonly document;
+    /** Open dialogs, from the first one opened to the one currently on top. */
+    private readonly refs;
+    /**
+     * Page scrolling is blocked here instead of per overlay, so stacked dialogs
+     * cannot unblock the page while another dialog is still open.
+     */
+    private readonly scrollBlock;
+    /** Element that was focused before the first dialog of the stack opened. */
+    private rootTrigger;
+    get openDialogs(): readonly DialogRef<any, any>[];
+    /** The full screen dialog that is open, if there is one. */
+    get fullScreenDialog(): DialogRef<any, any> | undefined;
     open<T, D = unknown, R = unknown>(component: Type<T>, config?: DialogConfig<D>): DialogRef<T, R>;
+    /**
+     * Opens a dialog that covers the whole screen. Only one can be open at a
+     * time, so it replaces whatever is open, and while it is up the side sheet
+     * outlets belong to it: side sheets open inside the dialog, not behind it.
+     */
+    openFullScreen<T, D = unknown, R = unknown>(component: Type<T>, config?: FullScreenDialogConfig<D>): DialogRef<T, R>;
+    /** Wires a freshly created dialog into the stack and starts its animation. */
+    private registerDialog;
+    /** Closes every open dialog, including the hidden and the full screen ones. */
+    closeAll(): Promise<void>;
+    /** Closes the regular dialogs and leaves a full screen dialog alone. */
+    private closeRegularDialogs;
     private mergeConfig;
-    private createOverlay;
+    /**
+     * Hides or closes the dialog that is on screen. Its scrim stays up until
+     * the dialog taking over is ready for it, so the page behind never
+     * brightens between the two dialogs.
+     */
+    private dismissPrevious;
     private startOpenAnimation;
-    private createInjector;
+    /** Opening animation for a dialog that took the place of another one. */
+    private startReplacingAnimation;
+    /** Opening animation for a dialog coming back from behind a closing one. */
+    private startRestoringAnimation;
+    /**
+     * Moves both scrims to their new value in a single frame, without a
+     * transition on either side, so the dim behind the dialogs never changes.
+     */
+    private beginScrimHandover;
+    /** Gives the scrims their transitions back once the handover is painted. */
+    private endScrimHandover;
     private bindDataToInputs;
-    private connectCloseEvents;
-    private focusDialog;
-    private getFocusedElement;
     private canBindDataToInputs;
+    /** Last dialog of the stack that is not closing yet. */
+    private topRef;
+    /**
+     * Same, without the full screen dialog: it hosts the dialogs opened on top
+     * of it, so it is never the one that gets hidden or closed to make room.
+     */
+    private topRegularRef;
+    private restorePreviousDialog;
+    private removeRef;
+    private updateScrollBlock;
+    private getFocusedElement;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DialogService, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<DialogService>;
 }
@@ -1002,6 +1126,42 @@ declare class DialogActions {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<DialogActions, "md3-dialog-actions", never, {}, {}, never, ["*"], true, never>;
 }
 
+/**
+ * Material 3 full screen dialog shell. It covers the viewport and lays its
+ * content out like the scaffold does, with a main pane and a side sheet outlet
+ * on each side, so side sheets opened while it is up land inside the dialog
+ * instead of behind it.
+ */
+declare class FullScreenDialog extends CdkDialogContainer implements DialogContainer, AfterViewInit {
+    private readonly surface;
+    private readonly startOutlet;
+    private readonly endOutlet;
+    private readonly sheets;
+    isActive: _angular_core.WritableSignal<boolean>;
+    protected readonly config: DialogConfig<unknown>;
+    get surfaceElement(): HTMLElement | null;
+    ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    startEnterAnimation(): void;
+    setActive(value: boolean): void;
+    recaptureFocus(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FullScreenDialog, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FullScreenDialog, "md3-fullscreen-dialog", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Header of a full screen dialog: a leading icon button to leave the dialog,
+ * the headline, and a trailing action. It sticks to the top of the dialog while
+ * the content scrolls underneath.
+ */
+declare class FullScreenDialogHeader implements ButtonContext {
+    title: _angular_core.InputSignal<string>;
+    buttonContextSize: Signal<ButtonSize>;
+    buttonContextWidth: Signal<IconButtonWidth>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FullScreenDialogHeader, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FullScreenDialogHeader, "md3-fullscreen-dialog-header", never, { "title": { "alias": "title"; "required": false; "isSignal": true; }; }, {}, never, ["[md3-icon-button][md3-header-leading]", "[md3-header-trailing]"], true, never>;
+}
+
 declare class Menu implements AfterContentInit {
     private el;
     private readonly portalOutlet;
@@ -1163,11 +1323,19 @@ declare class SideSheetRef<T = unknown, R = unknown> {
 
 declare class SheetsService {
     private readonly injector;
+    /**
+     * Outlets registered per side, from the page scaffold up to whatever took
+     * them over last. Sheets always open in the outlet on top, so a full screen
+     * dialog can host them while it is up and hand them back when it closes.
+     */
     private readonly states;
     registerSideSheetOutlet(side: SideSheetSide, outlet: CdkPortalOutlet): void;
     unregisterSideSheetOutlet(side: SideSheetSide, outlet: CdkPortalOutlet): void;
     openSideSheet<T = unknown, D = unknown, R = unknown>(component: Type<T>, config?: SideSheetConfig<D>): SideSheetRef<T, R>;
     closeSideSheet<R = unknown>(side?: SideSheetSide, result?: R): void;
+    /** Outlet that sheets currently open in: the last one that registered. */
+    private activeState;
+    private getOutletStack;
     private mergeConfig;
     private createInjector;
     private bindDataToInputs;
@@ -1294,5 +1462,5 @@ declare class SnackbarService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<SnackbarService>;
 }
 
-export { AppBar, AppBarLogo, Avatar, Badge, Button, ButtonGroup, Card, Checkbox, ChipAvatar, Chips, CircularProgressIndicator, DIALOG_COMPONENT, DIALOG_CONFIG, DIALOG_DATA, Dialog, DialogActions, DialogBody, DialogHeader, DialogRef, DialogService, Divider, FloatingActionButton, Grid, GridItem, IconButton, IconElement, InputElement, LayoutService, LinearProgressIndicator, List, ListItem, ListItemPrimaryAction, ListLeading, ListSlot, LoadingIndicator, MENU_COMPONENT, MENU_CONFIG, MENU_DATA, MaterialIcon, Menu, MenuGroup, MenuItem, MenuRef, MenuService, NavigationBar, NavigationGroup, NavigationItem, NavigationRail, RadioButton, SIDE_SHEET_COMPONENT, SIDE_SHEET_CONFIG, SIDE_SHEET_DATA, SNACKBAR_ACTION_LABEL, SNACKBAR_CONFIG, SNACKBAR_MESSAGE, Scaffold, ScaffoldBar, ScaffoldPane, ScaffoldRail, SheetsService, SideSheetActions, SideSheetBody, SideSheetHeader, SideSheetRef, Slider, Snackbar, SnackbarRef, SnackbarService, SplitButton, StateComponent, SupportingText, Switch, TextField, TypeBody, TypeDisplay, TypeHeadline, TypeLabel, TypeTitle };
-export type { AppBarScrollingStyle, AppBarType, ButtonGroupSelection, ButtonGroupType, ButtonSize, ButtonType, CardType, ChipStyle, ChipType, DialogConfig, DialogRole, FabSize, FabType, IconButtonType, IconButtonWidth, ListLeadingSize, ListLeadingType, Md3NavigationMode, MenuConfig, MenuPositionOrigin, MenuPositionX, MenuPositionY, MenuScrollStrategy, SideSheetConfig, SideSheetContainer, SideSheetSide, SideSheetType, SliderSize, SnackbarConfig, SnackbarDismiss, SnackbarDismissReason, SnackbarPoliteness, SplitButtonType, TextColor, TextSize };
+export { AppBar, AppBarLogo, Avatar, Badge, Button, ButtonGroup, Card, Checkbox, ChipAvatar, Chips, CircularProgressIndicator, DIALOG_COMPONENT, DIALOG_CONFIG, DIALOG_DATA, Dialog, DialogActions, DialogBody, DialogHeader, DialogRef, DialogService, Divider, FloatingActionButton, FullScreenDialog, FullScreenDialogHeader, Grid, GridItem, IconButton, IconElement, InputElement, LayoutService, LinearProgressIndicator, List, ListItem, ListItemPrimaryAction, ListLeading, ListSlot, LoadingIndicator, MENU_COMPONENT, MENU_CONFIG, MENU_DATA, MaterialIcon, Menu, MenuGroup, MenuItem, MenuRef, MenuService, NavigationBar, NavigationGroup, NavigationItem, NavigationRail, RadioButton, SIDE_SHEET_COMPONENT, SIDE_SHEET_CONFIG, SIDE_SHEET_DATA, SNACKBAR_ACTION_LABEL, SNACKBAR_CONFIG, SNACKBAR_MESSAGE, Scaffold, ScaffoldBar, ScaffoldPane, ScaffoldRail, SheetsService, SideSheetActions, SideSheetBody, SideSheetHeader, SideSheetRef, Slider, Snackbar, SnackbarRef, SnackbarService, SplitButton, StateComponent, SupportingText, Switch, TextField, TypeBody, TypeDisplay, TypeHeadline, TypeLabel, TypeTitle };
+export type { AppBarScrollingStyle, AppBarType, ButtonGroupSelection, ButtonGroupType, ButtonSize, ButtonType, CardType, ChipStyle, ChipType, DialogConfig, DialogContainer, DialogRole, FabSize, FabType, FullScreenDialogConfig, IconButtonType, IconButtonWidth, ListLeadingSize, ListLeadingType, Md3NavigationMode, MenuConfig, MenuPositionOrigin, MenuPositionX, MenuPositionY, MenuScrollStrategy, PreviousDialog, SideSheetConfig, SideSheetContainer, SideSheetSide, SideSheetType, SliderSize, SnackbarConfig, SnackbarDismiss, SnackbarDismissReason, SnackbarPoliteness, SplitButtonType, TextColor, TextSize };