From fe0eb092c112e44de03809747c18bc5e30a5cf10 Mon Sep 17 00:00:00 2001 From: Ben Elan Date: Tue, 5 Nov 2024 16:34:12 -0800 Subject: [PATCH] docs(angular, vite): cleanup setup instructions for component examples (#10697) ## Summary Clean up the Angular and Vite component integration examples. --------- Co-authored-by: Kitty Hurley --- examples/components/angular/README.md | 53 ++++++++++++------- .../angular/src/app/app.component.spec.ts | 3 ++ .../angular/src/app/app.component.ts | 2 - examples/components/angular/src/main.ts | 3 ++ examples/components/vite/README.md | 6 ++- 5 files changed, 43 insertions(+), 24 deletions(-) diff --git a/examples/components/angular/README.md b/examples/components/angular/README.md index 9d7f0548bd6..704833f4b5c 100644 --- a/examples/components/angular/README.md +++ b/examples/components/angular/README.md @@ -2,8 +2,6 @@ [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/esri/calcite-design-system/tree/dev/examples/components/angular?file=README.md) -This examples use [`@esri/calcite-components-angular`](https://www.npmjs.com/package/@esri/calcite-components-angular), which provides Angular wrappers for Calcite components. - To install dependencies and start the server, run: ```sh @@ -13,55 +11,70 @@ npm start ## Developer info -To install `@esri/calcite-components-angular`, run: +To install `@esri/calcite-components`, run: ```sh -npm install @esri/calcite-components-angular +npm install @esri/calcite-components ``` -This package includes the compatible version of the main component library as a dependency, so no need to install `@esri/calcite-components` separately. - ### Setup components -The Angular wrapper components must use Calcite component's [distribution build](https://developers.arcgis.com/calcite-design-system/get-started/#distribution). First, define the components, specifying the path to the assets: +Import and call `setAssetPath`, which ensures translations, icons, and other required assets are available to Calcite components (more on copying assets below). ```ts // src/main.ts -import { defineCustomElements } from "@esri/calcite-components/dist/loader"; -defineCustomElements(window, { resourcesUrl: "./assets" }); +import { setAssetPath } from "@esri/calcite-components/dist/components"; + +setAssetPath(location.href); +``` + +Next, import the components used in your application: + +```ts +// src/app/app.component.ts +import "@esri/calcite-components/dist/components/calcite-button.js"; +import "@esri/calcite-components/dist/components/calcite-icon.js"; +import "@esri/calcite-components/dist/components/calcite-loader.js"; +import "@esri/calcite-components/dist/components/calcite-slider.js"; +``` + +Then, import the global Calcite components stylesheet (only do this once): + +```css +/* src/styles.css */ +@import "@esri/calcite-components/dist/calcite/calcite.css"; ``` -To use Calcite components, add `CalciteComponentsModule` to the `imports`: +To use Calcite components in Angular, you **must** add CUSTOM_ELEMENTS_SCHEMA to the `schemas` property: ```ts // src/app/app.component.ts import { CommonModule } from '@angular/common'; +import { + CUSTOM_ELEMENTS_SCHEMA, + Component, + OnDestroy, + OnInit, +} from '@angular/core'; import { RouterOutlet } from '@angular/router'; -import { CalciteComponentsModule } from '@esri/calcite-components-angular'; @Component({ selector: 'app-root', standalone: true, + imports: [CommonModule, RouterOutlet], templateUrl: './app.component.html', - imports: [CommonModule, CalciteComponentsModule, RouterOutlet], styleUrls: ['./app.component.css'], + schemas: [CUSTOM_ELEMENTS_SCHEMA], }) ``` Calcite components can now be used in your application like any other Angular component! ```html - + ``` -Lastly, import the global Calcite components stylesheet (only do this once): - -```css -/* src/styles.css */ -@import "@esri/calcite-components/dist/calcite/calcite.css"; -``` - ### Copy the assets Calcite components' assets need to be copied to the `./public` directory when [using assets](https://developers.arcgis.com/calcite-design-system/get-started/#load-the-assets) locally. This example has a `copy` npm script, which will automatically run after installing dependencies. For example: diff --git a/examples/components/angular/src/app/app.component.spec.ts b/examples/components/angular/src/app/app.component.spec.ts index 67ac9fce4c5..13df0f2a776 100644 --- a/examples/components/angular/src/app/app.component.spec.ts +++ b/examples/components/angular/src/app/app.component.spec.ts @@ -4,6 +4,7 @@ import { ComponentFixtureAutoDetect, TestBed, } from '@angular/core/testing'; +import { setAssetPath } from '@esri/calcite-components/dist/components'; import { AppComponent } from './app.component'; let app: AppComponent; @@ -19,6 +20,8 @@ describe('AppComponent', () => { fixture = TestBed.createComponent(AppComponent); app = fixture.componentInstance; + + setAssetPath(window.location.href); }); it('should create the app', () => { diff --git a/examples/components/angular/src/app/app.component.ts b/examples/components/angular/src/app/app.component.ts index 08a36cf6b51..ff86ad24572 100644 --- a/examples/components/angular/src/app/app.component.ts +++ b/examples/components/angular/src/app/app.component.ts @@ -6,7 +6,6 @@ import { OnInit, } from '@angular/core'; import { RouterOutlet } from '@angular/router'; -import { setAssetPath } from '@esri/calcite-components/dist/components'; import '@esri/calcite-components/dist/components/calcite-button.js'; import '@esri/calcite-components/dist/components/calcite-icon.js'; import '@esri/calcite-components/dist/components/calcite-loader.js'; @@ -28,7 +27,6 @@ export class AppComponent implements OnInit, OnDestroy { ngOnInit() { this.fetch(); - setAssetPath(window.location.href); } ngOnDestroy(): void { diff --git a/examples/components/angular/src/main.ts b/examples/components/angular/src/main.ts index f3a7223da6d..3633a8a73a1 100644 --- a/examples/components/angular/src/main.ts +++ b/examples/components/angular/src/main.ts @@ -1,6 +1,9 @@ import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app/app.component'; import { appConfig } from './app/app.config'; +import { setAssetPath } from '@esri/calcite-components/dist/components'; + +setAssetPath(window.location.href); bootstrapApplication(AppComponent, appConfig).catch((err) => console.error(err), diff --git a/examples/components/vite/README.md b/examples/components/vite/README.md index 128463c9d63..f65dba152b7 100644 --- a/examples/components/vite/README.md +++ b/examples/components/vite/README.md @@ -22,7 +22,7 @@ npm install @esri/calcite-components Import and call `setAssetPath`, which ensures translations, icons, and other required assets are available to Calcite components (more on copying assets below). ```js -// src/main.ts +// main.ts import { setAssetPath } from "@esri/calcite-components/dist/components"; setAssetPath(location.href); @@ -31,15 +31,17 @@ setAssetPath(location.href); Next, import the components used in your application: ```js -// src/components/HelloWorld.vue +// main.ts import "@esri/calcite-components/dist/components/calcite-button"; import "@esri/calcite-components/dist/components/calcite-icon"; import "@esri/calcite-components/dist/components/calcite-date-picker"; +import "@esri/calcite-components/dist/components/calcite-loader"; ``` Lastly, import the global Calcite components stylesheet (only do this once): ```js +// main.ts import "@esri/calcite-components/dist/calcite/calcite.css"; ```