@ni/nimble-angular 1.0.0-beta.96 → 1.0.0

package/README.md

@@ -6,43 +6,109 @@
 
 [![NPM Version](https://img.shields.io/npm/v/@ni/nimble-angular.svg)](https://www.npmjs.com/package/@ni/nimble-angular)
 
-NI-styled UI components for Angular applications
+NI-styled UI components for [Angular](https://angular.io) applications
 
 ## Getting started
 
-You are currently required to set `"buildOptimizer": "false"` in `angular.json`. See [#18](https://github.com/ni/nimble/issues/18) for more info.
+The steps to use components from Nimble Angular are similar to using components from any other Angular library. You can see the [Example Client App](/angular-workspace/projects/example-client-app) project for an example.
 
-### Using Nimble form controls
+1. Install Nimble Angular from the [public NPM registry](https://www.npmjs.com/package/@ni/nimble-angular) by running `npm install @ni/nimble-angular`.
 
-For best results, always use `ngModel`, `formControl`, or `formControlName` bindings when integrating Nimble form controls in Angular. Binding to the control's native value property or event (e.g. `[value]` or `(change)`) is not supported, and can cause build failures and other issues. If a value change event is necessary, use `ngModel (ngModelChange)="onChange()"`.
+    *This guide assumes you have an existing Angular application and are using NPM 7 or greater.*
 
-## Contributing
+2. Each application should update `app.module.ts` to import the module for `NimbleThemeProviderModule`. Additionally, import modules for the components you want to use:
+
+    ```ts
+    import {
+        NimbleDrawerModule,
+        NimbleThemeProviderModule
+    } from '@ni/nimble-angular';
+
+    @NgModule ({
+        imports: [
+            NimbleDrawerModule,
+            NimbleThemeProviderModule
+        ]
+    })
+    class AppModule {}
+    ```
+
+3. Each application should add the `<nimble-theme-provider>` element to `app.component.html` and set its `theme` attribute. The theme provider has no appearance of its own but defines tokens that are used by descendant components.
 
-Follow the instructions in [CONTRIBUTING.md](CONTRIBUTING.md) to modify this library.
+    ```html
+    <nimble-theme-provider theme="light">
+        <router-outlet></router-outlet>
+    </nimble-theme-provider>
+    ```
 
-<!--
-# NimbleAngular
+4. Each application should import the Nimble fonts once in the root `src/styles.scss`. Nimble recommends using SCSS for capabilities such as build time property checking.
 
-This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 12.1.0.
+    ```scss
+    @import '~@ni/nimble-angular/styles/fonts';
+    ```
 
-## Code scaffolding
+5. As needed, import the theme-aware design tokens in each SCSS file that will leverage the tokens for other parts of your application (for colors, fonts, etc).
 
-Run `ng generate component component-name --project nimble-angular` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project nimble-angular`.
-> Note: Don't forget to add `--project nimble-angular` or else it will be added to the default project in your `angular.json` file. 
+    ```scss
+    @import '~@ni/nimble-angular/styles/tokens';
 
-## Build
+    .my-element {
+        font-family: $ni-nimble-font-family
+    }
+    ```
 
-Run `ng build nimble-angular` to build the project. The build artifacts will be stored in the `dist/` directory.
+    See [the theming documentation in `nimble-components`](/packages/nimble-components/README.md#theming) for more information.
 
-## Publishing
+6. As needed, add Nimble components to the templates in your application:
 
-After building your library with `ng build nimble-angular`, go to the dist folder `cd dist/nimble-angular` and run `npm publish`.
+    ```html
+    <nimble-drawer #drawerReference location="right">This is a drawer</nimble-drawer>
+    ```
 
-## Running unit tests
+7. As needed, import the Nimble component's directive and types in your component scripts to use programmatic APIs:
 
-Run `ng test nimble-angular` to execute the unit tests via [Karma](https://karma-runner.github.io).
+    ```ts
+    import { NimbleDrawerDirective } from '@ni/nimble-angular';
 
-## Further help
+    @Component({ /* ... */ })
+    class AppComponent {
+        @ViewChild('drawerReference', { read: NimbleDrawerDirective }) public drawer: NimbleDrawerDirective;
+
+        public openDrawer() {
+            this.drawer.show();
+        }
+    }
+    ```
+
+   Note: Nimble components are exposed in Angular as Angular Directives and have the suffix `Directive`.
+
+### Learn more
+
+See the [README.md for the ni/nimble repository](/README.md) for documentation of individual components.
+
+### Using Nimble form controls
+
+For best results, always use `ngModel`, `formControl`, or `formControlName` bindings when integrating Nimble form controls in Angular. Binding to the control's native value property or event (e.g. `[value]` or `(change)`) is not supported, and can cause build failures and other issues. If a value change event is necessary, use `ngModel (ngModelChange)="onChange()"`.
+
+### Testing with Nimble elements and `fakeAsync`
+
+Angular's `fakeAsync` utility is useful for writing quickly-executing tests, but it can cause issues when testing components containing Nimble elements. Nimble uses an internal process queue to schedule work. If a `fakeAsync` test schedules work on the queue (by creating or interacting with Nimble elements) and the queue isn't processed by the end of the test, the queue will never be processed and subsequent tests may fail.
+
+To avoid this, call `processUpdates()` after each `fakeAsync` test. This will synchronously process the internal queue and put it in a good state for subsequent tests. The `processUpdates()` method can also be called mid-test to synchronously complete operations which would otherwise require waiting for an animation frame.
+
+## Known Issues
+
+Currently the fast-animation library we depend on only exports CommonJS modules, which triggers an Angular project build warning (and potentially suboptimal bundle optimizations).
+
+Currently clients consuming the nimble Angular integration may need to make the following change in their `angular.json`, if they wish to suppress that build warning, in the `projects.[projectName].architect.build.options` section:
+```json
+"allowedCommonJsDependencies": [
+  "@microsoft/fast-animation"
+]
+```
+
+[nimble issue #189](https://github.com/ni/nimble/issues/189) tracks this issue.
+
+## Contributing
 
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.
--->
+Follow the instructions in [CONTRIBUTING.md](/angular-workspace/projects/ni/nimble-angular/CONTRIBUTING.md) to modify this library.