From 52fef50f65c8c9c7b90d0c17d9ed64fd1298047c Mon Sep 17 00:00:00 2001
From: Rich <piemonkey@protonmail.ch>
Date: Wed, 13 Mar 2024 16:32:27 +0100
Subject: [PATCH] Document passing of custom components as icons

---
 stories/4-utilities/Icons.stories.mdx         | 28 +++++++++++++++++++
 stories/5-components/Brand/AuIcon.stories.js  | 19 +++++++++++++
 .../Toasts/Documentation.stories.mdx          |  3 +-
 3 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 stories/4-utilities/Icons.stories.mdx

diff --git a/stories/4-utilities/Icons.stories.mdx b/stories/4-utilities/Icons.stories.mdx
new file mode 100644
index 000000000..a7d420965
--- /dev/null
+++ b/stories/4-utilities/Icons.stories.mdx
@@ -0,0 +1,28 @@
+import { Canvas, Meta, Story } from "@storybook/addon-docs";
+import * as iconStories from "../5-components/Brand/AuIcon.stories";
+
+<Meta title="Utilities/Icons" />
+
+# Icons
+
+Appuniversum includes many SVG icons that can be used by passing the name of the icon into the component, e.g.
+
+```
+<AuButton @icon="book">Button Text</AuButton>
+```
+
+Alternatively, wherever you can pass an icon name you can instead pass an Ember component that will be rendered instead of the default SVG in the AuIcon component.
+This can be used, for example, to use inline SVGs or PNG icons.
+
+Although the Ember component will not be passed any arguments, it's possible to pass them using the `component` helper.
+See [AuIcon docs](/docs/components-brand-auicon--with-custom-icon) for a live example.
+
+```
+<AuButton @icon={{component 'custom-icon' iconName='some-name'}}>Button Text</AuButton>
+```
+
+All the available icons are listed here:
+
+<Canvas>
+  <Story story={iconStories.Icons} />
+</Canvas>
diff --git a/stories/5-components/Brand/AuIcon.stories.js b/stories/5-components/Brand/AuIcon.stories.js
index 57d381c0a..36a8c408f 100644
--- a/stories/5-components/Brand/AuIcon.stories.js
+++ b/stories/5-components/Brand/AuIcon.stories.js
@@ -42,6 +42,17 @@ const Template = (args) => ({
   context: args,
 });
 
+const CustomIconTemplate = (args) => ({
+  template: hbs`
+    <AuIcon
+      @icon={{component 'au-icon' icon=this.icon}}
+      @size={{this.size}}
+      @alignment={{this.alignment}}
+      @ariaHidden={{this.ariaHidden}}
+    />`,
+  context: args,
+});
+
 const IconList = (args) => ({
   template: hbs`
     <AuIconList />
@@ -57,5 +68,13 @@ Component.args = {
   ariaHidden: true,
 };
 
+export const WithCustomIcon = CustomIconTemplate.bind({});
+WithCustomIcon.args = {
+  icon: 'info-circle',
+  size: 'large',
+  alignment: '',
+  ariaHidden: true,
+};
+
 export const Icons = IconList.bind({});
 IconList.args = {};
diff --git a/stories/5-components/Notifications/Toasts/Documentation.stories.mdx b/stories/5-components/Notifications/Toasts/Documentation.stories.mdx
index 29cc4afe1..43c66bf6b 100644
--- a/stories/5-components/Notifications/Toasts/Documentation.stories.mdx
+++ b/stories/5-components/Notifications/Toasts/Documentation.stories.mdx
@@ -37,7 +37,8 @@ All these methods have the same API. The only difference is the default icon and
 ```ts
 interface ToastOptions {
   type?: "info" | "success" | "warning" | "error"; // Default depends on the used display method
-  icon?: string; // Any valid Appuniversum icon name, default depends on the used display method
+  icon?: string | Component<Record<string, never>>; // Any valid Appuniversum icon name, default
+  // depends on the used display method, or an ember component requiring no arguments
   timeOut?: number; // delay in milliseconds after which the toast auto-closes
   closable?: boolean; // Can the toast be closed by users, defaults to `true`
 }