feat(dialog): Adding styling for scroll bar dividers, and adding logic to show said dividers only when content is scrolled "behind" the header or footer of the dialog.

BREAKING_CHANGE: This change adds four additional methods into the MDCDialogAdapter:

* registerContentEventHandler<K extends EventType>(
      evtType: K, handler: SpecificEventListener<K>): void;
* deregisterContentEventHandler<K extends EventType>(
      evtType: K, handler: SpecificEventListener<K>): void;
* isScrollableContentAtTop(): boolean;
* isScrollableContentAtBottom(): boolean;

Note that full-screen dialogs are currently under development and not yet ready for use.

PiperOrigin-RevId: 353767497

Author: sayris

packages/mdc-dialog/_mixins.scss

@@ -197,6 +197,18 @@
     .mdc-dialog__close {
       @include iconbutton-mixins.size($size: 24px, $query: $query);
     }
+
+    &.mdc-dialog--scrollable .mdc-dialog__actions {
+      // If full-screen dialog is scrollable, the scroll divider over the action
+      // buttons (i.e. the "footer") should only be visible when the content is
+      // "cut off" by the footer. To toggle this divider, we override the
+      // styling set by the mdc-dialog--scrollable class, and instead rely on
+      // the mdc-dialog-scroll-divider-footer class to determine when the
+      // border-top should be visible.
+      @include feature-targeting.targets($feat-structure) {
+        border-top: 1px solid transparent;
+      }
+    }
   }
 
   .mdc-dialog__content {
@@ -454,11 +466,18 @@
   $feat-color: feature-targeting.create-target($query, color);
 
   &.mdc-dialog--scrollable .mdc-dialog__title,
-  &.mdc-dialog--scrollable .mdc-dialog__actions {
+  &.mdc-dialog--scrollable .mdc-dialog__actions,
+  &.mdc-dialog--scrollable.mdc-dialog-scroll-divider-footer
+    .mdc-dialog__actions {
     @include feature-targeting.targets($feat-color) {
       border-color: rgba(theme-color.prop-value($color), $opacity);
     }
   }
+
+  &.mdc-dialog-scroll-divider-header.mdc-dialog--fullscreen
+    .mdc-dialog__header {
+    @include elevation-mixins.elevation(2, $query: $query);
+  }
 }
 
 @mixin shape-radius(

packages/mdc-dialog/adapter.ts

@@ -21,6 +21,8 @@
  * THE SOFTWARE.
  */
 
+import {EventType, SpecificEventListener} from '@material/base/types';
+
 /**
  * Defines the shape of the adapter expected by the foundation.
  * Implement this adapter for your framework of choice to delegate updates to
@@ -34,11 +36,11 @@ export interface MDCDialogAdapter {
   hasClass(className: string): boolean;
   addBodyClass(className: string): void;
   removeBodyClass(className: string): void;
-  eventTargetMatches(target: EventTarget | null, selector: string): boolean;
+  eventTargetMatches(target: EventTarget|null, selector: string): boolean;
 
   isContentScrollable(): boolean;
   areButtonsStacked(): boolean;
-  getActionFromEvent(evt: Event): string | null;
+  getActionFromEvent(evt: Event): string|null;
 
   trapFocus(focusElement: HTMLElement|null): void;
   releaseFocus(): void;
@@ -51,4 +53,33 @@ export interface MDCDialogAdapter {
   notifyOpened(): void;
   notifyClosing(action: string): void;
   notifyClosed(action: string): void;
+
+  /**
+   * Registers an event listener on the dialog's content element (indicated
+   * with the 'mdc-dialog__content' class).
+   */
+  registerContentEventHandler<K extends EventType>(
+      evtType: K, handler: SpecificEventListener<K>): void;
+
+  /**
+   * Deregisters an event listener on the dialog's content element.
+   */
+  deregisterContentEventHandler<K extends EventType>(
+      evtType: K, handler: SpecificEventListener<K>): void;
+
+  /**
+   * @return true if the content has been scrolled (that is, for
+   *     scrollable content, if it is at the "top"). This is used in full-screen
+   *     dialogs, where the scroll divider is expected only to appear once the
+   *     content has been scrolled "underneath" the header bar.
+   */
+  isScrollableContentAtTop(): boolean;
+
+  /**
+   * @return true if the content has been scrolled all
+   *     the way to the bottom. This is used in full-screen dialogs, where the
+   *     footer scroll divider is expected only to appear when the content is
+   *     "cut-off" by the footer bar.
+   */
+  isScrollableContentAtBottom(): boolean;
 }

packages/mdc-dialog/component.ts

@@ -210,6 +210,22 @@ export class MDCDialog extends MDCComponent<MDCDialogFoundation> {
       trapFocus: () => {
         this.focusTrap.trapFocus();
       },
+      registerContentEventHandler: (evt, handler) => {
+        if (this.content instanceof HTMLElement) {
+          this.content.addEventListener(evt, handler);
+        }
+      },
+      deregisterContentEventHandler: (evt, handler) => {
+        if (this.content instanceof HTMLElement) {
+          this.content.removeEventListener(evt, handler);
+        }
+      },
+      isScrollableContentAtTop: () => {
+        return util.isScrollAtTop(this.content);
+      },
+      isScrollableContentAtBottom: () => {
+        return util.isScrollAtBottom(this.content);
+      },
     };
     return new MDCDialogFoundation(adapter);
   }

packages/mdc-dialog/constants.ts

@@ -28,6 +28,15 @@ export const cssClasses = {
   SCROLLABLE: 'mdc-dialog--scrollable',
   SCROLL_LOCK: 'mdc-dialog-scroll-lock',
   STACKED: 'mdc-dialog--stacked',
+  FULLSCREEN: 'mdc-dialog--fullscreen',
+  // Class for showing a scroll divider on full-screen dialog header element.
+  // Should only be displayed on scrollable content, when the dialog content is
+  // scrolled "underneath" the header.
+  SCROLL_DIVIDER_HEADER: 'mdc-dialog-scroll-divider-header',
+  // Class for showing a scroll divider on a full-screen dialog footer element.
+  // Should only be displayed on scrolalble content, when the dialog content is
+  // obscured "underneath" the footer.
+  SCROLL_DIVIDER_FOOTER: 'mdc-dialog-scroll-divider-footer',
 };
 
 export const strings = {

packages/mdc-dialog/foundation.ts

@@ -21,10 +21,17 @@
  * THE SOFTWARE.
  */
 
+import {AnimationFrame} from '@material/animation/animationframe';
 import {MDCFoundation} from '@material/base/foundation';
+import {SpecificEventListener} from '@material/base/types';
+
 import {MDCDialogAdapter} from './adapter';
 import {cssClasses, numbers, strings} from './constants';
 
+enum AnimationKeys {
+  POLL_SCROLL_POS = 'poll_scroll_position'
+}
+
 export class MDCDialogFoundation extends MDCFoundation<MDCDialogAdapter> {
   static get cssClasses() {
     return cssClasses;
@@ -58,27 +65,41 @@ export class MDCDialogFoundation extends MDCFoundation<MDCDialogAdapter> {
       removeClass: () => undefined,
       reverseButtons: () => undefined,
       trapFocus: () => undefined,
+      registerContentEventHandler: () => undefined,
+      deregisterContentEventHandler: () => undefined,
+      isScrollableContentAtTop: () => false,
+      isScrollableContentAtBottom: () => false,
     };
   }
 
   private dialogOpen = false;
+  private isFullscreen = false;
   private animationFrame = 0;
   private animationTimer = 0;
   private layoutFrame = 0;
   private escapeKeyAction = strings.CLOSE_ACTION;
   private scrimClickAction = strings.CLOSE_ACTION;
   private autoStackButtons = true;
   private areButtonsStacked = false;
-  private suppressDefaultPressSelector = strings.SUPPRESS_DEFAULT_PRESS_SELECTOR;
+  private suppressDefaultPressSelector =
+      strings.SUPPRESS_DEFAULT_PRESS_SELECTOR;
+  private readonly contentScrollHandler: SpecificEventListener<'scroll'>;
+  private readonly animFrame: AnimationFrame;
 
   constructor(adapter?: Partial<MDCDialogAdapter>) {
     super({...MDCDialogFoundation.defaultAdapter, ...adapter});
+
+    this.animFrame = new AnimationFrame();
+    this.contentScrollHandler = () => {
+      this.handleScrollEvent();
+    };
   }
 
   init() {
     if (this.adapter.hasClass(cssClasses.STACKED)) {
       this.setAutoStackButtons(false);
     }
+    this.isFullscreen = this.adapter.hasClass(cssClasses.FULLSCREEN);
   }
 
   destroy() {
@@ -95,14 +116,24 @@ export class MDCDialogFoundation extends MDCFoundation<MDCDialogAdapter> {
       cancelAnimationFrame(this.layoutFrame);
       this.layoutFrame = 0;
     }
+
+    if (this.isFullscreen && this.adapter.isContentScrollable()) {
+      this.adapter.deregisterContentEventHandler(
+          'scroll', this.contentScrollHandler);
+    }
   }
 
   open() {
     this.dialogOpen = true;
     this.adapter.notifyOpening();
     this.adapter.addClass(cssClasses.OPENING);
+    if (this.isFullscreen && this.adapter.isContentScrollable()) {
+      this.adapter.registerContentEventHandler(
+          'scroll', this.contentScrollHandler);
+    }
 
-    // Wait a frame once display is no longer "none", to establish basis for animation
+    // Wait a frame once display is no longer "none", to establish basis for
+    // animation
     this.runNextAnimationFrame(() => {
       this.adapter.addClass(cssClasses.OPEN);
       this.adapter.addBodyClass(cssClasses.SCROLL_LOCK);
@@ -119,7 +150,8 @@ export class MDCDialogFoundation extends MDCFoundation<MDCDialogAdapter> {
 
   close(action = '') {
     if (!this.dialogOpen) {
-      // Avoid redundant close calls (and events), e.g. from keydown on elements that inherently emit click
+      // Avoid redundant close calls (and events), e.g. from keydown on elements
+      // that inherently emit click
       return;
     }
 
@@ -128,6 +160,10 @@ export class MDCDialogFoundation extends MDCFoundation<MDCDialogAdapter> {
     this.adapter.addClass(cssClasses.CLOSING);
     this.adapter.removeClass(cssClasses.OPEN);
     this.adapter.removeBodyClass(cssClasses.SCROLL_LOCK);
+    if (this.isFullscreen && this.adapter.isContentScrollable()) {
+      this.adapter.deregisterContentEventHandler(
+          'scroll', this.contentScrollHandler);
+    }
 
     cancelAnimationFrame(this.animationFrame);
     this.animationFrame = 0;
@@ -245,11 +281,25 @@ export class MDCDialogFoundation extends MDCFoundation<MDCDialogAdapter> {
     }
   }
 
+  /**
+   * Handles scroll event on the dialog's content element -- showing a scroll
+   * divider on the header or footer based on the scroll position. This handler
+   * should only be registered on full-screen dialogs with scrollable content.
+   */
+  private handleScrollEvent() {
+    // Since scroll events can fire at a high rate, we throttle these events by
+    // using requestAnimationFrame.
+    this.animFrame.request(AnimationKeys.POLL_SCROLL_POS, () => {
+      this.toggleScrollDividerHeader();
+      this.toggleScrollDividerFooter();
+    });
+  }
+
   private layoutInternal() {
     if (this.autoStackButtons) {
       this.detectStackedButtons();
     }
-    this.detectScrollableContent();
+    this.toggleScrollableClasses();
   }
 
   private handleAnimationTimerEnd() {
@@ -259,7 +309,8 @@ export class MDCDialogFoundation extends MDCFoundation<MDCDialogAdapter> {
   }
 
   /**
-   * Runs the given logic on the next animation frame, using setTimeout to factor in Firefox reflow behavior.
+   * Runs the given logic on the next animation frame, using setTimeout to
+   * factor in Firefox reflow behavior.
    */
   private runNextAnimationFrame(callback: () => void) {
     cancelAnimationFrame(this.animationFrame);
@@ -286,11 +337,35 @@ export class MDCDialogFoundation extends MDCFoundation<MDCDialogAdapter> {
     }
   }
 
-  private detectScrollableContent() {
-    // Remove the class first to let us measure the natural height of the content.
+  private toggleScrollableClasses() {
+    // Remove the class first to let us measure the natural height of the
+    // content.
     this.adapter.removeClass(cssClasses.SCROLLABLE);
     if (this.adapter.isContentScrollable()) {
       this.adapter.addClass(cssClasses.SCROLLABLE);
+
+      if (this.isFullscreen) {
+        // If dialog is full-screen and scrollable, check if a scroll divider
+        // should be shown.
+        this.toggleScrollDividerHeader();
+        this.toggleScrollDividerFooter();
+      }
+    }
+  }
+
+  private toggleScrollDividerHeader() {
+    if (!this.adapter.isScrollableContentAtTop()) {
+      this.adapter.addClass(cssClasses.SCROLL_DIVIDER_HEADER);
+    } else if (this.adapter.hasClass(cssClasses.SCROLL_DIVIDER_HEADER)) {
+      this.adapter.removeClass(cssClasses.SCROLL_DIVIDER_HEADER);
+    }
+  }
+
+  private toggleScrollDividerFooter() {
+    if (!this.adapter.isScrollableContentAtBottom()) {
+      this.adapter.addClass(cssClasses.SCROLL_DIVIDER_FOOTER);
+    } else if (this.adapter.hasClass(cssClasses.SCROLL_DIVIDER_FOOTER)) {
+      this.adapter.removeClass(cssClasses.SCROLL_DIVIDER_FOOTER);
     }
   }
 }