refactor: update stackblitz examples write to use webcontainers for v13 compatibility

Updates to the Stackblitz example writer:

* Simplifies opening mechanism by relying on the small/tree-shakable
  `@stackblitz/sdk` package instead of manually constructing the form.

* Updates the template files to reflect the files generated by a new
  CLI project generated with CLI v13.rc.

* Updates the StackBlitz base template from Angular to `node` which is
  bringing in the new WebContainer feature from StackBlitz. We need to
  use this as v13 packages are currently not supported by StackBlitz due
  to the APF v13 changes. Also WebContainer is recommended to be used in
  our case due to the complexities involed in running/replicating the
  CLI, while WebContainers could simply run them. -> with the benfit of
  users being able to experience Angular directly in the browser, as
  they would locally.

  * One downside is that the Stackblitz examples will not work in Safari and
    Firefox yet. Stackblitz prints a good message explaining why. For
    testing reproductions, the team needs to just download the zipped
    project and run it locally. This is another benefit of using the CLI
    directly in a WebContainer. It's a small trade-off for being able to
    actually rely on the CLI fully (mitigating potential cache issues
    like we have faced before).

* Removes the second boilerplate/template for running test harness
  examples. These will run as part of the same CLI boilerplate (allowing
  us to reduce the burden of maintaining a second boilerplate).

  * This also required some logic for selectively populating a
    `${startCommand}` placeholder so that either `yarn test` or `yarn
    start` is executed in the StackBlitz VM.

Author: devversion

.firebaserc

@@ -19,7 +19,6 @@
     "build:sm": "ng build --configuration production --source-map",
     "prod-build": "ng build --configuration production",
     "preinstall": "node ./tools/npm/check-npm.js",
-    "postinstall": "ngcc --properties es2015 browser module main --first-only --create-ivy-entry-points",
     "publish-prod": "bash ./tools/deploy.sh stable prod",
     "publish-dev": "bash ./tools/deploy.sh",
     "publish-beta": "bash ./tools/deploy.sh stable beta",
@@ -52,6 +51,7 @@
     "@angular/platform-browser-dynamic": "13.0.0-next.15",
     "@angular/router": "13.0.0-next.15",
     "@angular/youtube-player": "^13.0.0-rc.2",
+    "@stackblitz/sdk": "^1.5.2",
     "material-components-web": "13.0.0-canary.0a9069300.0",
     "moment": "^2.29.1",
     "rxjs": "^6.6.7",

package.json

@@ -11,35 +11,39 @@ import {StackBlitzWriter} from './stack-blitz-writer';
 })
 export class StackBlitzButton {
   /**
-   * The button becomes disabled if the user hovers over the button before the StackBlitz form
-   * is created. After the form is created, the button becomes enabled again.
-   * The form creation usually happens extremely quickly, but we handle the case of the
+   * The button becomes disabled if the user hovers over the button before the StackBlitz
+   * is ready for opening. After the StackBlitz is ready, the button becomes enabled again.
+   *
+   * The StackBlitz preparation usually happens extremely quickly, but we handle the case of the
    * StackBlitz not yet being ready for people with poor network connections or slow devices.
    */
   isDisabled = false;
+
   exampleData: ExampleData | undefined;
 
   /**
-   * Form used to submit the data to Stackblitz.
-   * Important! it needs to be constructed ahead-of-time, because doing so on-demand
-   * will cause Firefox to block the submit as a popup, because it didn't happen within
-   * the same tick as the user interaction.
+   * Function that can be invoked to open the StackBlitz window synchronously.
+   *
+   * **Note**: All files for the StackBlitz need to be loaded and prepared ahead-of-time,
+   * because doing so on-demand will cause Firefox to block the submit as a popup as the
+   * form submission (used internally to create the StackBlitz) didn't happen within the
+   * same tick as the user interaction.
    */
-  private _stackBlitzForm: HTMLFormElement | undefined;
+  private _openStackBlitzFn: (() => void) | null = null;
 
   @HostListener('mouseover')
   onMouseOver() {
-    this.isDisabled = !this._stackBlitzForm;
+    this.isDisabled = this._openStackBlitzFn === null;
   }
 
   @Input()
   set example(example: string | undefined) {
     if (example) {
       const isTest = example.includes('harness');
       this.exampleData = new ExampleData(example);
-      this.stackBlitzWriter.constructStackBlitzForm(example, this.exampleData, isTest)
-        .then(form => {
-          this._stackBlitzForm = form;
+      this.stackBlitzWriter.createStackBlitzForExample(example, this.exampleData, isTest)
+        .then(openFn => {
+          this._openStackBlitzFn = openFn;
           this.isDisabled = false;
         });
     } else {
@@ -49,16 +53,8 @@ export class StackBlitzButton {
 
   constructor(private stackBlitzWriter: StackBlitzWriter) {}
 
-  openStackBlitz(): void {
-    // When the form is submitted, it must be in the document body. The standard of forms is not
-    // to submit if it is detached from the document. See the following chromium commit for
-    // more details:
-    // https://chromium.googlesource.com/chromium/src/+/962c2a22ddc474255c776aefc7abeba00edc7470%5E!
-    if (this._stackBlitzForm) {
-      document.body.appendChild(this._stackBlitzForm);
-      this._stackBlitzForm.submit();
-      document.body.removeChild(this._stackBlitzForm);
-    }
+  async openStackBlitz(): Promise<void> {
+    this._openStackBlitzFn?.();
   }
 }
 

src/app/shared/stack-blitz/stack-blitz-button.ts

@@ -1,9 +1,26 @@
 import {HttpClientTestingModule, HttpTestingController} from '@angular/common/http/testing';
 import {waitForAsync, fakeAsync, flushMicrotasks, inject, TestBed} from '@angular/core/testing';
 import {EXAMPLE_COMPONENTS, ExampleData, LiveExample} from '@angular/components-examples';
-import {StackBlitzWriter} from './stack-blitz-writer';
+import {StackBlitzWriter, TEMPLATE_FILES} from './stack-blitz-writer';
+import stackblitz from '@stackblitz/sdk';
 
 const testExampleId = 'my-test-example-id';
+const testExampleBasePath = `/docs-content/examples-source/cdk/my-comp/${testExampleId}`;
+
+const FAKE_DOCS: {[key: string]: string} = {
+  '/assets/stack-blitz/src/index.html': '<material-docs-example></material-docs-example>',
+  '/assets/stack-blitz/src/app/app.module.ts':
+      `import {MaterialDocsExample} from './material-docs-example';`,
+  [`${testExampleBasePath}/test.ts`]: 'ExampleComponent',
+  [`${testExampleBasePath}/test.html`]: `<example></example>`,
+  [`${testExampleBasePath}/src/detail.ts`]: 'DetailComponent',
+};
+
+const TEST_URLS = TEMPLATE_FILES.map(filePath => `/assets/stack-blitz/${filePath}`).concat([
+  `${testExampleBasePath}/test.ts`,
+  `${testExampleBasePath}/test.html`,
+  `${testExampleBasePath}/src/detail.ts`,
+]);
 
 describe('StackBlitzWriter', () => {
   let stackBlitzWriter: StackBlitzWriter;
@@ -27,7 +44,8 @@ describe('StackBlitzWriter', () => {
   beforeEach(() => {
     stackBlitzWriter = TestBed.inject(StackBlitzWriter);
     data = new ExampleData('');
-    data.componentNames = [];
+    data.selectorName = 'this-is-the-comp-name';
+    data.componentNames = ['ExampleComponent', 'AdditionalComp'];
     data.exampleFiles = ['test.ts', 'test.html', 'src/detail.ts'];
     data.indexFilename = data.exampleFiles[0];
 
@@ -40,94 +58,70 @@ describe('StackBlitzWriter', () => {
     delete EXAMPLE_COMPONENTS[testExampleId];
   });
 
+  function fakeExternalFileRequests() {
+    for (const url of TEST_URLS) {
+      http.expectOne(url).flush(FAKE_DOCS[url] || 'fake');
+    }
+  }
+
   it('should append correct copyright', () => {
     const year = new Date().getFullYear();
     expect(stackBlitzWriter._appendCopyright('test.ts', 'NoContent')).toBe(`NoContent
 
 /**  Copyright ${year} Google LLC. All Rights Reserved.
     Use of this source code is governed by an MIT-style license that
-    can be found in the LICENSE file at http://angular.io/license */`);
+    can be found in the LICENSE file at https://angular.io/license */`);
 
     expect(stackBlitzWriter._appendCopyright('test.html', 'NoContent')).toBe(`NoContent
 
 <!-- Copyright ${year} Google LLC. All Rights Reserved.
     Use of this source code is governed by an MIT-style license that
-    can be found in the LICENSE file at http://angular.io/license -->`);
+    can be found in the LICENSE file at https://angular.io/license -->`);
 
   });
 
-  it('should create form element', () => {
-    expect(stackBlitzWriter._createFormElement('index.ts').outerHTML).toBe(
-      `<form action="https://run.stackblitz.com/api/angular/v1?file=index.ts" ` +
-      `method="post" target="_blank"></form>`);
-  });
+  it('should set tags for example stackblitz', fakeAsync(() => {
+    const openProjectSpy = spyOn(stackblitz, 'openProject');
 
-  it('should add files to form input', () => {
-    const form = stackBlitzWriter._createFormElement('index.ts');
+    stackBlitzWriter
+      .createStackBlitzForExample(testExampleId, data, false)
+      .then(openBlitzFn => openBlitzFn());
 
-    stackBlitzWriter._addFileToForm(form, data, 'NoContent', 'test.ts', 'path/to/file', false);
-    stackBlitzWriter._addFileToForm(form, data, 'Test', 'test.html', 'path/to/file', false);
-    stackBlitzWriter._addFileToForm(form, data, 'Detail', 'src/detail.ts', 'path/to/file', false);
+    flushMicrotasks();
+    fakeExternalFileRequests();
+    flushMicrotasks();
 
-    expect(form.elements.length).toBe(3);
-    expect(form.elements[0].getAttribute('name')).toBe('files[src/app/test.ts]');
-    expect(form.elements[1].getAttribute('name')).toBe('files[src/app/test.html]');
-    expect(form.elements[2].getAttribute('name')).toBe('files[src/app/src/detail.ts]');
-  });
+    expect(openProjectSpy).toHaveBeenCalledTimes(1);
+    expect(openProjectSpy).toHaveBeenCalledWith(jasmine.objectContaining(
+        {tags: ['angular', 'material', 'cdk', 'web', 'example']}), jasmine.anything());
+  }));
+
+  it('should read and transform template files properly', fakeAsync(() => {
+    const openProjectSpy = spyOn(stackblitz, 'openProject');
 
-  it('should open a new window with stackblitz url', fakeAsync(() => {
-    let form: HTMLFormElement;
-    stackBlitzWriter.constructStackBlitzForm(testExampleId, data, false).then(result => {
-      form = result;
-      flushMicrotasks();
-
-      for (const url of TEST_URLS) {
-        http.expectOne(url).flush(FAKE_DOCS[url] || '');
-      }
-      flushMicrotasks();
-
-      expect(form.elements.length).toBe(14);
-
-      // Should have correct tags
-      expect(form.elements[0].getAttribute('name')).toBe('tags[0]');
-      expect(form.elements[0].getAttribute('value')).toBe('angular');
-      expect(form.elements[1].getAttribute('name')).toBe('tags[1]');
-      expect(form.elements[1].getAttribute('value')).toBe('material');
-      expect(form.elements[2].getAttribute('name')).toBe('tags[2]');
-      expect(form.elements[2].getAttribute('value')).toBe('example');
-
-      // Should bet set as private and have description and dependencies.
-      expect(form.elements[3].getAttribute('name')).toBe('private');
-      expect(form.elements[3].getAttribute('value')).toBe('true');
-      expect(form.elements[4].getAttribute('name')).toBe('description');
-      expect(form.elements[5].getAttribute('name')).toBe('dependencies');
-
-      // Should have files needed for example.
-      expect(form.elements[6].getAttribute('name')).toBe('files[src/index.html]');
-      expect(form.elements[7].getAttribute('name')).toBe('files[src/styles.scss]');
-      expect(form.elements[8].getAttribute('name')).toBe('files[src/polyfills.ts]');
-      expect(form.elements[9].getAttribute('name')).toBe('files[src/main.ts]');
-      expect(form.elements[10].getAttribute('name')).toBe('files[src/app/material-module.ts]');
-      expect(form.elements[11].getAttribute('name')).toBe('files[src/app/test.ts]');
-      expect(form.elements[12].getAttribute('name')).toBe('files[src/app/test.html]');
-      expect(form.elements[13].getAttribute('name')).toBe('files[src/app/src/detail.ts]');
+    stackBlitzWriter
+      .createStackBlitzForExample(testExampleId, data, false)
+      .then(openBlitzFn => openBlitzFn());
+
+    flushMicrotasks();
+    fakeExternalFileRequests();
+    flushMicrotasks();
+
+    const expectedFiles = jasmine.objectContaining({
+      'angular.json': 'fake',
+      'src/main.ts': 'fake',
+      'src/test.ts': 'fake',
+      'src/index.html': `<this-is-the-comp-name></this-is-the-comp-name>`,
+      'src/app/app.module.ts': `import {ExampleComponent, AdditionalComp} from './test';`,
+      'src/app/test.ts': `ExampleComponent
+
+/**  Copyright 2021 Google LLC. All Rights Reserved.
+    Use of this source code is governed by an MIT-style license that
+    can be found in the LICENSE file at https://angular.io/license */`,
     });
+
+    expect(openProjectSpy).toHaveBeenCalledTimes(1);
+    expect(openProjectSpy).toHaveBeenCalledWith(
+        jasmine.objectContaining({files: expectedFiles}), {openFile: 'src/app/test.ts'});
   }));
 });
-
-const FAKE_DOCS: {[key: string]: string} = {
-  '/docs-content/examples-source/test.ts': 'ExampleComponent',
-  '/docs-content/examples-source/test.html': `<example></example>`,
-  '/docs-content/examples-source/src/detail.ts': 'DetailComponent',
-};
-
-const TEST_URLS = [
-  '/assets/stack-blitz/src/index.html',
-  '/assets/stack-blitz/src/styles.scss',
-  '/assets/stack-blitz/src/polyfills.ts',
-  '/assets/stack-blitz/src/main.ts',
-  '/assets/stack-blitz/src/app/material-module.ts',
-  `/docs-content/examples-source/cdk/my-comp/${testExampleId}/test.ts`,
-  `/docs-content/examples-source/cdk/my-comp/${testExampleId}/test.html`,
-  `/docs-content/examples-source/cdk/my-comp/${testExampleId}/src/detail.ts`,
-];