build: fix chips drag-drop example not working and improve example-module generation

Loading the chips-drag-drop example in the docs site is currently not
possible, as the example files fail to load. This is because the example
id does not match up with the directory that the example is stored within.

This highlights an issue as the docs site assumes a certain folder
structure. This is not ideal and an implementation detail specific to
the Angular Components repository. The docs site should not need to
make any assumptions about where code lives, but instead should just
retrieve this information through the example information. That way we
are free to change layout/file conventions in the components repository
without having to worry about it breaking the docs site.

This is implemented as part of this commit. Also a few sanity checks
that enforce consistency (for improved code health) have been added. The
new concept for examples also allows us to remove empty CSS files for
examples without CSS.

Author: devversion

src/components-examples/cdk/stepper/cdk-linear-stepper-with-form/cdk-linear-stepper-with-form-example.ts

@@ -4,7 +4,7 @@ import {FormBuilder, FormGroup, Validators} from '@angular/forms';
 
 /** @title A custom CDK linear stepper with forms */
 @Component({
-  selector: 'cdk-linear-stepper-with-form',
+  selector: 'cdk-linear-stepper-with-form-example',
   templateUrl: './cdk-linear-stepper-with-form-example.html',
   styleUrls: ['./cdk-linear-stepper-with-form-example.css']
 })

src/components-examples/example-data.ts

@@ -27,15 +27,13 @@ export class ExampleData {
       return;
     }
 
-    const {componentName, additionalFiles, additionalComponents, title} =
+    const {componentName, files, selector, primaryFile, additionalComponents, title} =
         EXAMPLE_COMPONENTS[example];
     const exampleName = example.replace(/(?:^\w|\b\w)/g, letter => letter.toUpperCase());
 
-    // TODO(tinayuangao): Do not hard-code extensions
-    this.exampleFiles = ['html', 'ts', 'css'].map(extension => `${example}-example.${extension}`);
-    this.selectorName = this.indexFilename = `${example}-example`;
-
-    this.exampleFiles.push(...additionalFiles);
+    this.exampleFiles = files;
+    this.selectorName = selector;
+    this.indexFilename = primaryFile;
     this.description = title || exampleName.replace(/[\-]+/g, ' ') + ' Example';
     this.componentNames = [componentName, ...additionalComponents];
   }

src/components-examples/material-experimental/column-resize/default-enabled-flex/default-enabled-column-resize-flex-example-module.ts renamed to src/components-examples/material-experimental/column-resize/default-enabled-column-resize-flex/default-enabled-column-resize-flex-example-module.ts

@@ -1,32 +1,34 @@
 import {NgModule} from '@angular/core';
-import {OptInColumnResizeExampleModule} from './opt-in/opt-in-column-resize-example-module';
 import {
-  DefaultEnabledColumnResizeExampleModule,
-} from './default-enabled/default-enabled-column-resize-example-module';
+  DefaultEnabledColumnResizeFlexExampleModule
+} from './default-enabled-column-resize-flex/default-enabled-column-resize-flex-example-module';
+import {
+  DefaultEnabledColumnResizeExampleModule
+} from './default-enabled-column-resize/default-enabled-column-resize-example-module';
 import {
-  DefaultEnabledColumnResizeFlexExampleModule,
-} from './default-enabled-flex/default-enabled-column-resize-flex-example-module';
+  OptInColumnResizeExampleModule
+} from './opt-in-column-resize/opt-in-column-resize-example-module';
 
 export {
   DefaultEnabledColumnResizeExample
-} from './default-enabled/default-enabled-column-resize-example';
+} from './default-enabled-column-resize/default-enabled-column-resize-example';
 export {
   DefaultEnabledColumnResizeExampleModule
-} from './default-enabled/default-enabled-column-resize-example-module';
+} from './default-enabled-column-resize/default-enabled-column-resize-example-module';
 
 export {
   DefaultEnabledColumnResizeFlexExample
-} from './default-enabled-flex/default-enabled-column-resize-flex-example';
+} from './default-enabled-column-resize-flex/default-enabled-column-resize-flex-example';
 export {
   DefaultEnabledColumnResizeFlexExampleModule
-} from './default-enabled-flex/default-enabled-column-resize-flex-example-module';
+} from './default-enabled-column-resize-flex/default-enabled-column-resize-flex-example-module';
 
 export {
   OptInColumnResizeExample
-} from './opt-in/opt-in-column-resize-example';
+} from './opt-in-column-resize/opt-in-column-resize-example';
 export {
   OptInColumnResizeExampleModule
-} from './opt-in/opt-in-column-resize-example-module';
+} from './opt-in-column-resize/opt-in-column-resize-example-module';
 
 
 @NgModule({

src/components-examples/material-experimental/column-resize/default-enabled-flex/default-enabled-column-resize-flex-example.css renamed to src/components-examples/material-experimental/column-resize/default-enabled-column-resize-flex/default-enabled-column-resize-flex-example.css

@@ -4,17 +4,17 @@ import {ReactiveFormsModule} from '@angular/forms';
 import {MatFormFieldModule} from '@angular/material-experimental/mdc-form-field';
 import {MatIconModule} from '@angular/material/icon';
 import {
-  FormFieldCustomControlExample,
+  MdcFormFieldCustomControlExample,
   MyTelInput
 } from './mdc-form-field-custom-control/form-field-custom-control-example';
 
 export {
-  FormFieldCustomControlExample,
+  MdcFormFieldCustomControlExample,
   MyTelInput,
 };
 
 const EXAMPLES = [
-  FormFieldCustomControlExample,
+  MdcFormFieldCustomControlExample,
 ];
 
 @NgModule({

src/components-examples/material-experimental/column-resize/default-enabled-flex/default-enabled-column-resize-flex-example.html renamed to src/components-examples/material-experimental/column-resize/default-enabled-column-resize-flex/default-enabled-column-resize-flex-example.html

@@ -7,11 +7,11 @@ import {Subject} from 'rxjs';
 
 /** @title Form field with custom telephone number input control. */
 @Component({
-  selector: 'form-field-custom-control-example',
+  selector: 'mdc-form-field-custom-control-example',
   templateUrl: 'form-field-custom-control-example.html',
   styleUrls: ['form-field-custom-control-example.css'],
 })
-export class FormFieldCustomControlExample {}
+export class MdcFormFieldCustomControlExample {}
 
 /** Data structure for holding telephone number. */
 export class MyTel {

src/components-examples/material-experimental/column-resize/default-enabled-flex/default-enabled-column-resize-flex-example.ts renamed to src/components-examples/material-experimental/column-resize/default-enabled-column-resize-flex/default-enabled-column-resize-flex-example.ts

@@ -7,7 +7,7 @@ import {MatChipsModule} from '@angular/material/chips';
 import {MatFormFieldModule} from '@angular/material/form-field';
 import {MatIconModule} from '@angular/material/icon';
 import {ChipsAutocompleteExample} from './chips-autocomplete/chips-autocomplete-example';
-import {ChipsDragDropExample} from './chips-drag-and-drop/chips-drag-drop-example';
+import {ChipsDragDropExample} from './chips-drag-drop/chips-drag-drop-example';
 import {ChipsInputExample} from './chips-input/chips-input-example';
 import {ChipsOverviewExample} from './chips-overview/chips-overview-example';
 import {ChipsStackedExample} from './chips-stacked/chips-stacked-example';

src/components-examples/material-experimental/column-resize/default-enabled/default-enabled-column-resize-example-module.ts renamed to src/components-examples/material-experimental/column-resize/default-enabled-column-resize/default-enabled-column-resize-example-module.ts

@@ -719,7 +719,7 @@ <h3>&lt;textarea&gt; with bindable autosize </h3>
   <mat-toolbar color="primary">Examples</mat-toolbar>
   <mat-card-content>
     <h4>Custom control</h4>
-    <form-field-custom-control-example></form-field-custom-control-example>
+    <mdc-form-field-custom-control-example></mdc-form-field-custom-control-example>
     <p>
       <mat-form-field appearance="outline">
         <mat-label>Phone number</mat-label>

src/components-examples/material-experimental/column-resize/default-enabled/default-enabled-column-resize-example.css renamed to src/components-examples/material-experimental/column-resize/default-enabled-column-resize/default-enabled-column-resize-example.css

@@ -1,17 +1,24 @@
 /**
  ******************************************************************************
  * DO NOT MANUALLY EDIT THIS FILE. THIS FILE IS AUTOMATICALLY GENERATED.
- ******************************************************************************/
+ ******************************************************************************
+ */
 
 export interface LiveExample {
   /** Title of the example. */
   title: string;
   /** Name of the example component. */
   componentName: string;
+  /** Selector to match the component of this example. */
+  selector: string;
+  /** Name of the primary file of this example. */
+  primaryFile: string;
+  /** List of files which are part of the example. */
+  files: string[];
+  /** Path to the directory containing the example. */
+  packagePath: string;
   /** List of additional components which are part of the example. */
   additionalComponents: string[];
-  /** List of additional files which are part of the example. */
-  additionalFiles: string[];
   /** NgModule that declares this example. */
   module: NgModuleInfo;
 }
@@ -27,4 +34,4 @@ export interface NgModuleInfo {
   importSpecifier: string;
 }
 
-export const EXAMPLE_COMPONENTS: {[key: string]: LiveExample} = ${exampleComponents};
+export const EXAMPLE_COMPONENTS: {[id: string]: LiveExample} = ${exampleComponents};

src/components-examples/material-experimental/column-resize/default-enabled/default-enabled-column-resize-example.html renamed to src/components-examples/material-experimental/column-resize/default-enabled-column-resize/default-enabled-column-resize-example.html

@@ -8,16 +8,18 @@ interface ExampleMetadata {
   componentName: string;
   /** Path to the source file that declares this example. */
   sourcePath: string;
-  /** Module import that can be used to load this example. */
-  importPath: string;
+  /** Path to the directory containing this example. */
+  packagePath: string;
+  /** Selector to match the component of this example. */
+  selector: string;
   /** Unique id for this example. */
   id: string;
   /** Title of the example. */
   title: string;
   /** Additional components for this example. */
   additionalComponents: string[];
-  /** Additional files for this example. */
-  additionalFiles: string[];
+  /** Files for this example. */
+  files: string[];
   /** Reference to the module that declares this example. */
   module: ExampleModule;
 }
@@ -37,11 +39,18 @@ interface AnalyzedExamples {
 function inlineExampleModuleTemplate(parsedData: AnalyzedExamples): string {
   const {exampleMetadata} = parsedData;
   const exampleComponents = exampleMetadata.reduce((result, data) => {
+    if (result[data.id] !== undefined) {
+      throw Error(`Multiple examples with the same id have been discovered: ${data.id}`);
+    }
+
     result[data.id] = {
+      packagePath: data.packagePath,
       title: data.title,
       componentName: data.componentName,
-      additionalFiles: data.additionalFiles,
+      files: data.files,
+      selector: data.selector,
       additionalComponents: data.additionalComponents,
+      primaryFile: path.basename(data.sourcePath),
       module: {
         name: data.module.name,
         importSpecifier: data.module.packagePath,
@@ -73,13 +82,14 @@ function analyzeExamples(sourceFiles: string[], baseDir: string): AnalyzedExampl
   for (const sourceFile of sourceFiles) {
     const relativePath = path.relative(baseDir, sourceFile).replace(/\\/g, '/');
     const importPath = relativePath.replace(/\.ts$/, '');
+    const packagePath = path.dirname(relativePath);
 
     // Collect all individual example modules.
     if (path.basename(sourceFile) === 'index.ts') {
       exampleModules.push(...parseExampleModuleFile(sourceFile).map(name => ({
         name,
         importPath,
-        packagePath: path.dirname(relativePath),
+        packagePath,
       })));
     }
 
@@ -96,25 +106,46 @@ function analyzeExamples(sourceFiles: string[], baseDir: string): AnalyzedExampl
       const exampleId = convertToDashCase(primaryComponent.componentName.replace('Example', ''));
       const example: ExampleMetadata = {
         sourcePath: relativePath,
+        packagePath,
         id: exampleId,
+        selector: primaryComponent.selector,
         componentName: primaryComponent.componentName,
         title: primaryComponent.title.trim(),
-        additionalFiles: [],
         additionalComponents: [],
+        files: [],
         module: null,
-        importPath,
       };
+
+      // For consistency, we expect the example component selector to match
+      // the id of the example.
+      const expectedSelector = `${exampleId}-example`;
+      if (primaryComponent.selector !== expectedSelector) {
+        throw Error(`Example ${exampleId} uses selector: ${primaryComponent.selector}, ` +
+            `but expected: ${expectedSelector}`);
+      }
+
+      example.files.push(path.basename(relativePath));
+      if (primaryComponent.templateUrl) {
+        example.files.push(primaryComponent.templateUrl);
+      }
+      if (primaryComponent.styleUrls) {
+        example.files.push(...primaryComponent.styleUrls);
+      }
+
       if (secondaryComponents.length) {
         for (const meta of secondaryComponents) {
           example.additionalComponents.push(meta.componentName);
           if (meta.templateUrl) {
-            example.additionalFiles.push(meta.templateUrl);
+            example.files.push(meta.templateUrl);
           }
           if (meta.styleUrls) {
-            example.additionalFiles.push(...meta.styleUrls);
+            example.files.push(...meta.styleUrls);
           }
         }
       }
+
+      // Ensure referenced files actually exist in the example.
+      example.files.forEach(f => assertReferencedExampleFileExists(baseDir, packagePath, f));
       exampleMetadata.push(example);
     } else {
         throw Error(`Could not find a primary example component in ${sourceFile}. ` +
@@ -132,12 +163,32 @@ function analyzeExamples(sourceFiles: string[], baseDir: string): AnalyzedExampl
       throw Error(`Could not determine example module for: ${example.id}`);
     }
 
+    const actualPath = path.dirname(example.sourcePath);
+    const expectedPath = path.posix.join(parentModule.packagePath, example.id);
+
+    // Ensures that example ids match with the directory they are stored in. This is not
+    // necessary for the docs site, but it helps with consistency and makes it easy to
+    // determine an id for an example. We also ensures for consistency that example
+    // folders are direct siblings of the module file.
+    if (actualPath !== expectedPath) {
+      throw Error(`Example is stored in: ${actualPath}, but expected: ${expectedPath}`);
+    }
+
     example.module = parentModule;
   });
 
   return {exampleMetadata};
 }
 
+/** Asserts that the given file exists for the specified example. */
+function assertReferencedExampleFileExists(baseDir: string, examplePackagePath: string,
+                                           relativePath: string) {
+  if (!fs.existsSync(path.join(baseDir, examplePackagePath, relativePath))) {
+    throw Error(
+        `Example "${examplePackagePath}" references "${relativePath}", but file does not exist.`);
+  }
+}
+
 /**
  * Generates the example module from the given source files and writes it to a specified output
  * file.

src/components-examples/material-experimental/column-resize/default-enabled/default-enabled-column-resize-example.ts renamed to src/components-examples/material-experimental/column-resize/default-enabled-column-resize/default-enabled-column-resize-example.ts

@@ -4,6 +4,7 @@ interface ParsedMetadata {
   isPrimary: boolean;
   componentName: string;
   title: string;
+  selector: string;
   templateUrl: string;
   styleUrls: string[];
 }