add docs for notifications

src/Umbraco.Web.UI.Client/.storybook/main.js

@@ -1,7 +1,10 @@
 module.exports = {
 	stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
-	addons: ['@storybook/addon-links', '@storybook/addon-essentials', '@storybook/addon-a11y'],
+	addons: ['@storybook/addon-links', '@storybook/addon-essentials', '@storybook/addon-a11y', '@storybook/addon-docs'],
 	framework: '@storybook/web-components',
+	features: {
+		previewMdx2: true
+	},
 	core: {
 		builder: '@storybook/builder-vite',
 	},

src/Umbraco.Web.UI.Client/.storybook/preview-head.html

@@ -2,6 +2,15 @@
 	body {
 		padding: 0px !important;
 	}
+
+	pre {
+		font-family: monospace;
+		font-size: 14px;
+		background-color: var(--uui-color-background);
+		padding: 1.5em;
+		border-radius: 3px;
+		line-height: 1.3em;
+	}
 </style>
 
 <script>

src/Umbraco.Web.UI.Client/package.json

@@ -44,12 +44,15 @@
   },
   "devDependencies": {
     "@babel/core": "^7.18.10",
+    "@mdx-js/react": "^2.1.2",
     "@open-wc/testing": "^3.1.6",
     "@storybook/addon-a11y": "^6.5.9",
     "@storybook/addon-actions": "^6.5.9",
+    "@storybook/addon-docs": "^6.5.9",
     "@storybook/addon-essentials": "^6.5.9",
     "@storybook/addon-links": "^6.5.9",
     "@storybook/builder-vite": "^0.2.2",
+    "@storybook/mdx2-csf": "^0.0.3",
     "@storybook/web-components": "^6.5.9",
     "@types/chai": "^4.3.1",
     "@types/mocha": "^9.1.1",

src/Umbraco.Web.UI.Client/src/core/services/notification/notification.stories.mdx

@@ -0,0 +1,173 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="API/Notifications/Intro" />
+
+# Notifications
+
+Notifications appear in the bottom right corner of the Backoffice. There are two types of notifications: "Peek" and "Stay". 
+
+**Peek notifications**
+Goes away automatically and should be used as feedback on user actions.
+
+**Stay notifications**
+Stays on the screen until dismissed by the user or custom code. Stay notification should be used when you need user feedback or want to control when the notification disappears.
+
+## Basic usage
+
+### Consume UmbNotificationService from an element
+
+The UmbNotification service can be used to open notifications.
+
+```ts
+import { html, LitElement } from 'lit';
+import { UmbContextConsumerMixin } from './core/context';
+import type { UmbNotificationService } from './core/services/notification';
+
+class MyElement extends UmbContextConsumerMixin(LitElement) {
+
+  private _notificationService: UmbNotificationService;
+
+  constructor () {
+    super();
+
+    this.consumeContext('umbNotificationService', (notificationService) => {
+      this._notificationService = notificationService;
+      // notificationService is now ready to be used
+    });
+  }
+}
+```
+
+### Open a notification
+
+A notification is opened by calling one of the helper methods on the UmbNotificationService. The methods will return an instance of UmbNotificationHandler.
+
+```ts
+import { html, LitElement } from 'lit';
+import { state } from 'lit/decorators.js';
+import { UmbContextConsumerMixin } from './core/context';
+import type { UmbNotificationService, UmbNotificationDefaultData } from './core/services/notification';
+
+class MyElement extends UmbContextConsumerMixin(LitElement) {
+
+  private _notificationService: UmbNotificationService;
+
+  constructor () {
+    super();
+
+    this.consumeContext('umbNotificationService', (notificationService) => {
+      this._notificationService = notificationService;
+      // notificationService is now ready to be used
+    });
+  }
+
+  private _handleClick () {
+    const data: UmbNotificationDefaultData = { headline: 'Look at this', message: 'Something good happened' };
+    const notificationHandler = this._notificationService?.peek('positive', { data });
+
+    notificationHandler.onClose().then(() => {
+      // if you need any logic when the notification is closed you can run it here
+    });
+  }
+
+  render() {
+    return html`<button @click="${this._handleClick}">Open Notification</button>`;
+  }
+}
+```
+
+## Advanced usage: creating custom layouts
+
+The default layout will cover most cases, but there might be situations where we want a more complex layout. You can create a new Custom Element to use as the layout.
+
+### Custom layout element
+
+```ts
+import { html, LitElement } from 'lit';
+import { property } from 'lit/decorators.js';
+import { UUITextStyles } from '@umbraco-ui/uui-css';
+import type { UmbNotificationHandler } from './core/services/notification';
+
+export interface UmbNotificationCustomData {
+  headline: string;
+  user: {
+    name: string;
+  }
+}
+
+export class UmbNotificationLayoutCustom extends LitElement {
+  static styles = [
+    UUITextStyles
+  ];
+
+  @property({ attribute: false })
+  public notificationHandler: UmbNotificationHandler;
+
+  @property({ type: Object })
+  public data: UmbNotificationCustomData;
+
+  private _handleConfirm () {
+    this.notificationHandler.close(true);
+  }
+
+  render() {
+    return html`
+      <uui-toast-notification-layout headline="${this.data.headline}" class="uui-text">
+        ${this.data.user.name}
+        <uui-button slot="actions" @click="${this._handleConfirm}" label="Confirm">Confirm</uui-button>
+      </uui-toast-notification-layout>
+    `;
+  }
+}
+```
+
+### Open notification with custom layout
+
+```ts
+import { html, LitElement } from 'lit';
+import { UmbContextInjectMixin } from './core/context';
+import type { UmbNotificationService, UmbNotificationOptions } from './core/services/notification';
+import type { UmbNotificationCustomData } from './custom-notification-layout';
+
+class MyElement extends LitElement {
+
+  private _notificationService: UmbNotificationService;
+
+  constructor () {
+    super();
+
+    this.consumeContext('umbNotificationService', (notificationService) => {
+      this._notificationService = notificationService;
+      // notificationService is now ready to be used
+    });
+  }
+
+  private _handleClick () {
+    const options: UmbNotificationOptions<UmbNotificationCustomData> = {
+      elementName: 'umb-notification-layout-custom',
+      data: {
+        headline: 'Attention',
+        user: { name: 'Peter Parker' }
+      }
+    };
+
+    const notificationHandler = this._notificationService?.stay('default', options);
+
+    notificationHandler.onClose().then((result) => {
+      if (result) {
+        console.log('He agreed!');
+      }
+    });
+  }
+
+  render() {
+    return html`<button @click="${this._handleClick}">Open Notification</button>`;
+  }
+}
+```
+
+## Best practices
+* Keep messages in notifications short and friendly.
+* Only use headlines when you need extra attention to the notification
+* If a custom notification layout is only used in one module keep the files layout files local to that module.
+* If a custom notification will be used across the project. Create it as a layout in the notification folder and add a helper method to the UmbNotificationService.