docs: add example for providing custom MatPaginatorIntl (#22771)

Adds an example for providing a custom `MatPaginatorIntl`. The
example also show-cases the use with `@angular/localize`.

Fixes #8239.

Author: devversion

package.json

@@ -77,6 +77,7 @@
     "@angular/bazel": "^12.0.0",
     "@angular/compiler-cli": "^12.0.0",
     "@angular/dev-infra-private": "https://github.com/angular/dev-infra-private-builds.git#2e0271af93b020a811323fbc274afcf588dbc91e",
+    "@angular/localize": "^12.0.0",
     "@angular/platform-browser-dynamic": "^12.0.0",
     "@angular/platform-server": "^12.0.0",
     "@angular/router": "^12.0.0",

packages.bzl

@@ -25,6 +25,7 @@ VERSION_PLACEHOLDER_REPLACEMENTS = {
 # List of default Angular library UMD bundles which are not processed by ngcc.
 ANGULAR_NO_NGCC_BUNDLES = [
     ("@angular/compiler", ["compiler.umd.js"]),
+    ("@angular/localize", ["localize.umd.js", "localize-init.umd.js"]),
 ]
 
 # List of Angular library UMD bundles which will are processed by ngcc.

scripts/check-rollup-globals.ts

@@ -30,6 +30,7 @@ const filesToCheckGlob = [
   '!src/+(e2e-app|universal-app|dev-app)/**/*.ts',
   '!src/**/schematics/**/*.ts',
   '!src/**/tests/**/*.ts',
+  '!src/components-examples/private/localize-types.d.ts',
 ];
 
 const failures = new Map<string, string[]>();

src/components-examples/material/paginator/BUILD.bazel

@@ -16,6 +16,7 @@ ng_module(
     deps = [
         "//src/cdk/testing",
         "//src/cdk/testing/testbed",
+        "//src/components-examples/private:localize_types",
         "//src/material/input",
         "//src/material/paginator",
         "//src/material/paginator/testing",

src/components-examples/material/paginator/index.ts

@@ -8,16 +8,22 @@ import {
 } from './paginator-configurable/paginator-configurable-example';
 import {PaginatorOverviewExample} from './paginator-overview/paginator-overview-example';
 import {PaginatorHarnessExample} from './paginator-harness/paginator-harness-example';
+import {
+  PaginatorIntlExample,
+  PaginatorIntlExampleModule,
+} from './paginator-intl/paginator-intl-example';
 
 export {
   PaginatorConfigurableExample,
   PaginatorHarnessExample,
+  PaginatorIntlExample,
   PaginatorOverviewExample,
 };
 
 const EXAMPLES = [
   PaginatorConfigurableExample,
   PaginatorHarnessExample,
+  // PaginatorIntlExample is imported through it's own example module.
   PaginatorOverviewExample,
 ];
 
@@ -26,6 +32,7 @@ const EXAMPLES = [
     CommonModule,
     MatInputModule,
     MatPaginatorModule,
+    PaginatorIntlExampleModule,
     FormsModule,
   ],
   declarations: EXAMPLES,

src/components-examples/material/paginator/paginator-intl/paginator-intl-example.html

@@ -0,0 +1,2 @@
+<mat-paginator [length]="0" [pageSizeOptions]="[10, 50, 100]">
+</mat-paginator>

src/components-examples/material/paginator/paginator-intl/paginator-intl-example.ts

@@ -0,0 +1,45 @@
+import {Component, Injectable, NgModule} from '@angular/core';
+import {MatPaginatorIntl, MatPaginatorModule} from '@angular/material/paginator';
+import {Subject} from 'rxjs';
+
+@Injectable()
+export class MyCustomPaginatorIntl implements MatPaginatorIntl {
+  changes = new Subject<void>();
+
+  // For internationalization, the `$localize` function from
+  // the `@angular/localize` package can be used.
+  firstPageLabel = $localize`First page`;
+  itemsPerPageLabel = $localize`Items per page:`;
+  lastPageLabel = $localize`Last page`;
+
+  // You can set labels to an arbitrary string too, or dynamically compute
+  // it through other third-party internationalization libraries.
+  nextPageLabel = 'Next page';
+  previousPageLabel = 'Previous page';
+
+  getRangeLabel(page: number, pageSize: number, length: number): string {
+    if (length === 0) {
+      return $localize`Page 1 of 1`;
+    }
+    const amountPages = Math.ceil(length / pageSize);
+    return $localize`Page ${page + 1} of ${amountPages}`;
+  }
+}
+
+/**
+ * @title Paginator internationalization
+ */
+@Component({
+  selector: 'paginator-intl-example',
+  templateUrl: 'paginator-intl-example.html',
+})
+export class PaginatorIntlExample {}
+
+@NgModule({
+  imports: [MatPaginatorModule],
+  declarations: [PaginatorIntlExample],
+  providers: [
+    {provide: MatPaginatorIntl, useClass: MyCustomPaginatorIntl}
+  ]
+})
+export class PaginatorIntlExampleModule {}

src/components-examples/private/BUILD.bazel

@@ -11,3 +11,8 @@ ts_library(
         "@npm//@angular/core",
     ],
 )
+
+ts_library(
+    name = "localize_types",
+    srcs = ["localize-types.d.ts"],
+)

src/components-examples/private/localize-types.d.ts

@@ -0,0 +1,5 @@
+import {LocalizeFn} from '@angular/localize/src/localize';
+
+declare global {
+  const $localize: LocalizeFn;
+}

src/dev-app/BUILD.bazel

@@ -96,6 +96,7 @@ ng_module(
         "//src/dev-app/virtual-scroll",
         "//src/dev-app/youtube-player",
         "//src/material/core",
+        "@npm//@angular/localize",
         "@npm//@angular/router",
     ],
 )