mirror
/
shoelace
kopia lustrzana https://github.com/shoelace-style/shoelace
1
0
Forkuj 0
Kod Zgłoszenia Packages Projekty Wydania Wiki Aktywność

Polish off toast

pull/224/head
Cory LaViska 2020-09-18 09:40:21 -04:00
rodzic af0ade31fd
commit be3aae8cb2
3 zmienionych plików z 25 dodań i 21 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

21
docs/components/alert.md
Wyświetl plik

@ -110,7 +110,7 @@ Set the `duration` prop to automatically hide an alert after a period of time. T
### Toast Notifications
To display an alert as a toast notification, call its `toast()` method. This will move the alert out of its position in the DOM and into the [toast stack](#toast-stack) where it will be shown. Once dismissed, it will be removed from the DOM completely. To reuse an alert, store a reference to it and call `toast()` again the next time you want it to appear.
To display an alert as a toast notification, or "toast", create the alert and call its `toast()` method. This will move the alert out of its position in the DOM and into [the toast stack](#the-toast-stack) where it will be shown. Once dismissed, it will be removed from the DOM completely. To reuse a toast, store a reference to it and call `toast()` again later on.
You should always use the `closable` prop so users can dismiss the notification. It's also common to set a reasonable `duration` when the notification doesn't require acknowledgement.
@ -165,7 +165,9 @@ You should always use the `closable` prop so users can dismiss the notification.
</script>
```
For convenience, you can create a utility that emits toast notifications with a single function call. To do this, generate the alert dynamically, append it to the body, and call its `toast()` method as shown in the example below.
### Creating Toasts Imperatively
For convenience, you can create a utility that emits toast notifications with a function call rather than composing them in your HTML. To do this, generate the alert with JavaScript, append it to the body, and call the `toast()` method as shown in the example below.
```html preview
<div class="alert-toast-wrapper">
@ -177,11 +179,14 @@ For convenience, you can create a utility that emits toast notifications with a
const button = container.querySelector('sl-button');
let count = 0;
// Always escape HTML for text arguments!
function escapeHtml(html) {
return document.createElement('div').appendChild(document.createTextNode(html)).parentNode.innerHTML;
const div = document.createElement('div');
div.textContent = html;
return div.innerHTML;
}
// Custom function to emit toast notifications on the fly
// Custom function to emit toast notifications
function notify(message, type = 'primary', icon = 'info-circle', duration = 3000) {
const alert = Object.assign(document.createElement('sl-alert'), {
type: type,
@ -203,11 +208,11 @@ For convenience, you can create a utility that emits toast notifications with a
</script>
```
### Toast Stack
### The Toast Stack
The toast stack is a fixed position singleton element created and managed 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.
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 toasts are shown. When more than one toast is visible, they will stack vertically in the toast stack.
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 CSS.
By default, the toast stack is positioned at the top-right of the viewport. You can change its position by targeting `.sl-toast-stack` in your stylesheet. To make toasts appear at the top-left of the viewport, for example, use the following styles.
```css
.sl-toast-stack {
@ -216,6 +221,6 @@ You can change the toast stack's position and behavior in your stylesheet. To ma
}
```
?> By design, toasts cannot be shown in more than one stack. This makes for a poor user experience, as it distracts and confuses users.
?> By design, it is not possible to show toasts in more than one stack simultaneously. Such behavior is confusing and makes for a poor user experience.
[component-metadata:sl-alert]

6
src/components.d.ts vendored
Wyświetl plik

@ -12,7 +12,7 @@ export namespace Components {
*/
"closable": boolean;
/**
* The length of time, in milliseconds, the alert will show before closing itself. If the user interacts with the alert before it closes (e.g. moves the mouse over it), the duration will restart.
* The length of time, in milliseconds, the alert will show before closing itself. If the user interacts with the alert before it closes (e.g. moves the mouse over it), the timer will restart.
*/
"duration": number;
/**
@ -28,7 +28,7 @@ export namespace Components {
*/
"show": () => Promise<void>;
/**
* Displays the alert as a toast notification. This will move the alert out of its position in the DOM and, when dismissed, it will be removed from the DOM completely. By storing a reference to the alert, you can reuse it by calling this method again. The returned promise resolves when the alert is hidden.
* Displays the alert as a toast notification. This will move the alert out of its position in the DOM and, when dismissed, it will be removed from the DOM completely. By storing a reference to the alert, you can reuse it by calling this method again. The returned promise will resolve after the alert is hidden.
*/
"toast": () => Promise<unknown>;
/**
@ -1427,7 +1427,7 @@ declare namespace LocalJSX {
*/
"closable"?: boolean;
/**
* The length of time, in milliseconds, the alert will show before closing itself. If the user interacts with the alert before it closes (e.g. moves the mouse over it), the duration will restart.
* The length of time, in milliseconds, the alert will show before closing itself. If the user interacts with the alert before it closes (e.g. moves the mouse over it), the timer will restart.
*/
"duration"?: number;
/**

19
src/components/alert/alert.tsx
Wyświetl plik

@ -1,6 +1,6 @@
import { Component, Element, Event, EventEmitter, Host, Method, Prop, Watch, h } from '@stencil/core';
const stack = Object.assign(document.createElement('div'), { className: 'sl-toast-stack' });
const toastStack = Object.assign(document.createElement('div'), { className: 'sl-toast-stack' });
/**
* @since 2.0
@ -38,7 +38,7 @@ export class Alert {
/**
* The length of time, in milliseconds, the alert will show before closing itself. If the user interacts with the
* alert before it closes (e.g. moves the mouse over it), the duration will restart.
* alert before it closes (e.g. moves the mouse over it), the timer will restart.
*/
@Prop() duration = Infinity;
@ -123,17 +123,16 @@ export class Alert {
/**
* Displays the alert as a toast notification. This will move the alert out of its position in the DOM and, when
* dismissed, it will be removed from the DOM completely. By storing a reference to the alert, you can reuse it by
* calling this method again. The returned promise resolves when the alert is hidden.
* calling this method again. The returned promise will resolve after the alert is hidden.
*/
@Method()
async toast() {
return new Promise(resolve => {
if (!stack.parentElement) {
document.body.append(stack);
if (!toastStack.parentElement) {
document.body.append(toastStack);
}
stack.clientWidth; // force a reflow
stack.append(this.host);
toastStack.append(this.host);
this.show();
this.host.addEventListener(
@ -142,9 +141,9 @@ export class Alert {
this.host.remove();
resolve();
// Remove the stack from the DOM when there are no more alerts
if (stack.querySelector('sl-alert') === null) {
stack.remove();
// Remove the toast stack from the DOM when there are no more alerts
if (toastStack.querySelector('sl-alert') === null) {
toastStack.remove();
}
},
{ once: true }