@almoamendev/ngx-md3 0.3.8 → 0.5.0

package/package.json

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

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

@@ -1,11 +1,11 @@
 import * as _angular_core from '@angular/core';
-import { ViewContainerRef, Injector, ElementRef, AfterViewInit, OnDestroy, OnInit, Renderer2, Signal, InputSignal, InjectionToken, Type, AfterContentInit, ComponentRef, TemplateRef } from '@angular/core';
+import { ViewContainerRef, Injector, Signal, ElementRef, AfterViewInit, OnDestroy, OnInit, Renderer2, InputSignal, InjectionToken, Type, AfterContentInit, ComponentRef, TemplateRef } from '@angular/core';
 import { FlexibleConnectedPositionStrategyOrigin, ConnectedPosition, OverlayRef } from '@angular/cdk/overlay';
+import { Observable, Subject } from 'rxjs';
 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';
 
 type TextSize = 'large' | 'medium' | 'small';
@@ -226,6 +226,80 @@ interface SideSheetContainer {
     setHidden(value: boolean): void;
 }
 
+/**
+ * How the sheet sits in the layout. A modal sheet floats above the page in an overlay with a
+ * scrim; a standard sheet docks into the scaffold, reserves its collapsed height and leaves the
+ * rest of the page usable.
+ */
+type BottomSheetType = 'standard' | 'modal';
+/** Which of a standard sheet's two heights it is resting at. */
+type BottomSheetState = 'collapsed' | 'expanded';
+interface BottomSheetConfig<D = unknown> {
+    data?: D;
+    bindDataToInputs?: boolean;
+    /** @default 'modal' */
+    type?: BottomSheetType;
+    /** Shows the MD3 drag handle centered above the sheet's content. */
+    handle?: boolean;
+    /**
+     * Lets the sheet be dragged, and flung. A modal sheet is dragged down to dismiss it; a
+     * standard sheet is dragged between its collapsed and expanded heights.
+     */
+    gestures?: boolean;
+    /** Standard only. How much of the sheet shows when it is collapsed. */
+    collapsedHeight?: number | string;
+    /** Standard only. Height the sheet grows to when it is expanded. */
+    expandedHeight?: number | string;
+    /** Standard only. Which height the sheet opens at. */
+    initialState?: BottomSheetState;
+    /** Standard only. Whether dragging below the collapsed height closes the sheet. */
+    dismissible?: boolean;
+    /** Standard only. Accessible name for the region the sheet occupies. */
+    label?: string;
+    /** Standard only. Id of the element naming the sheet, when it already has a visible title. */
+    labelledBy?: string;
+    scheme?: 'inherit' | 'dark' | 'light';
+    direction?: null | 'ltr' | 'rtl';
+    viewContainerRef?: ViewContainerRef;
+    injector?: Injector;
+}
+/**
+ * What BottomSheetRef needs from the surface hosting a sheet, whichever shell it was created
+ * in. The surface reports gestures rather than acting on them, because it is created before
+ * the reference exists and cannot reach it through DI.
+ */
+interface BottomSheetSurfaceHost {
+    readonly surfaceElement: HTMLElement | null;
+    /** Emits when a drag gesture asks for the sheet to be dismissed. */
+    readonly dismissed: Observable<void>;
+    /** Emits how far a drag has taken the sheet towards being dismissed, from 0 to 1. */
+    readonly dragProgress: Observable<number>;
+    /** Emits the height a drag settled the sheet at. Standard sheets only. */
+    readonly stateChanges: Observable<BottomSheetState>;
+    startEnterAnimation(): void;
+    setActive(value: boolean): void;
+}
+/**
+ * The modal shell, which is a CDK dialog container underneath and so has focus handling the
+ * standard shell deliberately does without.
+ */
+interface BottomSheetContainer extends BottomSheetSurfaceHost {
+    recaptureFocus(): void;
+}
+/**
+ * The docked shell, which owns the two heights a standard sheet moves between. Typed as an
+ * interface so BottomSheetRef can drive the shell without importing the component it lives in.
+ */
+interface StandardBottomSheetHost extends BottomSheetSurfaceHost {
+    readonly state: Signal<BottomSheetState>;
+    expand(): void;
+    collapse(): void;
+    toggle(): void;
+    setCollapsedHeight(value: number | string): void;
+    setExpandedHeight(value: number | string): void;
+    setDismissible(value: boolean): void;
+}
+
 type SnackbarPoliteness = 'polite' | 'assertive';
 interface SnackbarConfig<D = unknown> {
     /**
@@ -548,8 +622,10 @@ declare class LayoutService {
 declare class Scaffold implements AfterViewInit, OnDestroy {
     private startOutlet;
     private endOutlet;
+    private bottomOutlet;
     private panesContainer;
     private sheets;
+    private bottomSheets;
     private layout;
     ngAfterViewInit(): void;
     ngOnDestroy(): void;
@@ -1842,6 +1918,140 @@ declare class SideSheetActions {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SideSheetActions, "md3-side-sheet-actions", never, { "showDivider": { "alias": "show-divider"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
+declare const BOTTOM_SHEET_DATA: InjectionToken<unknown>;
+declare const BOTTOM_SHEET_CONFIG: InjectionToken<BottomSheetConfig<unknown>>;
+declare const BOTTOM_SHEET_COMPONENT: InjectionToken<Type<unknown>>;
+/**
+ * What both kinds of bottom sheet have in common: closing once, animating out before the shell
+ * goes away, and reporting the result. The two shells differ in what they are hosted by — a CDK
+ * overlay or a scaffold outlet — so each subclass owns its own exit and teardown.
+ *
+ * This class stays the DI token, so a component written for one kind of sheet can be opened as
+ * the other without changing how it injects its reference.
+ */
+declare abstract class BottomSheetRef<T = unknown, R = unknown> {
+    protected readonly closed: Subject<R | undefined>;
+    protected closeStarted: boolean;
+    private closeSettled;
+    /** Surface hosting the sheet. Filled in by BottomSheetService once the shell is created. */
+    sheetInstance?: BottomSheetSurfaceHost;
+    /** Filled by BottomSheetService after the sheet component is attached. */
+    componentInstance?: T;
+    /** Whether the sheet started closing. */
+    get isClosing(): boolean;
+    /** Height the sheet is resting at. A modal sheet is only ever fully open. */
+    get state(): Signal<BottomSheetState>;
+    /** Closes the sheet. The promise resolves once the exit animation is done. */
+    close(result?: R): Promise<void>;
+    afterClosed(): Observable<R | undefined>;
+    /**
+     * Wires the shell to this reference. Called by BottomSheetService, since the shell is
+     * created before this reference exists and cannot reach it through DI.
+     */
+    attachContainer(container: BottomSheetSurfaceHost): void;
+    /** Moves a standard sheet to its expanded height. Modal sheets have only one height. */
+    expand(): void;
+    /** Moves a standard sheet back to its collapsed height. */
+    collapse(): void;
+    /** Switches a standard sheet between its two heights. */
+    toggle(): void;
+    setCollapsedHeight(height: number | string): void;
+    setExpandedHeight(height: number | string): void;
+    setDismissible(value: boolean): void;
+    protected abstract startCloseAnimation(): Promise<void>;
+    protected abstract finishClose(result?: R): void;
+    /** Resolves when the surface finished animating, with a timeout as a safety net. */
+    protected waitForSurfaceAnimation(fallback?: HTMLElement | null): Promise<void>;
+    /** Emits the result once the sheet is gone. */
+    protected settle(result?: R): void;
+}
+/**
+ * A modal bottom sheet is a single overlay, not a stack like dialogs can be, so this is a
+ * smaller version of DialogRef: no hide/show, no full screen variant, closing is always the
+ * only way out.
+ */
+declare class ModalBottomSheetRef<T = unknown, R = unknown> extends BottomSheetRef<T, R> {
+    private readonly cdkRef;
+    constructor(cdkRef: DialogRef$1<R, T>);
+    /** Overlay hosting the sheet, useful to reach the panel and the scrim. */
+    get overlayRef(): OverlayRef;
+    attachContainer(container: BottomSheetSurfaceHost): void;
+    protected startCloseAnimation(): Promise<void>;
+    protected finishClose(result?: R): void;
+    private connectCloseEvents;
+    /** Fades the scrim along with the sheet being dragged, and hands it back to CSS on release. */
+    private trackDragProgress;
+}
+/**
+ * A standard bottom sheet lives in a scaffold outlet rather than an overlay, so there is no
+ * scrim to fade and nothing to dispose but the component itself. In exchange it can be moved
+ * between its two heights while it is open.
+ */
+declare class StandardBottomSheetRef<T = unknown, R = unknown> extends BottomSheetRef<T, R> {
+    private readonly onClosed;
+    private sheetComponentRef?;
+    private host?;
+    constructor(onClosed: () => void);
+    get state(): Signal<BottomSheetState>;
+    /** Called by BottomSheetService once the shell has been created in the outlet. */
+    attachSheet(componentRef: ComponentRef<unknown>, host: StandardBottomSheetHost): void;
+    expand(): void;
+    collapse(): void;
+    toggle(): void;
+    setCollapsedHeight(height: number | string): void;
+    setExpandedHeight(height: number | string): void;
+    setDismissible(value: boolean): void;
+    /**
+     * Tears the sheet down without an exit animation, for when the outlet holding it is going
+     * away and there is nothing left to animate in.
+     */
+    dispose(result?: R): void;
+    protected startCloseAnimation(): Promise<void>;
+    protected finishClose(result?: R): void;
+}
+
+/**
+ * Opens bottom sheets, in either of the two ways MD3 describes them.
+ *
+ * A modal sheet is a CDK dialog anchored to the bottom of the viewport, the same way a regular
+ * dialog is always an overlay, so that path mirrors DialogService. A standard sheet is docked
+ * into the scaffold instead, following the side sheet outlet model: it floats over the content
+ * without a scrim, leaves the rest of the page usable, and needs an outlet to open into.
+ *
+ * One of each may be open at a time, and they replace only their own kind.
+ */
+declare class BottomSheetService {
+    private readonly cdkDialog;
+    private readonly overlay;
+    private readonly injector;
+    /**
+     * Outlets registered from the page scaffold up to whatever took them over last. Standard
+     * sheets always open in the outlet on top.
+     */
+    private readonly outlets;
+    private modalRef?;
+    private standardRef?;
+    /** Registers the outlet standard bottom sheets open into. Called by Scaffold. */
+    registerBottomSheetOutlet(outlet: CdkPortalOutlet): void;
+    unregisterBottomSheetOutlet(outlet: CdkPortalOutlet): void;
+    open<T, D = unknown, R = unknown>(component: Type<T>, config?: BottomSheetConfig<D>): BottomSheetRef<T, R>;
+    /**
+     * Closes the bottom sheet that is open. A modal sheet goes first when both kinds are up,
+     * since it is the one covering the page.
+     */
+    close<R = unknown>(result?: R): void;
+    private openModal;
+    private openStandard;
+    private activeOutlet;
+    private createInjector;
+    private startOpenAnimation;
+    private mergeConfig;
+    private bindDataToInputs;
+    private canBindDataToInputs;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<BottomSheetService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<BottomSheetService>;
+}
+
 declare class Snackbar implements OnInit, OnDestroy {
     private readonly el;
     private readonly snackbarRef;
@@ -1937,5 +2147,5 @@ declare class SnackbarService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<SnackbarService>;
 }
 
-export { AppBar, AppBarLogo, Avatar, Badge, Button, ButtonGroup, CAROUSEL_STRATEGIES, Card, Carousel, CarouselItem, 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, buildGeometry, clampIndex, indexForScrollOffset, multiBrowseStrategy, parseCarouselAspectRatio, resolveItemGeometry, resolveState, scrollOffsetForIndex, sizeBandFor };
-export type { AppBarScrollingStyle, AppBarType, ButtonGroupSelection, ButtonGroupType, ButtonSize, ButtonType, CardType, CarouselAlignment, CarouselArrangement, CarouselGeometry, CarouselItemGeometry, CarouselItemSize, CarouselKeyline, CarouselKeylineState, CarouselLayout, CarouselOrientation, CarouselStrategy, CarouselStrategyContext, 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 };
+export { AppBar, AppBarLogo, Avatar, BOTTOM_SHEET_COMPONENT, BOTTOM_SHEET_CONFIG, BOTTOM_SHEET_DATA, Badge, BottomSheetRef, BottomSheetService, Button, ButtonGroup, CAROUSEL_STRATEGIES, Card, Carousel, CarouselItem, 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, ModalBottomSheetRef, 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, StandardBottomSheetRef, StateComponent, SupportingText, Switch, TextField, TypeBody, TypeDisplay, TypeHeadline, TypeLabel, TypeTitle, buildGeometry, clampIndex, indexForScrollOffset, multiBrowseStrategy, parseCarouselAspectRatio, resolveItemGeometry, resolveState, scrollOffsetForIndex, sizeBandFor };
+export type { AppBarScrollingStyle, AppBarType, BottomSheetConfig, BottomSheetContainer, BottomSheetState, BottomSheetSurfaceHost, BottomSheetType, ButtonGroupSelection, ButtonGroupType, ButtonSize, ButtonType, CardType, CarouselAlignment, CarouselArrangement, CarouselGeometry, CarouselItemGeometry, CarouselItemSize, CarouselKeyline, CarouselKeylineState, CarouselLayout, CarouselOrientation, CarouselStrategy, CarouselStrategyContext, 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, StandardBottomSheetHost, TextColor, TextSize };