@almoamendev/ngx-md3 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almoamendev/ngx-md3",
-  "version": "0.4.0",
+  "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,7 +1,7 @@
 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 } from 'rxjs';
+import { Observable, Subject } from 'rxjs';
 import * as i1 from '@angular/cdk/scrolling';
 import { AbstractControl } from '@angular/forms';
 import * as i1$1 from '@angular/router';
@@ -226,33 +226,79 @@ 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 down, and flung, to dismiss it. */
+    /**
+     * 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 shell hosting a bottom sheet, mirroring
- * DialogContainer: a bottom sheet is a CDK dialog container underneath, not a
- * side-sheet-style outlet.
+ * 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 BottomSheetContainer {
+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> {
@@ -576,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;
@@ -1874,58 +1922,128 @@ declare const BOTTOM_SHEET_DATA: InjectionToken<unknown>;
 declare const BOTTOM_SHEET_CONFIG: InjectionToken<BottomSheetConfig<unknown>>;
 declare const BOTTOM_SHEET_COMPONENT: InjectionToken<Type<unknown>>;
 /**
- * A bottom sheet is a single modal 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.
+ * 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 class BottomSheetRef<T = unknown, R = unknown> {
-    private readonly cdkRef;
-    private readonly closed;
-    private closeStarted;
+declare abstract class BottomSheetRef<T = unknown, R = unknown> {
+    protected readonly closed: Subject<R | undefined>;
+    protected closeStarted: boolean;
     private closeSettled;
-    /** Shell hosting the sheet. Filled by BottomSheetService once it is created. */
-    sheetInstance?: BottomSheetContainer;
+    /** 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;
-    /** Overlay hosting the sheet, useful to reach the panel and the scrim. */
-    get overlayRef(): OverlayRef;
     /** Whether the sheet started closing. */
     get isClosing(): boolean;
-    constructor(cdkRef: DialogRef$1<R, T>);
+    /** 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 by the CDK before this reference exists and cannot reach it through DI.
+     * created before this reference exists and cannot reach it through DI.
      */
-    attachContainer(container: BottomSheetContainer): void;
+    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;
-    private connectCloseEvents;
-    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;
+}
+/**
+ * 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 as CDK dialogs anchored to the bottom of the viewport.
- * A bottom sheet is always a modal overlay, the same way a regular dialog is
- * always an overlay, so this mirrors DialogService rather than the side sheet
- * outlet model: there is no docked variant and nothing to register from the
- * scaffold.
+ * 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;
-    /** Only one bottom sheet is ever open at a time. */
-    private ref?;
+    /**
+     * 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, if there is one. */
+    /**
+     * 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;
@@ -2029,5 +2147,5 @@ declare class SnackbarService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<SnackbarService>;
 }
 
-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, 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, BottomSheetConfig, BottomSheetContainer, 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 };