@almoamendev/ngx-md3 0.5.4 → 0.6.0

package/package.json

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

package/src/lib/styles/md3.scss

@@ -510,6 +510,14 @@ md3-badge {
         height: 100%;
         overflow-x: hidden;
         overflow-y: auto;
+
+        // A floating toolbar in a scaffold bar covers content that it does not reserve. The
+        // scaffold publishes how much, and the fallback is 0, so a layout without one is
+        // unchanged. Set these to 0 on a page that needs full-bleed content.
+        padding-block-start: var(--md-scaffold-floating-inset-block-start, 0em);
+        padding-block-end: var(--md-scaffold-floating-inset-block-end, 0em);
+        scroll-padding-block-start: var(--md-scaffold-floating-inset-block-start, 0em);
+        scroll-padding-block-end: var(--md-scaffold-floating-inset-block-end, 0em);
     }
 }
 

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

@@ -53,6 +53,62 @@ type ListLeadingSize = 'image' | 'small-video' | 'large-video';
  */
 type CarouselLayout = 'multi-browse';
 
+/**
+ * The toolbar container style.
+ *
+ * `floating` draws a rounded, elevated container with an outside margin. In a scaffold bar
+ * region it leaves the layout flow, so the content passes behind it. In a scaffold rail
+ * region it stays in the flow and reserves its own space.
+ *
+ * `docked` fills its region, has square corners and no elevation. The Material 3
+ * specification allows it in a bar region only, because it spans the full window width.
+ */
+type ToolbarType = 'floating' | 'docked';
+
+/**
+ * The toolbar color configuration.
+ *
+ * `standard` uses a surface container. `vibrant` uses a primary container, and remaps the
+ * colors of the buttons inside it, as the Material 3 specification describes.
+ */
+type ToolbarColor = 'standard' | 'vibrant';
+
+/**
+ * The axis the toolbar items follow.
+ *
+ * The value is optional on the component. When it is not set, a toolbar in a scaffold rail
+ * region becomes `vertical`, and every other toolbar becomes `horizontal`.
+ */
+type ToolbarOrientation = 'horizontal' | 'vertical';
+
+/**
+ * Where the toolbar sits along its main axis.
+ *
+ * A docked toolbar fills its region, so the value moves the item row inside the container. A
+ * floating toolbar is as wide as its content, so the value moves the container itself, and the
+ * FAB with it, inside the region.
+ */
+type ToolbarAlignment = 'start' | 'center' | 'end';
+
+/**
+ * What the toolbar does when the scaffold main pane scrolls down.
+ *
+ * `none` does nothing. `hide` moves the toolbar out of the region. `collapse` hides every
+ * item that does not carry the `md3-toolbar-persistent` attribute, and keeps the FAB.
+ *
+ * A vertical toolbar ignores this input.
+ */
+type ToolbarScrollAction = 'none' | 'hide' | 'collapse';
+
+/**
+ * The scaffold region a toolbar sits in, named by its logical side.
+ *
+ * `blockStart` and `blockEnd` are the top and bottom scaffold bars. `inlineStart` and
+ * `inlineEnd` are the leading and trailing scaffold rails. The names are logical, so they
+ * follow the document direction.
+ */
+type ToolbarRegion = 'blockStart' | 'blockEnd' | 'inlineStart' | 'inlineEnd';
+
 /**
  * Where the focal (large) items sit within the carousel container.
  */
@@ -568,6 +624,11 @@ type ViewportWidth = 'compact' | 'medium' | 'expanded' | 'large' | 'extra-large'
 
 type ViewportHeight = 'compact' | 'medium' | 'expanded';
 
+type FloatingBarSide = 'blockStart' | 'blockEnd';
+interface FloatingInset {
+    blockStart: number;
+    blockEnd: number;
+}
 type Md3NavigationMode = 'none' | 'navigation-bar' | 'navigation-rail' | 'standard-drawer' | 'modal-drawer';
 declare class LayoutService {
     private readonly document;
@@ -579,8 +640,19 @@ declare class LayoutService {
     private mainPaneEl?;
     private panesContainerResizeObserver?;
     private panesContainerResizeListener?;
+    /** Floating bars currently registered, keyed by the measured element. */
+    private readonly floatingBars;
+    /** How far the main pane must move before the scroll direction flips. Stops jitter. */
+    private static readonly scrollDirectionThreshold;
+    private scrollPosition;
     readonly mainScrollTop: _angular_core.WritableSignal<number>;
     readonly mainIsScrolled: _angular_core.Signal<boolean>;
+    /**
+     * True while the main pane moves down, false while it moves up. A small threshold keeps
+     * a jitter from flipping the value. Components that react to scrolling — the app bar and
+     * the toolbar — read this, so they can never disagree.
+     */
+    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
@@ -589,6 +661,22 @@ declare class LayoutService {
      * 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.
+     *
+     * 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
+     * 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
+     * it never appears here.
+     */
+    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.
+     */
+    readonly bottomSafeInset: _angular_core.Signal<number>;
     readonly viewport: _angular_core.Signal<{
         width: number;
         height: number;
@@ -613,7 +701,24 @@ declare class LayoutService {
     private scrollMainPaneToTop;
     registerMainPane(element: HTMLElement): void;
     unregisterMainPane(element: HTMLElement): void;
+    private resetScrollDirection;
+    private updateScrollDirection;
     registerPanesContainer(element: HTMLElement): void;
+    /**
+     * Register a floating bar so the scaffold 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.
+     */
+    registerFloatingBar(element: HTMLElement, side: FloatingBarSide): void;
+    unregisterFloatingBar(element: HTMLElement): void;
+    private measureFloatingBars;
+    /**
+     * `offsetHeight` ignores transforms. So a toolbar that scrolling has hidden or collapsed
+     * still reports its expanded size, and the content padding never moves while the user
+     * scrolls.
+     */
+    private measureBlockSize;
     unregisterPanesContainer(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<LayoutService, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<LayoutService>;
@@ -627,6 +732,8 @@ declare class Scaffold implements AfterViewInit, OnDestroy {
     private sheets;
     private bottomSheets;
     private layout;
+    private el;
+    constructor();
     ngAfterViewInit(): void;
     ngOnDestroy(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Scaffold, never>;
@@ -1354,8 +1461,7 @@ declare class AppBar implements ButtonContext {
     hasLogo: Signal<boolean>;
     hasAvatar: Signal<boolean>;
     mainIsScrolled: Signal<boolean>;
-    isScrollingDown: _angular_core.WritableSignal<boolean>;
-    private scrollPosition;
+    isScrollingDown: Signal<boolean>;
     private bottomExpandedHeight;
     private bottomCollapse;
     buttonContextSize: Signal<ButtonSize>;
@@ -1363,7 +1469,6 @@ declare class AppBar implements ButtonContext {
     get element(): HTMLElement;
     private getBottomOpacity;
     private isBottomCollapsed;
-    private updateScrollDirection;
     private hasCollapsibleBottom;
     private getHostFontSize;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<AppBar, never>;
@@ -1375,6 +1480,119 @@ declare class AppBarLogo {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<AppBarLogo, "[md3-app-bar-logo]", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Material 3 toolbar.
+ *
+ * The toolbar holds the actions of the current page. Put it in a scaffold region, and the
+ * region decides where it goes:
+ *
+ * ```html
+ * <md3-toolbar md3-scaffold-bar="bottom" toolbar-type="floating" scroll-action="collapse">
+ *     <md3-toolbar-item><button md3-icon-button>...</button></md3-toolbar-item>
+ *     <md3-toolbar-item md3-toolbar-persistent><button md3-icon-button>...</button></md3-toolbar-item>
+ *     <button md3-fab>...</button>
+ * </md3-toolbar>
+ * ```
+ *
+ * Every action goes inside an `md3-toolbar-item`. The toolbar projects that element only. A FAB is
+ * the one exception: it sits beside the container, and a floating toolbar takes it.
+ *
+ * A **floating** toolbar in a *bar* region leaves the layout flow, so the content passes
+ * behind it. The scaffold pads the main pane by the height it covers. In a *rail* region it
+ * stays in the flow and reserves its own space, so no padding is necessary.
+ *
+ * A **docked** toolbar fills its region. The specification allows it in a bar region only.
+ *
+ * Group actions with `md3-button-group`. The toolbar has one slots region, and it keeps the
+ * authored order. The space between the items follows the free space of the container, between
+ * `--md-toolbar-gap-min` and `--md-toolbar-gap-max`.
+ */
+declare class Toolbar implements ButtonContext, OnDestroy {
+    private readonly el;
+    private readonly layout;
+    private readonly scaffoldBar;
+    private readonly scaffoldRail;
+    toolbarType: _angular_core.InputSignal<ToolbarType>;
+    toolbarColor: _angular_core.InputSignal<ToolbarColor>;
+    /**
+     * Leave this unset to follow the region. A rail region gives `vertical`, and every other
+     * placement gives `horizontal`. Read `effectiveOrientation` for the resolved value.
+     */
+    orientation: _angular_core.InputSignal<ToolbarOrientation | null>;
+    alignment: _angular_core.InputSignal<ToolbarAlignment>;
+    scrollAction: _angular_core.InputSignal<ToolbarScrollAction>;
+    fabPosition: _angular_core.InputSignal<"start" | "end">;
+    /** The collapse state. Scrolling writes to it, and you can read or set it yourself. */
+    expanded: _angular_core.ModelSignal<boolean>;
+    private readonly layoutElement;
+    private readonly containerElement;
+    private readonly slotsElement;
+    private readonly fab;
+    /** Set from the DOM, because `md3-toolbar-persistent` is a plain attribute, not a directive. */
+    private readonly hasPersistentItem;
+    private readonly hasFocusWithin;
+    private persistentObserver?;
+    private readonly isBrowser;
+    /** The last published free space, to keep an unchanged measurement from writing to the DOM. */
+    private lastGap;
+    readonly isFloating: Signal<boolean>;
+    readonly effectiveOrientation: Signal<ToolbarOrientation>;
+    /** The logical side of the scaffold region, or null outside a scaffold. */
+    readonly region: Signal<ToolbarRegion | null>;
+    protected readonly isBarRegion: Signal<boolean>;
+    protected readonly isRailRegion: Signal<boolean>;
+    /** A floating toolbar inside a scaffold region needs the region to stop clipping it. */
+    protected readonly isFloatingRegion: Signal<boolean>;
+    /** Only a floating bar covers content it does not reserve. Everything else reserves its space. */
+    private readonly coversContent;
+    /** Something must survive a collapse, or a collapse is just a hide. */
+    private readonly canCollapse;
+    /** With a FAB and no marked item, a collapse takes the container away and the FAB stays alone. */
+    protected readonly collapsesToFab: Signal<boolean>;
+    /** A vertical toolbar never reacts to scrolling, and a docked one never collapses. */
+    readonly resolvedScrollAction: Signal<ToolbarScrollAction>;
+    readonly isHidden: _angular_core.WritableSignal<boolean>;
+    readonly isCollapsed: Signal<boolean>;
+    /**
+     * The collapsed state in which the FAB stays alone.
+     *
+     * This is the state, not the capability. A FAB by itself must never take the container
+     * away, because a toolbar that does not collapse keeps its items at all times.
+     */
+    protected readonly isCollapsedToFab: Signal<boolean>;
+    buttonContextSize: Signal<ButtonSize>;
+    constructor();
+    ngOnDestroy(): void;
+    get element(): HTMLElement;
+    protected onFocusIn(): void;
+    protected onFocusOut(event: FocusEvent): void;
+    private updateScrollState;
+    /**
+     * Divide the free space of the container between the gaps.
+     *
+     * The measurement starts from the host, because the host holds the space the region gives
+     * the toolbar. A floating container is only as wide as its content, so reading the container
+     * itself would feed the gap back into the measurement and the value would never settle.
+     */
+    private measureGap;
+    private publishGap;
+    private extent;
+    private contentExtent;
+    private paddingExtent;
+    /** What the other children of the layout take, the flex gap that separates them included. */
+    private siblingExtent;
+    private watchPersistentItems;
+    private checkConfiguration;
+    private warn;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<Toolbar, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Toolbar, "md3-toolbar", never, { "toolbarType": { "alias": "toolbar-type"; "required": false; "isSignal": true; }; "toolbarColor": { "alias": "toolbar-color"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "alignment": { "alias": "alignment"; "required": false; "isSignal": true; }; "scrollAction": { "alias": "scroll-action"; "required": false; "isSignal": true; }; "fabPosition": { "alias": "fab-position"; "required": false; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; }, { "expanded": "expandedChange"; }, ["fab"], ["[md3-fab]", "md3-toolbar-item"], true, never>;
+}
+
+declare class ToolbarItem {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ToolbarItem, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ToolbarItem, "md3-toolbar-item", never, {}, {}, never, never, true, never>;
+}
+
 declare class NavigationItem {
     private readonly el;
     private routerLinkActive;
@@ -2148,5 +2366,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, 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 };
+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 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 };