Deprecate classes and styles inputs in all components

Fixes #373

Author: devoto13

UPGRADING.md

@@ -15,3 +15,4 @@ You might also be interested in the larger umbrella project [upgrade guide](http
 * [0.4.0 to 0.5.0](docs/upgrading/0.4.0-0.5.0.md)
 * [0.5.0 to 0.6.0](docs/upgrading/0.5.0-0.6.0.md)
 * [0.9.0 to 0.10.0](docs/upgrading/0.9.0-0.10.0.md)
+* [0.11.0 to 0.12.0](docs/upgrading/0.11.0-0.12.0.md)

docs/guide/styling-icon-internals.md

@@ -0,0 +1,44 @@
+# Styling icon internals
+
+**DISCLAIMER:** Styling icon internals is not recommended as it relies on the component's implementation details and may silently break after any library update.
+
+For the majority of the cases, styling the icon with regular `style` and `class` properties as shown in [Custom styles](../usage/features.md#custom-styles) should be used. However, sometimes one has to attach style to one of the internal elements of the component. To achieve this, one would need to overcome the Angular [view encapsulation](https://angular.io/guide/view-encapsulation). This guide explains how to do that.
+
+## Use global styles
+
+As global styles are not subject to the view encapsulation, one can add styles for the `fa-icon` internals to the global `styles.css` and use it everywhere in the application.
+
+```css
+/* styles.css */
+fa-icon.fancy svg path {
+  fill: #ffffff;
+  stroke: #ff0000;
+  stroke-width: 10;
+}
+```
+
+```angular2html
+<!-- app.component.html -->
+<fa-icon icon="user" class="fancy"></fa-icon>
+```
+
+## Use `::ng-deep` pseudo-class selector
+
+Another options is to use `:ng-deep` pseudo-class selector. This has the benefit that styles are local to the component and won't accidentally affect `fa-icon` usage in other components of the application.
+
+```ts
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  template: '<fa-icon icon="user" class="fancy"></fa-icon>',
+  styles: [`
+    fa-icon.fancy ::ng-deep svg path {
+      fill: #ffffff;
+      stroke: #ff0000;
+      stroke-width: 10;
+    }
+  `],
+})
+export class AppComponent {}
+```

docs/upgrading/0.11.0-0.12.0.md

@@ -0,0 +1,5 @@
+# Upgrading 0.11.0 to 0.12.0
+
+## Remove usage of the deprecated `styles` and `classes` inputs
+
+`styles` and `classes` inputs in all components are deprecated for removal in the next release. These inputs don't work the way one would expect and cause a lot of confusion. For majority of the cases, one should use regular [class and style bindings](https://angular.io/guide/class-binding) provided by Angular. For those rare cases, when it is not enough, there is a guide on how one can style component's internal elements at their own risk - [Styling icon internals](https://github.com/FortAwesome/angular-fontawesome/blob/master/docs/guide/styling-icon-internals.md).

docs/usage.md

@@ -26,8 +26,7 @@ Utilize core FontAwesome features
 * [Animations](./usage/features.md#animations)
 * [Border](./usage/features.md#border)
 * [Pull](./usage/features.md#pull)
-* [Custom Classes](./usage/features.md#custom-classes)
-* [Default Style](./usage/features.md#default-style)
+* [Custom styles](./usage/features.md#custom-styles)
 
 ## Features specific for Duotone icons
 Additional features available for Duotone icons
@@ -51,8 +50,9 @@ Take your icons to the next level with these advanced features.
 * [Programmatic API](./usage/features.md#programmatic-api)
 
 ## Guides
-Guides cover specific topics or use cases.
+Guides on specific topics or use cases.
 
 * [Testing](./guide/testing.md)
 * [Storybook](./guide/storybook.md)
 * [Advanced uses](./guide/advanced-uses.md)
+* [Styling icon internals](./guide/styling-icon-internals.md)

docs/usage/features.md

@@ -60,17 +60,22 @@ The following features are available as part of Font Awesome. Note that the synt
 <fa-icon [icon]="['fas', 'coffee']" pull="right"></fa-icon>
 ```
 
-### Custom Classes
+### Custom styles
 
-```html
-<fa-icon [icon]="['fas', 'coffee']" [classes]="['my-icon-class']"></fa-icon>
+Simple styles can be applied using usual [class and style bindings](https://angular.io/guide/class-binding):
+
+```css
+.red-icon {
+  color: red;
+}
 ```
 
-### Default Style
 ```html
-<fa-icon [icon]="['fas', 'coffee']" [styles]="{'stroke': 'red', 'color': 'red'}"></fa-icon>
+<fa-icon [icon]="['fas', 'coffee']" class="red-icon" [style]="{display: 'inline-block', padding: '5px'}"></fa-icon>
 ```
 
+For more advanced styling, see [Styling icon internals](../guide/styling-icon-internals.md).
+
 ## Duotone icons
 
 ### Basic use

src/lib/icon/icon.component.ts

@@ -2,7 +2,6 @@ import { Component, HostBinding, Input, OnChanges, Optional, SimpleChanges } fro
 import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
 import {
   FaSymbol,
-  findIconDefinition,
   FlipProp,
   icon,
   IconDefinition,
@@ -38,13 +37,23 @@ export class FaIconComponent implements OnChanges {
 
   /**
    * Specify a title for the icon.
+   *
    * This text will be displayed in a tooltip on hover and presented to the
    * screen readers.
    */
   @Input() title?: string;
   @Input() spin?: boolean;
   @Input() pulse?: boolean;
   @Input() mask?: IconProp;
+
+  /**
+   * Set `style` attribute on the SVG element rendered by the component.
+   *
+   * @deprecated This input breaks view encapsulation and is not recommended.
+   * For simple cases (like colors), use `style` on the component itself, for
+   * more complex usages, explicitly opt-in to break the view encapsulation.
+   * This input is deprecated since 0.12.0 and will be removed in 0.13.0.
+   */
   @Input() styles?: Styles;
   @Input() flip?: FlipProp;
   @Input() size?: SizeProp;
@@ -54,6 +63,15 @@ export class FaIconComponent implements OnChanges {
   @Input() symbol?: FaSymbol;
   @Input() rotate?: RotateProp;
   @Input() fixedWidth?: boolean;
+
+  /**
+   * Set `class` attribute on the SVG element rendered by the component.
+   *
+   * @deprecated This input breaks view encapsulation and is not recommended.
+   * For simple cases (like colors), use `class` on the component itself, for
+   * more complex usages, explicitly opt-in to break the view encapsulation.
+   * This input is deprecated since 0.12.0 and will be removed in 0.13.0.
+   */
   @Input() classes?: string[] = [];
   @Input() transform?: string | Transform;
 
@@ -86,14 +104,8 @@ export class FaIconComponent implements OnChanges {
       return faWarnIfIconSpecMissing();
     }
 
-    let iconToBeRendered: IconProp = null;
-    if (this.icon == null) {
-      iconToBeRendered = this.config.fallbackIcon;
-    } else {
-      iconToBeRendered = this.icon;
-    }
-
     if (changes) {
+      const iconToBeRendered = this.icon != null ? this.icon : this.config.fallbackIcon;
       const iconDefinition = this.findIconDefinition(iconToBeRendered);
       if (iconDefinition != null) {
         const params = this.buildParams();

src/lib/layers/layers-counter.component.ts

@@ -14,7 +14,25 @@ import { FaLayersComponent } from './layers.component';
 export class FaLayersCounterComponent implements OnChanges {
   @Input() content: string;
   @Input() title?: string;
+
+  /**
+   * Set `style` attribute on the SVG element rendered by the component.
+   *
+   * @deprecated This input breaks view encapsulation and is not recommended.
+   * For simple cases (like colors), use `style` on the component itself, for
+   * more complex usages, explicitly opt-in to break the view encapsulation.
+   * This input is deprecated since 0.12.0 and will be removed in 0.13.0.
+   */
   @Input() styles?: Styles;
+
+  /**
+   * Set `class` attribute on the SVG element rendered by the component.
+   *
+   * @deprecated This input breaks view encapsulation and is not recommended.
+   * For simple cases (like colors), use `class` on the component itself, for
+   * more complex usages, explicitly opt-in to break the view encapsulation.
+   * This input is deprecated since 0.12.0 and will be removed in 0.13.0.
+   */
   @Input() classes?: string[] = [];
   @Input() position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
 

src/lib/layers/layers-text.component.ts

@@ -26,7 +26,25 @@ import { FaLayersComponent } from './layers.component';
 export class FaLayersTextComponent implements OnChanges {
   @Input() content: string;
   @Input() title?: string;
+
+  /**
+   * Set `style` attribute on the SVG element rendered by the component.
+   *
+   * @deprecated This input breaks view encapsulation and is not recommended.
+   * For simple cases (like colors), use `style` on the component itself, for
+   * more complex usages, explicitly opt-in to break the view encapsulation.
+   * This input is deprecated since 0.12.0 and will be removed in 0.13.0.
+   */
   @Input() styles?: Styles;
+
+  /**
+   * Set `class` attribute on the SVG element rendered by the component.
+   *
+   * @deprecated This input breaks view encapsulation and is not recommended.
+   * For simple cases (like colors), use `class` on the component itself, for
+   * more complex usages, explicitly opt-in to break the view encapsulation.
+   * This input is deprecated since 0.12.0 and will be removed in 0.13.0.
+   */
   @Input() classes?: string[] = [];
   @Input() spin?: boolean;
   @Input() pulse?: boolean;