@ni/nimble-angular 1.0.0-beta.13 → 1.0.0-beta.130

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-    <p align="center"><b>ni | nimble | angular</b></p>
+    <p><b>ni | nimble | angular</b></p>
 </div>
 
 # Nimble Angular
@@ -8,37 +8,63 @@
 
 NI-styled UI components for Angular applications
 
-## Getting Started
+## 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.
+*This guide assumes you have an existing Angular application and are using NPM 7 or greater.*
 
-## Contributing
+1. Install Nimble Angular from the [public NPM registry](https://www.npmjs.com/package/@ni/nimble-angular) by running `npm install @ni/nimble-angular`.
+2. 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.
+   1. Update your `app.module.ts` to import the module for each component you want to use:
+        ```ts
+        import { NimbleDrawerModule } from '@ni/nimble-angular';
 
-Follow the instructions in [CONTRIBUTING.md](CONTRIBUTING.md) to modify this library.
+        @NgModule ({
+            imports: [
+                NimbleDrawerModule,
+            ]
+        })
+        class AppModule {}
+        ```
+   2. Add the component to your `app.component.html` (or to the template for another component in your application):
+        ```html
+        <nimble-drawer #drawerReference [location]="location">This is a drawer</nimble-drawer>
+        ```
+   3. If needed, import the Nimble component's directive and types in `app.component.ts` (or the TypeScript file backing another component) to use its programmatic API: 
+        ```ts
+        import { DrawerLocation, NimbleDrawerDirective } from '@ni/nimble-angular';
 
-<!--
-# NimbleAngular
+        @Component({ /* ... */ })
+        class AppComponent {
+            @Input() public location: DrawerLocation = DrawerLocation.Right;
+            @ViewChild('drawerReference', { read: NimbleDrawerDirective }) public drawer: NimbleDrawerDirective;
 
-This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 12.1.0.
+            public openDrawer() {
+                this.drawer.show();
+            }
+        }
+        ```
 
-## Code scaffolding
+### Learn more
 
-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. 
+See the [README.md for the ni/nimble repository](/README.md) for documentation of individual components.
 
-## Build
+### Using Nimble form controls
 
-Run `ng build nimble-angular` to build the project. The build artifacts will be stored in the `dist/` directory.
+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()"`.
 
-## Publishing
+## Known Issues
 
-After building your library with `ng build nimble-angular`, go to the dist folder `cd dist/nimble-angular` and run `npm publish`.
+Currently the fast-animation library we depend on only exports CommonJS modules, which triggers an Angular project build warning (and potentially suboptimal bundle optimizations).
 
-## Running unit tests
+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"
+]
+```
 
-Run `ng test nimble-angular` to execute the unit tests via [Karma](https://karma-runner.github.io).
+[nimble issue #189](https://github.com/ni/nimble/issues/189) tracks this issue.
 
-## Further help
+## 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.