Document how to use custom icons

Fixes #172

docs/guide/custom-icons.md

@@ -0,0 +1,64 @@
+# Custom icons
+
+This guide explains how to use custom icons with `angular-fontawesome`.
+
+First of all, you'll need a valid SVG file containing the icon you want to use. Please refer to
+the [Icon Design Guidelines](https://docs.fontawesome.com/web/add-icons/upload-icons/icon-design)
+and [Prep Icons for Upload](https://docs.fontawesome.com/web/add-icons/upload-icons/prep-icons) to learn how to create
+an SVG icon which can be used with Font Awesome.
+
+## Icon definition
+
+To use a custom icon in the project, you need to define an object specified by the `IconDefinition` type. All icons are
+defined using the same structure, so you can refer to existing icons as examples. The object should contain the 
+following properties:
+
+```typescript
+export interface IconDefinition {
+    prefix: string; // prefix of the icon
+    iconName: string; // name of the icon
+    icon: [
+        number, // viewBox width
+        number, // viewBox height
+        string[], // ligatures (not used in `angular-fontawesome`)
+        string, // unicode (not used in `angular-fontawesome`)
+        string | string[], // single path for a simple icon or array of two paths for a duotone icon
+    ];
+}
+```
+
+Knowing the icon structure, you can easily convert the SVG file to the `IconDefinition` object by picking up the
+relevant parts. Given an example SVG file:
+
+```xml
+
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+    <path d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512z"/>
+</svg>
+```
+
+The icon definition will look like the following:
+
+```typescript
+import { IconDefinition } from '@fortawesome/angular-fontawesome';
+
+const myIcon: IconDefinition = {
+    prefix: 'fac',
+    iconName: 'my-icon',
+    icon: [
+        512,
+        512,
+        [],
+        '',
+        'M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512z',
+    ],
+};
+```
+
+You can also use a [Font Awesome Kit](https://fontawesome.com/kits) to upload your custom icons or pick only the icons
+you'd like to use.
+
+## Use custom icon
+
+To use a custom icon is no different from a Font Awesome icon. You can either add it to
+the [icon library](./icon-library.md) or use an [explicit references](./explicit-reference.md) approach.

docs/usage.md

@@ -53,6 +53,7 @@ Take your icons to the next level with these advanced features.
 Guides on specific topics or use cases.
 
 * [Testing](./guide/testing.md)
+* [Custom icons](./guide/custom-icons.md)
 * [Storybook](./guide/storybook.md)
 * [Advanced uses](./guide/advanced-uses.md)
 * [Styling icon internals](./guide/styling-icon-internals.md)

docs/usage/explicit-reference.md

@@ -58,3 +58,15 @@ export class AppComponent {
 }
 ```
 
+Kit packages use a [subpath exports](https://nodejs.org/api/packages.html#subpath-exports) feature of Node.js. If you
+get an error like `Cannot find module '@awesome.me/kit-KIT_CODE/icons/classic/solid' or its corresponding type 
+declartions.`, you may need to update your `tsconfig.json` to set `moduleResolution` to `bundler`:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler"
+  }
+}
+```
+

docs/usage/icon-library.md

@@ -80,6 +80,18 @@ export class AppComponent {
 }
 ```
 
+Kit packages use a [subpath exports](https://nodejs.org/api/packages.html#subpath-exports) feature of Node.js. If you
+get an error like `Cannot find module '@awesome.me/kit-KIT_CODE/icons' or its corresponding type declartions.`, you may
+need to update your `tsconfig.json` to set `moduleResolution` to `bundler`: 
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler"
+  }
+}
+```
+
 ## Changing the default prefix
 
 The default prefix, `fas`, can be adjusted by injecting the `FaConfig` and modifying the `defaultPrefix` property.

projects/demo/src/app/app.component.ts

@@ -8,14 +8,14 @@ import {
   faBell,
   faCircle,
   faCoffee,
+  faCog,
   faEllipsisH,
   faFighterJet,
   faFlag as solidFlag,
   faHeart,
   faMagic,
   faSpinner,
   faSquare,
-  faCog,
   faTimes,
   faUser,
 } from '@fortawesome/free-solid-svg-icons';
@@ -48,7 +48,7 @@ export class AppComponent {
   faDummy: IconDefinition = {
     prefix: 'fad',
     iconName: 'dummy',
-    icon: [512, 512, [], 'f030', ['M50 50 H412 V250 H50 Z', 'M50 262 H412 V462 H50 Z']],
+    icon: [512, 512, [], '', ['M50 50 H412 V250 H50 Z', 'M50 262 H412 V462 H50 Z']],
   };
 
   notificationsCounter = 1000;

src/testing/helpers.ts

@@ -34,5 +34,5 @@ export const queryByCss = (fixture: ComponentFixture<any>, cssSelector: string):
 export const faDummy: IconDefinition = {
   prefix: 'fad',
   iconName: 'dummy',
-  icon: [512, 512, [], 'f030', ['M50 50 H412 V250 H50 Z', 'M50 262 H412 V462 H50 Z']],
+  icon: [512, 512, [], '', ['M50 50 H412 V250 H50 Z', 'M50 262 H412 V462 H50 Z']],
 };

testing/src/icon/mock-icon-library.service.ts

@@ -4,7 +4,7 @@ import { FaIconLibraryInterface, IconDefinition, IconName, IconPrefix } from '@f
 export const dummyIcon: IconDefinition = {
   prefix: 'fad',
   iconName: 'dummy',
-  icon: [512, 512, [], 'f030', 'M50 50 H462 V462 H50 Z'],
+  icon: [512, 512, [], '', 'M50 50 H462 V462 H50 Z'],
 };
 
 @Injectable({

tsconfig.json

@@ -15,7 +15,7 @@
     "declaration": false,
     "downlevelIteration": true,
     "experimentalDecorators": true,
-    "moduleResolution": "node",
+    "moduleResolution": "bundler",
     "importHelpers": true,
     "target": "ES2022",
     "module": "ES2022",