From 5b4424143b8233325a7df4bda9e505bb92be1c96 Mon Sep 17 00:00:00 2001 From: Cory LaViska Date: Wed, 16 Sep 2020 17:00:48 -0400 Subject: [PATCH] meh --- docs/components/alert.md | 196 +++++++++++++++++++++------------ src/components.d.ts | 4 +- src/components/alert/alert.tsx | 17 ++- 3 files changed, 137 insertions(+), 80 deletions(-) diff --git a/docs/components/alert.md b/docs/components/alert.md index ee3de0b4..15d213b4 100644 --- a/docs/components/alert.md +++ b/docs/components/alert.md @@ -2,73 +2,7 @@ [component-header:sl-alert] -Alerts are used to display important messages. - -Alerts are designed to be shown dynamically, so you must include the `open` attribute to display them. - - - - - -```html preview -
- Primary - Success - Info - Warning - Danger - - - - This is super informative
- You can tell by how pretty the alert is. - - - - - Your changes have been saved
- You can safely exit the app now. - - - - - Your settings have been updated
- Some settings will take affect the next time you log in. - - - - - Your session has ended
- Please login again to continue. - - - - - Your account has been deleted
- We're very sorry to see you go! - -
- - -``` - - - - - - - - - +Alerts are used to display important messages either inline or as toast notifications. ```html preview @@ -103,7 +37,7 @@ Set the `type` attribute to change the alert's type. Your settings have been updated
- Some settings will take affect the next time you log in. + Settings will take affect on next login.
@@ -151,4 +85,130 @@ Icons are optional. Simply omit the `icon` slot if you don't want them. ``` +### Toast Notifications + +When the `toast` prop is used, the alert will be displayed as a toast notification. To facilitate this, the alert is appended to the toast stack the first time it is shown and removed from the DOM when dismissed. By storing a reference to the alert, you can use it again later as shown in this example. + +```html preview +
+ Primary + Success + Info + Warning + Danger + + + + This is super informative
+ You can tell by how pretty the alert is. + + + + + Your changes have been saved
+ You can safely exit the app now. + + + + + Your settings have been updated
+ Settings will take affect on next login. + + + + + Your session has ended
+ Please login again to continue. + + + + + Your account has been deleted
+ We're very sorry to see you go! + +
+ + +``` + +The toast stack is a fixed position singleton element created and managed internally by the alert component. It will be added and removed from the DOM as needed when toast alerts are shown. By default, the toast stack is positioned at the top-right of the viewport. When more than one alert is visible, they will stack vertically. + +You can change the toast stack's position and behavior in your stylesheet. To make toasts appear at the top-left of the viewport, for example, add the following to your stylesheet. + +```css +.sl-toast-stack { + left: 0; + right: auto; +} +``` + +?> By design, toasts cannot be shown in more than one stack. That would be distracting and confusing to users, which makes for a poor experience. + +### Creating Toasts Dynamically + +Toast alerts can be created declaratively, but you can create them imperatively as well. Just make sure to append them to the DOM before calling `show()`. + +```html preview +
+ Create New Toast +
+ + +``` + +### Duration + +Set the `duration` prop to automatically hide an alert after a period of time. This is useful for alerts that don't require user acknowledgement and works especially well with the `toast` prop. + +```html preview +
+ Show Alert + + + + This alert will automatically hide itself after three seconds, unless you interact with it. + +
+ + +``` + [component-metadata:sl-alert] diff --git a/src/components.d.ts b/src/components.d.ts index 6cad59e2..449b32bd 100644 --- a/src/components.d.ts +++ b/src/components.d.ts @@ -28,7 +28,7 @@ export namespace Components { */ "show": () => Promise; /** - * When true, the alert will be shown as a "toast" notification. In this case, the alert will be hoisted to a stack and removed from the DOM when closed. By storing a reference to the alert, you can reuse it by calling `alert.show()` even after it has been removed from the DOM. + * When true, the alert will be shown as a toast notification. To facilitate this, the alert is appended to the toast stack the first time it is shown and removed from the DOM when dismissed. */ "toast": boolean; /** @@ -1451,7 +1451,7 @@ declare namespace LocalJSX { */ "open"?: boolean; /** - * When true, the alert will be shown as a "toast" notification. In this case, the alert will be hoisted to a stack and removed from the DOM when closed. By storing a reference to the alert, you can reuse it by calling `alert.show()` even after it has been removed from the DOM. + * When true, the alert will be shown as a toast notification. To facilitate this, the alert is appended to the toast stack the first time it is shown and removed from the DOM when dismissed. */ "toast"?: boolean; /** diff --git a/src/components/alert/alert.tsx b/src/components/alert/alert.tsx index e3a0a16e..95984dbf 100644 --- a/src/components/alert/alert.tsx +++ b/src/components/alert/alert.tsx @@ -1,5 +1,7 @@ import { Component, Element, Event, EventEmitter, Host, Method, Prop, Watch, h } from '@stencil/core'; +const stack = Object.assign(document.createElement('div'), { className: 'sl-toast-stack' }); + /** * @since 2.0 * @status stable @@ -13,8 +15,6 @@ import { Component, Element, Event, EventEmitter, Host, Method, Prop, Watch, h } * @part close-button - The close button. */ -const stack = Object.assign(document.createElement('div'), { className: 'sl-toast-stack' }); - @Component({ tag: 'sl-alert', styleUrl: 'alert.scss', @@ -31,17 +31,16 @@ export class Alert { @Prop({ mutable: true, reflect: true }) open = false; /** Set to true to make the alert closable. */ - @Prop() closable = false; + @Prop({ reflect: true }) closable = false; /** The type of alert. */ - @Prop() type: 'primary' | 'success' | 'info' | 'warning' | 'danger' = 'primary'; + @Prop({ reflect: true }) type: 'primary' | 'success' | 'info' | 'warning' | 'danger' = 'primary'; /** - * When true, the alert will be shown as a "toast" notification. In this case, the alert will be hoisted to a stack - * and removed from the DOM when closed. By storing a reference to the alert, you can reuse it by calling - * `alert.show()` even after it has been removed from the DOM. + * When true, the alert will be shown as a toast notification. To facilitate this, the alert is appended to the toast + * stack the first time it is shown and removed from the DOM when dismissed. */ - @Prop() toast = false; + @Prop({ reflect: true }) toast = false; /** * The length of time, in milliseconds, the alert will show before closing itself. If the user interacts with the @@ -192,8 +191,6 @@ export class Alert { 'alert--open': this.open, 'alert--closable': this.closable, 'alert--toast': this.toast, - - // States 'alert--primary': this.type === 'primary', 'alert--success': this.type === 'success', 'alert--info': this.type === 'info',