docs(cdk/scrolling): Docs for new virtual scroll features added in #24394 (#25043)

Author: mmalerba

src/cdk/scrolling/scrolling.md

@@ -128,3 +128,21 @@ to the list as the user scrolls without removing rendered views. The `appendOnly
 views that are already rendered persist in the DOM after they scroll out of view.
 
 <!-- example(cdk-virtual-scroll-append-only) -->
+
+### Separate viewport and scrolling element
+The virtual scroll viewport itself acts as the scrolling element by default. However, there may be
+some cases where you want to have the viewport scroll one of its parent elements. For example,
+if you want to have some non-virtualized content that the user can scroll through before or after
+the virtualized content.
+
+To configure a `cdk-vritual-scroll-viewport` to use one of its parent elements as the scrolling
+element, apply `cdkVirtualScrollingElement` to the scrolling parent element.
+
+<!-- example(cdk-virtual-scroll-parent-scrolling) -->
+
+Another common scenario is using the window itself as the scrolling element. This often a better
+user experience on mobile devices, as it allows the browser chrome to scroll away. To use the
+window as the scrolling element, add the `scrollWindow` attribute to the 
+`cdk-virtual-scroll-viewport`.
+
+<!-- example(cdk-virtual-scroll-window-scrolling) -->

src/components-examples/cdk/scrolling/cdk-virtual-scroll-parent-scrolling/cdk-virtual-scroll-parent-scrolling-example.css

@@ -0,0 +1,16 @@
+.example-viewport {
+  flex: 1;
+  width: 200px;
+  min-height: 200px;
+  border: 1px solid black;
+}
+
+.example-item {
+  height: 50px;
+}
+
+.example-header,
+.example-footer {
+  height: 100px;
+  background: lightgray;
+}

src/components-examples/cdk/scrolling/cdk-virtual-scroll-parent-scrolling/cdk-virtual-scroll-parent-scrolling-example.html

@@ -0,0 +1,7 @@
+<div class="example-viewport" cdkVirtualScrollingElement>
+  <div class="example-header">Content before</div>
+  <cdk-virtual-scroll-viewport itemSize="50">
+    <div *cdkVirtualFor="let item of items" class="example-item">{{item}}</div>
+  </cdk-virtual-scroll-viewport>
+  <div class="example-footer">Content after</div>
+</div>

src/components-examples/cdk/scrolling/cdk-virtual-scroll-parent-scrolling/cdk-virtual-scroll-parent-scrolling-example.ts

@@ -0,0 +1,12 @@
+import {ChangeDetectionStrategy, Component} from '@angular/core';
+
+/** @title Virtual scrolling viewport parent element */
+@Component({
+  selector: 'cdk-virtual-scroll-parent-scrolling-example',
+  styleUrls: ['cdk-virtual-scroll-parent-scrolling-example.css'],
+  templateUrl: 'cdk-virtual-scroll-parent-scrolling-example.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class CdkVirtualScrollParentScrollingExample {
+  items = Array.from({length: 100000}).map((_, i) => `Item #${i}`);
+}

src/components-examples/cdk/scrolling/cdk-virtual-scroll-window-scrolling/cdk-virtual-scroll-window-scrolling-example.css

@@ -0,0 +1,9 @@
+.example-item {
+  height: 50px;
+}
+
+.example-header,
+.example-footer {
+  height: 100px;
+  background: lightgray;
+}

src/components-examples/cdk/scrolling/cdk-virtual-scroll-window-scrolling/cdk-virtual-scroll-window-scrolling-example.html

@@ -0,0 +1,9 @@
+<ng-container *ngIf="shouldRun">
+  <div class="example-header">Content before</div>
+  <cdk-virtual-scroll-viewport scrollWindow itemSize="50">
+    <div *cdkVirtualFor="let item of items" class="example-item">{{item}}</div>
+  </cdk-virtual-scroll-viewport>
+  <div class="example-footer">Content after</div>
+</ng-container>
+
+<div *ngIf="!shouldRun">Please open on StackBlitz to see result</div>

src/components-examples/cdk/scrolling/cdk-virtual-scroll-window-scrolling/cdk-virtual-scroll-window-scrolling-example.ts

@@ -0,0 +1,14 @@
+import {ChangeDetectionStrategy, Component, Input} from '@angular/core';
+
+/** @title Virtual scrolling window */
+@Component({
+  selector: 'cdk-virtual-scroll-window-scrolling-example',
+  styleUrls: ['cdk-virtual-scroll-window-scrolling-example.css'],
+  templateUrl: 'cdk-virtual-scroll-window-scrolling-example.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class CdkVirtualScrollWindowScrollingExample {
+  @Input() shouldRun = /(^|.)(stackblitz|webcontainer).(io|com)$/.test(window.location.host);
+
+  items = Array.from({length: 100000}).map((_, i) => `Item #${i}`);
+}

src/components-examples/cdk/scrolling/index.ts

@@ -8,7 +8,10 @@ import {CdkVirtualScrollDlExample} from './cdk-virtual-scroll-dl/cdk-virtual-scr
 import {CdkVirtualScrollFixedBufferExample} from './cdk-virtual-scroll-fixed-buffer/cdk-virtual-scroll-fixed-buffer-example';
 import {CdkVirtualScrollHorizontalExample} from './cdk-virtual-scroll-horizontal/cdk-virtual-scroll-horizontal-example';
 import {CdkVirtualScrollOverviewExample} from './cdk-virtual-scroll-overview/cdk-virtual-scroll-overview-example';
+import {CdkVirtualScrollParentScrollingExample} from './cdk-virtual-scroll-parent-scrolling/cdk-virtual-scroll-parent-scrolling-example';
 import {CdkVirtualScrollTemplateCacheExample} from './cdk-virtual-scroll-template-cache/cdk-virtual-scroll-template-cache-example';
+import {CdkVirtualScrollWindowScrollingExample} from './cdk-virtual-scroll-window-scrolling/cdk-virtual-scroll-window-scrolling-example';
+import {CommonModule} from '@angular/common';
 
 export {
   CdkVirtualScrollAppendOnlyExample,
@@ -20,6 +23,8 @@ export {
   CdkVirtualScrollHorizontalExample,
   CdkVirtualScrollOverviewExample,
   CdkVirtualScrollTemplateCacheExample,
+  CdkVirtualScrollParentScrollingExample,
+  CdkVirtualScrollWindowScrollingExample,
 };
 
 const EXAMPLES = [
@@ -32,10 +37,12 @@ const EXAMPLES = [
   CdkVirtualScrollHorizontalExample,
   CdkVirtualScrollOverviewExample,
   CdkVirtualScrollTemplateCacheExample,
+  CdkVirtualScrollParentScrollingExample,
+  CdkVirtualScrollWindowScrollingExample,
 ];
 
 @NgModule({
-  imports: [ScrollingModule],
+  imports: [CommonModule, ScrollingModule],
   declarations: EXAMPLES,
   exports: EXAMPLES,
 })

src/dev-app/virtual-scroll/BUILD.bazel

@@ -12,6 +12,7 @@ ng_module(
     deps = [
         "//src/cdk-experimental/scrolling",
         "//src/cdk/scrolling",
+        "//src/components-examples/cdk/scrolling",
         "//src/material/button",
         "//src/material/form-field",
         "//src/material/input",

src/dev-app/virtual-scroll/virtual-scroll-demo.html

@@ -179,24 +179,10 @@ <h2>Append only</h2>
   </div>
 </cdk-virtual-scroll-viewport>
 
-<h2>Custom virtual scroller</h2>
-
-<div class="demo-viewport" cdkVirtualScrollingElement>
-  <p>Content before virtual scrolling items</p>
-  <cdk-virtual-scroll-viewport itemSize="50">
-    <div *cdkVirtualFor="let size of fixedSizeData; let i = index" class="demo-item"
-         [style.height.px]="size">
-      Item #{{i}} - ({{size}}px)
-    </div>
-  </cdk-virtual-scroll-viewport>
-  <p>Content after virtual scrolling items</p>
-</div>
-
-<h2>Window virtual scroller</h2>
-
-<cdk-virtual-scroll-viewport scrollWindow itemSize="50">
-  <div *cdkVirtualFor="let size of fixedSizeData; let i = index" class="demo-item"
-       [style.height.px]="size">
-    Item #{{i}} - ({{size}}px)
-  </div>
-</cdk-virtual-scroll-viewport>
+<h2>Virtual scroller with scrolling parent</h2>
+<cdk-virtual-scroll-parent-scrolling-example class="demo-resize-example">
+</cdk-virtual-scroll-parent-scrolling-example>
+
+<h2>Virtual scroller with scrolling window</h2>
+<cdk-virtual-scroll-window-scrolling-example [shouldRun]="true">
+</cdk-virtual-scroll-window-scrolling-example>