auro-docsite: Include Angular setup example

bdahl1 commented 1 year ago

Is your feature request related to a problem? Please describe.

I would like the docsite to include instructions for setting up Auro to play nicely with Angular

Describe the solution you'd like

I would like an example project similar to the react/svelt/javascript one provided. Or at least the secret sauce for getting Web Components working with Angular to be linked from the documentation

Describe alternatives you've considered

Whining a bunch.

Additional context

I am putting this documentation together myself and will happily link it or copy/paste it here when it's done.

bdahl1 commented 1 year ago

I documented the Angular steps for JetStream here: https://github.com/Alaska-ITS/alaska-component-angular/blob/main/src/stories/GettingStarted.stories.mdx

The steps for Auro are the exact same, save the very bottom where we are talking about specific components, of course

blackfalcon commented 1 year ago

@blackfalcon to schedule meeting with @bdahl1 to go over specifics, I know things have changed since this issue was submitted and need to refresh thoughts.

bdahl1 commented 1 year ago

Here's my proposal:

I think the main auro.alaskaair.com site should have the following Angular setup instructions placed in it, probably in its own page under the React one. These goofy steps are required to make Angular play nicely with Auro (or any other custom element library). Some extra bits on the end to actually npm install an example auro component would be nice just to bring the whole thing home.

Configure web components polyfill

We need to do a bit of work to get Web Components working properly in Angular. We rely on the webcomponentjs project for that functionality, but it does require some finicky setup to get playing nicely in Angular. Follow the instructions below carefully.

Enable CUSTOM_ELEMENTS_SCHEMA

In your app.module.ts import CUSTOM_ELEMENTS_SCHEMA from @angular/core and add it to the schemas array. This will make it so Angular can handle general web components.

import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';

/* ...snip... */

@NgModule({
  declarations: [...],
  imports: [...],
  providers: [...],
  bootstrap: [...],
  schemas: [ CUSTOM_ELEMENTS_SCHEMA ] // add this line
})
export class AppModule { }

Install the Webcomponentsjs Dependency

npm install @webcomponents/webcomponentsjs --save

Configure build

In angular.json, under projects.yourproject.architect.build.options.assets add the webcomponent assets

{
  /* ...snip... */
  "architect": {
    "build": {
      "builder": "@angular-devkit/build-angular:browser",
      "options": {
        /* ...snip... */
        "assets": [
          "src/favicon.ico",
          "src/assets",
          /* Add this block */
          {
            "glob": "**/*.js",
            "input": "node_modules/@webcomponents/webcomponentsjs",
            "output": "webcomponents/"
          }
        ],
      },
    }
  }
}

Add the web component loader

In index.html:

<head>
  <!-- ...other head elements... -->
  <script src="webcomponents/webcomponents-loader.js" defer></script>
</head>

Add the WebComponentsReady event listener

In main.ts, right after the imports

/* import statements */

window.addEventListener('WebComponentsReady', () => {
  return import('./webcomponents');
});

note: Your compiler will probably complain until you actually add a web component in a later step.

Add an empty webcomponents file

In the src directory add an empty webcomponents.ts file. We'll need that later.

Install your components

TODO

Add the new components to webcomponents.ts

In webcomponents.ts:

import "@alaska-its/alaska-button";
/* Every component needs to be added here */

bdahl1 commented 2 days ago

@jason-capsule42 did this documentation get added somewhere?

jason-capsule42 commented 1 day ago

I'm going to go ahead and re-open this one and flag it in the DocSite milestone to make sure the proposed example in the comments in considered when we regenerate the framework implementation solutions.

bdahl1 commented 1 day ago

I have ported these instructions into the dev wiki in case the decision is made not to include framework specific documentation: https://wiki.devtools.teamaag.com/en/guides/auro/angular-auro-integration

AlaskaAirlines / AuroDocsSite