@almoamendev/ngx-md3 0.6.0 → 0.7.1

package/package.json

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

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

@@ -624,18 +624,68 @@ type ViewportWidth = 'compact' | 'medium' | 'expanded' | 'large' | 'extra-large'
 
 type ViewportHeight = 'compact' | 'medium' | 'expanded';
 
+type Md3NavigationMode = 'none' | 'navigation-bar' | 'navigation-rail' | 'standard-drawer' | 'modal-drawer';
+/**
+ * The state of the window and of the document, for the whole application.
+ *
+ * This service is a singleton on purpose. A layout region can appear more than once — a page
+ * scaffold, and a contained layout inside a full screen dialog — and each one keeps its own
+ * scroll and inset state in its own {@link LayoutService}. The window size, the breakpoints,
+ * the reading direction and the color scheme belong to the document, so they live here and
+ * every layout reads the same values.
+ */
+declare class ViewportService {
+    private readonly document;
+    private readonly breakpointObserver;
+    private readonly widthQueries;
+    private readonly heightQueries;
+    readonly viewport: _angular_core.Signal<{
+        width: number;
+        height: number;
+    } | {
+        readonly width: number;
+        readonly height: number;
+    }>;
+    readonly widthClass: _angular_core.Signal<ViewportWidth>;
+    readonly heightClass: _angular_core.Signal<ViewportHeight>;
+    readonly direction: _angular_core.WritableSignal<"ltr" | "rtl">;
+    readonly isCompact: _angular_core.Signal<boolean>;
+    readonly isMedium: _angular_core.Signal<boolean>;
+    readonly isExpanded: _angular_core.Signal<boolean>;
+    readonly isLarge: _angular_core.Signal<boolean>;
+    readonly isExtraLarge: _angular_core.Signal<boolean>;
+    readonly isPortrait: _angular_core.Signal<boolean>;
+    readonly isLandscape: _angular_core.Signal<boolean>;
+    readonly preferredNavigationMode: _angular_core.Signal<"navigation-bar" | "navigation-rail" | "standard-drawer">;
+    darkMode: _angular_core.WritableSignal<boolean>;
+    constructor();
+    setDirection(direction: 'ltr' | 'rtl'): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ViewportService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ViewportService>;
+}
+
 type FloatingBarSide = 'blockStart' | 'blockEnd';
 interface FloatingInset {
     blockStart: number;
     blockEnd: number;
 }
-type Md3NavigationMode = 'none' | 'navigation-bar' | 'navigation-rail' | 'standard-drawer' | 'modal-drawer';
+
+/**
+ * The state of one layout container: what its main pane scrolls, and what its floating bars
+ * cover.
+ *
+ * The service is provided at the root, and the page scaffold uses that root instance. A
+ * contained layout — `md3-layout`, the one a full screen dialog holds — provides its own
+ * instance instead, so a toolbar inside it reads the scroll and the insets of that layout and
+ * never of the page behind it.
+ *
+ * The window size, the breakpoints, the reading direction and the color scheme belong to the
+ * document, not to a container. They live in {@link ViewportService}, and every instance of
+ * this service exposes the same signals, so an instance stays a complete view of the layout.
+ */
 declare class LayoutService {
-    private readonly document;
-    private readonly breakpointObserver;
+    private readonly viewportService;
     private readonly router;
-    private readonly widthQueries;
-    private readonly heightQueries;
     private mainPaneSub?;
     private mainPaneEl?;
     private panesContainerResizeObserver?;
@@ -654,18 +704,17 @@ declare class LayoutService {
      */
     readonly isScrollingDown: _angular_core.WritableSignal<boolean>;
     /**
-     * Distance, in pixels, between the viewport bottom and the bottom edge of
-     * the scaffold's .md3-panes-container — i.e. whatever the bottom scaffold
-     * bar (nav bar) currently reserves, or 0 when there is none. Overlay-based
-     * components anchored to the viewport bottom (like Snackbar) read this so
-     * they never render lower than the panes container.
+     * Distance, in pixels, between the bottom of the container and the bottom edge of
+     * the .md3-panes-container — i.e. whatever the bottom bar currently reserves, or 0 when
+     * there is none. Overlay-based components anchored to the bottom (like Snackbar) read
+     * this so they never render lower than the panes container.
      */
     readonly bottomInset: _angular_core.WritableSignal<number>;
     /**
-     * Space a floating scaffold bar covers but does not reserve, per logical block side.
+     * Space a floating bar covers but does not reserve, per logical block side.
      *
      * A floating toolbar in a bar region leaves the layout flow, so its grid track collapses
-     * and the content flows under it. This signal reports what it covers, so the scaffold can
+     * and the content flows under it. This signal reports what it covers, so the layout can
      * pad the main pane and overlays can stay clear of it.
      *
      * A floating toolbar in a *rail* region stays in the flow and reserves its own space, so
@@ -673,8 +722,8 @@ declare class LayoutService {
      */
     readonly floatingInset: _angular_core.WritableSignal<FloatingInset>;
     /**
-     * The distance from the viewport bottom that a viewport-anchored overlay must keep clear.
-     * It covers both the reserved bottom bar and any floating bottom bar over it.
+     * The distance from the bottom that an anchored overlay must keep clear. It covers both
+     * the reserved bottom bar and any floating bottom bar over it.
      */
     readonly bottomSafeInset: _angular_core.Signal<number>;
     readonly viewport: _angular_core.Signal<{
@@ -705,10 +754,10 @@ declare class LayoutService {
     private updateScrollDirection;
     registerPanesContainer(element: HTMLElement): void;
     /**
-     * Register a floating bar so the scaffold and the overlays know what it covers.
+     * Register a floating bar so the layout and the overlays know what it covers.
      *
-     * Call this for a floating toolbar in a scaffold *bar* region only. A rail region keeps
-     * the toolbar in the layout flow, so it reserves its own space and needs no inset.
+     * Call this for a floating toolbar in a *bar* region only. A rail region keeps the toolbar
+     * in the layout flow, so it reserves its space and needs no inset.
      */
     registerFloatingBar(element: HTMLElement, side: FloatingBarSide): void;
     unregisterFloatingBar(element: HTMLElement): void;
@@ -740,6 +789,35 @@ declare class Scaffold implements AfterViewInit, OnDestroy {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<Scaffold, "md3-scaffold", never, {}, {}, never, ["[md3-scaffold-bar=top]", "[md3-scaffold-rail=leading]", "[md3-scaffold-pane=start]", "[md3-scaffold-pane=main]", "[md3-scaffold-pane=end]", "[md3-scaffold-rail=trailing]", "[md3-scaffold-bar=bottom]"], true, never>;
 }
 
+/**
+ * A layout region shell that fills its parent instead of the window.
+ *
+ * It places the same regions as `md3-scaffold` — the bar rows, the rail columns and the three
+ * panes — so the same region attributes work inside it:
+ *
+ * ```html
+ * <md3-layout>
+ *     <md3-toolbar md3-scaffold-bar="bottom" toolbar-type="floating">...</md3-toolbar>
+ *
+ *     <div md3-scaffold-pane="main">...</div>
+ * </md3-layout>
+ * ```
+ *
+ * Use it wherever a page-sized scaffold does not fit: the content of a full screen dialog, a
+ * card, a preview pane. A full screen dialog is the common one, because a toolbar needs a bar
+ * or a rail region and the dialog shell has none of its own.
+ *
+ * The layout provides its own {@link LayoutService}, so everything inside it reads the scroll
+ * position and the floating insets of *this* container. A floating toolbar therefore pads the
+ * main pane of the layout, and `scroll-action` follows the pane of the layout — never the page
+ * behind it. The window size, the breakpoints, the reading direction and the color scheme stay
+ * shared with the rest of the application.
+ */
+declare class Layout extends Scaffold {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<Layout, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Layout, "md3-layout", never, {}, {}, never, ["[md3-scaffold-bar=top]", "[md3-scaffold-rail=leading]", "[md3-scaffold-pane=start]", "[md3-scaffold-pane=main]", "[md3-scaffold-pane=end]", "[md3-scaffold-rail=trailing]", "[md3-scaffold-bar=bottom]"], true, never>;
+}
+
 declare class ScaffoldBar {
     region: _angular_core.InputSignal<"top" | "bottom">;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ScaffoldBar, never>;
@@ -1450,6 +1528,16 @@ type AppBarScrollingStyle = 'none' | 'transparent' | 'elevate';
 declare class AppBar implements ButtonContext {
     private el;
     private layoutService;
+    private readonly inDialog;
+    /**
+     * The landmark role of the bar.
+     *
+     * A page has one banner, and the app bar of the page is it. A bar inside a dialog is not
+     * the banner of the document — a banner nested in a dialog misleads a screen reader — so a
+     * bar that finds itself in one carries no role. Set this input to force either value.
+     */
+    barRole: _angular_core.InputSignal<"none" | "banner" | null>;
+    protected readonly resolvedRole: Signal<string | null>;
     title: _angular_core.InputSignal<string | null>;
     subtitle: _angular_core.InputSignal<string | null>;
     appBarType: _angular_core.InputSignal<AppBarType>;
@@ -1472,7 +1560,7 @@ declare class AppBar implements ButtonContext {
     private hasCollapsibleBottom;
     private getHostFontSize;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<AppBar, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AppBar, "md3-app-bar", never, { "title": { "alias": "bar-title"; "required": false; "isSignal": true; }; "subtitle": { "alias": "bar-subtitle"; "required": false; "isSignal": true; }; "appBarType": { "alias": "bar-type"; "required": false; "isSignal": true; }; "appBarScrollingStyle": { "alias": "scroll-style"; "required": false; "isSignal": true; }; "autoHide": { "alias": "auto-hide"; "required": false; "isSignal": true; }; "centerAligned": { "alias": "center-aligned"; "required": false; "isSignal": true; }; }, {}, ["logo", "avatar"], ["[md3-app-bar-leading]", "[md3-search-leading]", "[md3-input-element]", "[md3-search-trailing]", "[md3-app-bar-logo]", "[md3-app-bar-trailing]", "[md3-avatar]"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AppBar, "md3-app-bar", never, { "barRole": { "alias": "bar-role"; "required": false; "isSignal": true; }; "title": { "alias": "bar-title"; "required": false; "isSignal": true; }; "subtitle": { "alias": "bar-subtitle"; "required": false; "isSignal": true; }; "appBarType": { "alias": "bar-type"; "required": false; "isSignal": true; }; "appBarScrollingStyle": { "alias": "scroll-style"; "required": false; "isSignal": true; }; "autoHide": { "alias": "auto-hide"; "required": false; "isSignal": true; }; "centerAligned": { "alias": "center-aligned"; "required": false; "isSignal": true; }; }, {}, ["logo", "avatar"], ["[md3-app-bar-leading]", "[md3-search-leading]", "[md3-input-element]", "[md3-search-trailing]", "[md3-app-bar-logo]", "[md3-app-bar-trailing]", "[md3-avatar]"], true, never>;
 }
 
 declare class AppBarLogo {
@@ -1898,21 +1986,35 @@ declare class DialogActions {
 }
 
 /**
- * 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.
+ * Material 3 full screen dialog shell. It covers the viewport and holds the content.
+ *
+ * The content is an `md3-layout`. The layout places the regions — the bar rows for an app bar
+ * or a toolbar, the rail columns, and the panes where side sheets open — so the dialog itself
+ * places nothing but the content. A content root that is not a layout gets a warning in
+ * development mode, and the shell falls back to panes of its own, so a side sheet never opens
+ * behind the dialog where nobody can see it.
  */
 declare class FullScreenDialog extends CdkDialogContainer implements DialogContainer, AfterViewInit {
     private readonly surface;
+    private readonly mainPane;
     private readonly startOutlet;
     private readonly endOutlet;
     private readonly sheets;
+    /** True while the shell holds the side sheet outlets, which happens without a layout only. */
+    private ownsSideSheetOutlets;
     isActive: _angular_core.WritableSignal<boolean>;
     protected readonly config: DialogConfig<unknown>;
     get surfaceElement(): HTMLElement | null;
     ngAfterViewInit(): void;
     ngOnDestroy(): void;
+    /**
+     * The layout at the root of the content, if the content brought one.
+     *
+     * The root is either the layout itself, or the component that holds it — a dialog is
+     * normally opened with a component whose own template starts with `md3-layout`.
+     */
+    private findContentLayout;
+    private checkContentLayout;
     startEnterAnimation(): void;
     setActive(value: boolean): void;
     recaptureFocus(): void;
@@ -1920,18 +2022,6 @@ declare class FullScreenDialog extends CdkDialogContainer implements DialogConta
     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 {
-    buttonContextSize: Signal<ButtonSize>;
-    buttonContextWidth: Signal<IconButtonWidth>;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FullScreenDialogHeader, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FullScreenDialogHeader, "md3-fullscreen-dialog-header", never, {}, {}, never, ["[md3-icon-button][md3-header-leading]", "*", "[md3-header-trailing]"], true, never>;
-}
-
 declare class Menu implements AfterContentInit {
     private el;
     private readonly portalOutlet;
@@ -2366,5 +2456,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, 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, Toolbar, ToolbarItem, TypeBody, TypeDisplay, TypeHeadline, TypeLabel, TypeTitle, buildGeometry, clampIndex, indexForScrollOffset, multiBrowseStrategy, parseCarouselAspectRatio, resolveItemGeometry, resolveState, scrollOffsetForIndex, sizeBandFor };
+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, Grid, GridItem, IconButton, IconElement, InputElement, Layout, 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, Toolbar, ToolbarItem, TypeBody, TypeDisplay, TypeHeadline, TypeLabel, TypeTitle, ViewportService, 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, FloatingBarSide, FloatingInset, 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, ToolbarAlignment, ToolbarColor, ToolbarOrientation, ToolbarRegion, ToolbarScrollAction, ToolbarType };