docs: allow module imports to be copied from API tab

adds icon button next to module import text allowing users to copy it directly

fixes #16127

Author: naaajii

material.angular.io/src/app/shared/doc-viewer/doc-viewer-module.ts

@@ -10,7 +10,7 @@ import {NgModule} from '@angular/core';
 import {HeaderLink} from './header-link';
 import {CodeSnippet} from '../example-viewer/code-snippet';
 import {DeprecatedFieldComponent} from './deprecated-tooltip';
-
+import {ModuleImportCopyButton} from './module-import-copy-button';
 
 // ExampleViewer is included in the DocViewerModule because they have a circular dependency.
 @NgModule({
@@ -25,8 +25,9 @@ import {DeprecatedFieldComponent} from './deprecated-tooltip';
     ExampleViewer,
     HeaderLink,
     CodeSnippet,
-    DeprecatedFieldComponent
+    DeprecatedFieldComponent,
+    ModuleImportCopyButton,
   ],
-  exports: [DocViewer, ExampleViewer, HeaderLink, DeprecatedFieldComponent]
+  exports: [DocViewer, ExampleViewer, HeaderLink, DeprecatedFieldComponent, ModuleImportCopyButton],
 })
-export class DocViewerModule { }
+export class DocViewerModule {}

material.angular.io/src/app/shared/doc-viewer/doc-viewer.spec.ts

@@ -7,13 +7,17 @@ import {DocViewer} from './doc-viewer';
 import {DocViewerModule} from './doc-viewer-module';
 import {ExampleViewer} from '../example-viewer/example-viewer';
 import {MatTooltip} from '@angular/material/tooltip';
+import {MatIconButton} from '@angular/material/button';
+import {Clipboard} from '@angular/cdk/clipboard';
 
 describe('DocViewer', () => {
   let http: HttpTestingController;
+  const clipboardSpy = jasmine.createSpyObj<Clipboard>('Clipboard', ['copy']);
 
   beforeEach(waitForAsync(() => {
     TestBed.configureTestingModule({
       imports: [DocViewerModule, DocsAppTestingModule, DocViewerTestComponent],
+      providers: [{provide: Clipboard, useValue: clipboardSpy}],
     }).compileComponents();
   }));
 
@@ -142,10 +146,10 @@ describe('DocViewer', () => {
 
     http.expectOne(errorUrl).flush('Not found', {status: 404, statusText: 'Not found'});
 
-
     expect(docViewer).not.toBeNull();
     expect(docViewer.nativeElement.innerHTML).toContain(
-        'Failed to load document: http://material.angular.io/error-doc.html');
+      'Failed to load document: http://material.angular.io/error-doc.html',
+    );
     expect(console.error).toHaveBeenCalledTimes(1);
   });
 
@@ -165,7 +169,7 @@ describe('DocViewer', () => {
     // and properties.
     expect(docViewer.children.length).toBe(5);
 
-    // it should have "Deprecated" as its inner text 
+    // it should have "Deprecated" as its inner text
     const deprecatedSymbol = docViewer.children.shift()!;
     expect(deprecatedSymbol.nativeElement.innerText).toBe('Deprecated');
 
@@ -179,6 +183,27 @@ describe('DocViewer', () => {
     expect(deprecatedSymbol.query(By.directive(MatTooltip))).toBeTruthy();
   });
 
+  it('should show copy icon button for module imports', () => {
+    const fixture = TestBed.createComponent(DocViewerTestComponent);
+    fixture.componentInstance.documentUrl = `http://material.angular.io/copy-module-import.html`;
+    fixture.detectChanges();
+
+    const url = fixture.componentInstance.documentUrl;
+    http.expectOne(url).flush(FAKE_DOCS[url]);
+
+    const docViewer = fixture.debugElement.query(By.directive(DocViewer));
+    expect(docViewer).not.toBeNull();
+
+    const iconButton = fixture.debugElement.query(By.directive(MatIconButton));
+    // icon button for copying module import should exist
+    expect(iconButton).toBeTruthy();
+
+    // click on icon button to trigger copying the module import
+    iconButton.nativeNode.dispatchEvent(new MouseEvent('click'));
+    fixture.detectChanges();
+    expect(clipboardSpy.copy).toHaveBeenCalled();
+  });
+
   // TODO(mmalerba): Add test that example-viewer is instantiated.
 });
 
@@ -207,8 +232,7 @@ const FAKE_DOCS: {[key: string]: string} = {
     '<div material-docs-example="demo-example"></div>',
   'http://material.angular.io/whole-snippet-example.html':
     '<div material-docs-example="whole-snippet-example" file="whole-snippet-example.ts"></div>',
-  'http://material.angular.io/deprecated.html':
-    `<div class="docs-api-class-deprecated-marker" 
+  'http://material.angular.io/deprecated.html': `<div class="docs-api-class-deprecated-marker" 
         deprecated-message="deprecated class">Deprecated</div>
   
       <div class="docs-api-constant-deprecated-marker" 
@@ -222,6 +246,17 @@ const FAKE_DOCS: {[key: string]: string} = {
         
       <div class="docs-api-deprecated-marker" 
         deprecated-message="deprecated">Deprecated</div>`,
+  'http://material.angular.io/copy-module-import.html': `<div class="docs-api-module">
+      <p class="docs-api-module-import">
+        <code>
+          import {MatIconModule} from '@angular/material/icon';
+        </code>
+      </p>
+
+      <div class="docs-api-module-import-button" 
+        data-docs-api-module-import-button="import {MatIconModule} from '@angular/material/icon';">
+      </div>
+    </div>`,
   /* eslint-enable @typescript-eslint/naming-convention */
 };
 

material.angular.io/src/app/shared/doc-viewer/doc-viewer.ts

@@ -3,7 +3,7 @@ import {
   ComponentPortal,
   DomPortalOutlet,
   Portal,
-  PortalModule
+  PortalModule,
 } from '@angular/cdk/portal';
 import {HttpClient, HttpErrorResponse} from '@angular/common/http';
 import {DomSanitizer} from '@angular/platform-browser';
@@ -21,13 +21,14 @@ import {
   Output,
   SecurityContext,
   ViewContainerRef,
-  input
+  input,
 } from '@angular/core';
 import {Observable, Subscription} from 'rxjs';
 import {shareReplay, take, tap} from 'rxjs/operators';
 import {ExampleViewer} from '../example-viewer/example-viewer';
 import {HeaderLink} from './header-link';
 import {DeprecatedFieldComponent} from './deprecated-tooltip';
+import {ModuleImportCopyButton} from './module-import-copy-button';
 
 @Injectable({providedIn: 'root'})
 class DocFetcher {
@@ -41,7 +42,7 @@ class DocFetcher {
     }
 
     const stream = this._http.get(url, {responseType: 'text'}).pipe(shareReplay(1));
-    return stream.pipe(tap(() => this._cache[url] = stream));
+    return stream.pipe(tap(() => (this._cache[url] = stream)));
   }
 }
 
@@ -55,7 +56,7 @@ class DocFetcher {
     }
   `,
   standalone: true,
-  imports: [PortalModule]
+  imports: [PortalModule],
 })
 export class DocViewer implements OnDestroy {
   private _portalHosts: DomPortalOutlet[] = [];
@@ -86,10 +87,12 @@ export class DocViewer implements OnDestroy {
   /** The document text. It should not be HTML encoded. */
   textContent = '';
 
-  private static initExampleViewer(exampleViewerComponent: ExampleViewer,
-                                   example: string,
-                                   file: string | null,
-                                   region: string | null) {
+  private static initExampleViewer(
+    exampleViewerComponent: ExampleViewer,
+    example: string,
+    file: string | null,
+    region: string | null,
+  ) {
     exampleViewerComponent.example = example;
     if (file) {
       // if the html div has field `file` then it should be in compact view to show the code
@@ -106,25 +109,25 @@ export class DocViewer implements OnDestroy {
       // otherwise it is an embedded demo
       exampleViewerComponent.view = 'demo';
     }
-
   }
 
-  constructor(private _appRef: ApplicationRef,
-              private _componentFactoryResolver: ComponentFactoryResolver,
-              public _elementRef: ElementRef,
-              private _injector: Injector,
-              private _viewContainerRef: ViewContainerRef,
-              private _ngZone: NgZone,
-              private _domSanitizer: DomSanitizer,
-              private _docFetcher: DocFetcher) {
-  }
+  constructor(
+    private _appRef: ApplicationRef,
+    private _componentFactoryResolver: ComponentFactoryResolver,
+    public _elementRef: ElementRef,
+    private _injector: Injector,
+    private _viewContainerRef: ViewContainerRef,
+    private _ngZone: NgZone,
+    private _domSanitizer: DomSanitizer,
+    private _docFetcher: DocFetcher,
+  ) {}
 
   /** Fetch a document by URL. */
   private _fetchDocument(url: string) {
     this._documentFetchSubscription?.unsubscribe();
     this._documentFetchSubscription = this._docFetcher.fetchDocument(url).subscribe(
       document => this.updateDocument(document),
-      error => this.showError(url, error)
+      error => this.showError(url, error),
     );
   }
 
@@ -148,6 +151,9 @@ export class DocViewer implements OnDestroy {
     // Create tooltips for the deprecated fields
     this._createTooltipsForDeprecated();
 
+    // Create icon buttons to copy module import
+    this._createCopyIconForModule();
+
     // Resolving and creating components dynamically in Angular happens synchronously, but since
     // we want to emit the output if the components are actually rendered completely, we wait
     // until the Angular zone becomes stable.
@@ -159,21 +165,23 @@ export class DocViewer implements OnDestroy {
   /** Show an error that occurred when fetching a document. */
   private showError(url: string, error: HttpErrorResponse) {
     console.error(error);
-    this._elementRef.nativeElement.innerText =
-      `Failed to load document: ${url}. Error: ${error.statusText}`;
+    this._elementRef.nativeElement.innerText = `Failed to load document: ${url}. Error: ${error.statusText}`;
   }
 
   /** Instantiate a ExampleViewer for each example. */
   private _loadComponents(componentName: string, componentClass: any) {
-    const exampleElements =
-        this._elementRef.nativeElement.querySelectorAll(`[${componentName}]`);
+    const exampleElements = this._elementRef.nativeElement.querySelectorAll(`[${componentName}]`);
 
     [...exampleElements].forEach((element: Element) => {
       const example = element.getAttribute(componentName);
       const region = element.getAttribute('region');
       const file = element.getAttribute('file');
       const portalHost = new DomPortalOutlet(
-          element, this._componentFactoryResolver, this._appRef, this._injector);
+        element,
+        this._componentFactoryResolver,
+        this._appRef,
+        this._injector,
+      );
       const examplePortal = new ComponentPortal(componentClass, this._viewContainerRef);
       const exampleViewer = portalHost.attach(examplePortal);
       const exampleViewerComponent = exampleViewer.instance as ExampleViewer;
@@ -195,36 +203,71 @@ export class DocViewer implements OnDestroy {
   }
 
   _createTooltipsForDeprecated() {
-    // all of the deprecated symbols end with `deprecated-marker` 
+    // all of the deprecated symbols end with `deprecated-marker`
     // class name on their element.
-    // for example: 
-    // <div class="docs-api-deprecated-marker">Deprecated</div>, 
+    // for example:
+    // <div class="docs-api-deprecated-marker">Deprecated</div>,
     // these can vary for each deprecated symbols such for class, interface,
     // type alias, constants or properties:
     // .docs-api-class-interface-marker, docs-api-type-alias-deprecated-marker
     // .docs-api-constant-deprecated-marker, .some-more
     // so instead of manually writing each deprecated class, we just query
     // elements that ends with `deprecated-marker` in their class name.
-    const deprecatedElements =
-      this._elementRef.nativeElement.querySelectorAll(`[class$=deprecated-marker]`);
+    const deprecatedElements = this._elementRef.nativeElement.querySelectorAll(
+      `[class$=deprecated-marker]`,
+    );
 
     [...deprecatedElements].forEach((element: Element) => {
       // the deprecation message, it will include alternative to deprecated item
       // and breaking change if there is one included.
       const deprecationTitle = element.getAttribute('deprecated-message');
 
       const elementPortalOutlet = new DomPortalOutlet(
-        element, this._componentFactoryResolver, this._appRef, this._injector);
+        element,
+        this._componentFactoryResolver,
+        this._appRef,
+        this._injector,
+      );
 
       const tooltipPortal = new ComponentPortal(DeprecatedFieldComponent, this._viewContainerRef);
       const tooltipOutlet = elementPortalOutlet.attach(tooltipPortal);
 
-
       if (deprecationTitle) {
         tooltipOutlet.instance.message = deprecationTitle;
       }
 
       this._portalHosts.push(elementPortalOutlet);
     });
   }
+
+  _createCopyIconForModule() {
+    // every module import element will be marked with docs-api-module-import-button attribute
+    const moduleImportElements = this._elementRef.nativeElement.querySelectorAll(
+      '[data-docs-api-module-import-button]',
+    );
+
+    [...moduleImportElements].forEach((element: HTMLElement) => {
+      // get the module import path stored in the attribute
+      const moduleImport = element.getAttribute('data-docs-api-module-import-button');
+
+      const elementPortalOutlet = new DomPortalOutlet(
+        element,
+        this._componentFactoryResolver,
+        this._appRef,
+        this._injector,
+      );
+
+      const moduleImportPortal = new ComponentPortal(
+        ModuleImportCopyButton,
+        this._viewContainerRef,
+      );
+      const moduleImportOutlet = elementPortalOutlet.attach(moduleImportPortal);
+
+      if (moduleImport) {
+        moduleImportOutlet.instance.import = moduleImport;
+      }
+
+      this._portalHosts.push(elementPortalOutlet);
+    });
+  }
 }

material.angular.io/src/app/shared/doc-viewer/module-import-copy-button.ts

@@ -0,0 +1,34 @@
+import {Component, inject} from '@angular/core';
+import {MatIconButton} from '@angular/material/button';
+import {MatIcon} from '@angular/material/icon';
+import {MatSnackBar} from '@angular/material/snack-bar';
+import {MatTooltip} from '@angular/material/tooltip';
+import {Clipboard} from '@angular/cdk/clipboard';
+
+/**
+ * Shows up an icon button which will allow users to copy the module import
+ */
+@Component({
+  selector: 'module-import-copy-button',
+  template: `<button
+  mat-icon-button
+  matTooltip="Copy import to the clipboard"
+  (click)="copy()">
+  <mat-icon>content_copy</mat-icon>
+</button>`,
+  standalone: true,
+  imports: [MatIconButton, MatIcon, MatTooltip],
+})
+export class ModuleImportCopyButton {
+  private clipboard = inject(Clipboard);
+  private snackbar = inject(MatSnackBar);
+  /** Import path for the module that will be copied */
+  import = '';
+
+  copy(): void {
+    const message = this.clipboard.copy(this.import)
+      ? 'Copied module import'
+      : 'Failed to copy module import';
+    this.snackbar.open(message, undefined, {duration: 2500});
+  }
+}

material.angular.io/src/styles/_api.scss

@@ -27,6 +27,15 @@
   word-break: break-word;
 }
 
+.docs-api-module {
+  display: flex;
+  align-items: center;
+}
+
+.docs-api-module-import {
+  margin: 0px;
+}
+
 .docs-api-class-name,
 .docs-api-module-import,
 .docs-api-class-selector-name,