Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jackbsteinberg/std-toast
https://github.com/jackbsteinberg/std-toast
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/jackbsteinberg/std-toast
- Owner: jackbsteinberg
- Created: 2019-05-08T20:41:01.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2019-08-29T15:58:56.000Z (about 5 years ago)
- Last Synced: 2024-07-18T22:22:30.428Z (4 months ago)
- Size: 3.83 MB
- Stars: 120
- Watchers: 12
- Forks: 4
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Security: security-privacy-self-review.md
Awesome Lists containing this project
README
# A Standard 'Toast' UI Element
# Introduction
This document proposes a new HTML element for a "toast" pop-up notification.
It is provided as a [built-in module](https://github.com/tc39/proposal-javascript-standard-library/).
This proposal is intended to incubate in the WICG once it gets interest on
[its Discourse thread](https://discourse.wicg.io/t/proposal-toast-ui-element/3634).
After incubation, if it gains multi-implementer interest,
it will graduate to the [HTML Standard](https://html.spec.whatwg.org/multipage/) as a new standard HTML element.
## What is a "toast" pop-up notification?
> "Toasts are pretty common in UX design; refers to popup notifications which typically appear at the bottom of the screen (like a piece of toast in a toaster)."
— [Kyle Decker](https://twitter.com/kybradeck/status/1139006173762531328)
Sneha Munot provides a nice definition in her [uxplanet.org article](https://uxplanet.org/toast-notification-or-dialog-box-ae32ad53106d),
where she compares toasts to dialog boxes.
> [A toast] is a small message that shows up in a box at the bottom of the screen and disappears on its own after few seconds.
> It is a simple feedback about an operation in which current activity remains visible and interactive.
> It basically is to inform the user of something that is not critical and that does not require specific attention and does not prevent the user from using the app device.
>
> For example; on gmail when a mail is send you receive a feedback of “Sending message…” written in the form of toast message.
Another concise definition is found in Ben Brocka's [ux.stackexchange.com response](https://ux.stackexchange.com/a/12000):
> A Toast is a non modal, unobtrusive window element used to display brief, auto-expiring windows of information to a user.
This adds which adds the distinguishing detail of a toast being **auto-expiring**.
In the absence of browser-intrinsic toasts,
the current state of affairs is that many libraries and design systems include toast features.
This repository contains a [study group](https://github.com/jackbsteinberg/std-toast/tree/master/study-group) which surveys and compares toast implementations across the web and other platforms.
Below is an animated image displaying some typical toast behaviors,
drawn from the [Blueprint](https://blueprintjs.com/docs/#core/components/toast) design component library.
The study group contains [a variety of such examples](study-group/Library-Demos.md).
## Why?
Modern web applications allow users to complete many actions per page,
which necessitates providing clear feedback for each action.
Toast notifications are commonly used to unobtrusively provide this feedback.
Many libraries in a variety of frameworks implement a version of toast
(see [research](./study-group/)),
but the web has no built-in API to address the use case.
By providing a toast API as part of the web platform's standard library,
the web becomes more competitive with other app development platforms,
and web application developers can spend less of their time and bytes
on implementing this pattern.
Toasts are also a deceptively-tricky pattern to get right.
They require special accessibility considerations,
and scenarios involving multiple toasts need special handling.
[Not all libraries account for these subtleties](./study-group/).
By providing a built-in toast control that fully handles these aspects,
we can level up the typical toast experience for both developers and users of the web.
Finally,
the ecosystem can benefit from a shared understanding of how to create and style toasts.
If the platform provides a toast,
then all libraries and components can freely use toasts to communicate to their users.
Whereas,
if toasts can only be found in libraries,
then importing a toast-using component also means importing their opinion on what the best toast library is.
In the worst case,
this can lead to multiple uncoordinated toast libraries acting on a single page,
each of which needs its own styling and tweaks to fit in to the application.
If instead libraries and components all use the standard toast,
the application developer can centrally style and coordinate them.
## Sample code
The standard toast can be used according to two different patterns.
The first defines a `` HTML element,
then shows it with configurations via a method on the element.
This can be used to declaratively predefine toasts the application will need,
and then show them inside the application logic.
```html
import 'std:elements/toast';
Email sent!
```
```js
document.querySelector('#sample-toast').show({
duration: 3000
});
```
The second imports the `showToast()` function from the `"std:elements/toast"` module,
which takes in a message and some configurations and creates and shows a toast in the DOM.
This is more convenient for one-off toasts,
or for JavaScript-driven situations,
similar to how the `alert()` function can be used show alerts.
```js
import { showToast } from 'std:elements/toast';
const toast = showToast("Email sent!", {
type: "success",
duration: 3000
});
```
## Goals
Across popular toast implementations there are recurring patterns,
which the standard toast aims to accomplish natively.
- The component will be accessible by default;
native accessibility is a strong priority for toasts,
as they can be difficult to make properly accessible.
- Toast implementations are often shaped similarly,
and a goal of the standard toast is to make it as easy as possible for developers
to build and style toasts that conform to those common shapes.
- The positioning of the toast must be intuitive,
so the standard toast will come with built-in support for common positions,
as well as a sensible default.
- To balance ease of use with customization,
the standard toast will support creating and showing with one JavaScript function,
as well as writing a custom view with a `` element
and showing that with a method.
- The standard toast will come with support for showing multiple toasts,
either by stacking them in the view,
or queueing them and displaying sequentially.
The standard toast API hopes to provide a base for more opinionated or featureful toast libraries to layer on top of.
It will be designed and built highly extensible,
so library implementations can focus on providing more specific styling, better framework support, or more opinionated defaults.
The intent is that any developer looking to use a toast in their work will use a standard toast,
or a library which provides a wrapper on top of standard toast.
TODO([#14](https://github.com/jackbsteinberg/std-toast/issues/14)): create an example of this layering and link to it here.
## Proposed API
The element is provided as a [built-in module](https://github.com/tc39/proposal-javascript-standard-library/blob/master/README.md),
named `"std:elements/toast"`.
See [whatwg/html#4697](https://github.com/whatwg/html/issues/4697) for more discussion on "pay-for-what-you-use" elements available via module imports.
### The `` element
#### Behavior
The `` element provides a subtle, non-interruptive notification to the user.
The toast will appear at a customized time and position on the screen,
and will typically contain a message and optionally action and dismiss buttons
(though arbitrary markup in the element is supported).
The contents will be announced to a screen reader
(politely or assertively depending on `type` [see [attributes](#attributes)]),
and after a certain duration, the toast will timeout and hide itself
(though this timeout will be suspended while the toast has focus or the mouse is hovering on it).
TODO([#18](https://github.com/jackbsteinberg/std-toast/issues/18),
[#29](https://github.com/jackbsteinberg/std-toast/issues/29)):
determine properly accessible behavior,
specifically w.r.t. actions and navigation to / from the toast.
#### Attributes
- [Global attributes](https://html.spec.whatwg.org/multipage/dom.html#global-attributes)
- `open`: a boolean attribute, determining whether the toast is visible or not (according to the default styles).
By default toasts are not shown.
- `type`: an [enumerated attribute](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#enumerated-attribute) indicating whether the toast is of a special type:
one of `"success"`, `"warning"`, or `"error"`.
This is used to convey special [semantics](https://html.spec.whatwg.org/multipage/dom.html#represents) for the toast,
similar to the distinctions between e.g. `
` / `` / `
` or `` / `` / ``.
- Toasts with no `type=""` set (or `type=""` set to an invalid value) have no special semantics distinction.
- Like other semantic distinctions,
authors may want to style based on the distinction.
The [default styles](#default-styles) only change the border color of the toast,
but can be overridden by a page or design system to give any desired appearance.
- By default, `"error"` toasts will be treated as having the ARIA role semantics of [alert](https://rawgit.com/w3c/aria/master/#alert),
while the other toasts will be treated as having the ARIA role semantics of a [status](https://rawgit.com/w3c/aria/master/#status).
As with all HTML elements,
explicitly-specified ARIA attributes can take precedence for exceptional cases,
e.g. `` could be used to immediately notify the user of a time-sensitive success.
- TODO: action-containing toasts may also need to be assertive.
- `position`: default position will be ???
- Options for position:
- `"top-left"`
- `"top-center"`
- `"top-right"`
- `"center"`
- `"bottom-left"`
- `"bottom-center"`
- `"bottom-right"`
- TODO([#39](https://github.com/jackbsteinberg/std-toast/issues/39)): Do we need values `"top-stretch"`, `"center-stretch"`, and `"bottom-stretch"` as well? Should this stretching be done automatically on mobile?
The default (if the attribute is omitted or set to an invalid value) is ???.
- TODO([#13](https://github.com/jackbsteinberg/std-toast/issues/13)): should this positioning be an attribute or a style
- `closebutton`: allows setting the toast's close button content (using ``),
or leaving it up to the user agent's default (using ``).
If this attribute is not present,
the toast does not have a close button.
See the ["Appearance customization"](#appearance-customization) section for how to customize the close button when it's present.
#### Properties
##### Reflected properties
All attributes will be reflected as properties on the element's JavaScript interface.
For example:
```js
const toast = document.createElement('std-toast');
console.log(toast.open); // false
```
The `type` enumerated attribute is reflected [limited to only known values](https://html.spec.whatwg.org/multipage/common-dom-interfaces.html#limited-to-only-known-values),
with an invalid value default and missing value default of the default state. The default state does not have a corresponding keyword.
_This means that `toast.type` will return the empty string, if the `type=""` attribute's value is missing, or not a case-insensitive match for `"warning"`, `"error"`, or `"success"`. Otherwise it will return those values, in their canonical lowercase._
##### `closeButton` property
The `closeButton` property allows controlling the element's `closebutton=""` attribute.
It is similar to the reflected properties,
but slightly more complicated to allow both a boolean usage model
(for using the user agent's default close button content)
and a string usage model
(for customizing the close button content).
In detail:
- The getter returns `false` if the attribute is absent,
`true` if the attribute is present with the empty string as its value,
and the attribute's value otherwise.
- The setter,
if given true,
sets the value of the attribute to the empty string.
If given false,
it removes the attribute.
Otherwise,
it converts the given value to a string,
and sets the attribute's value to that string.
To see examples of the `closeButton` setter in use,
read on to the next section.
##### `action` property
There will additionally be an `action` property,
which returns or allows setting an element that provides the toast's action.
In detail:
- The getter returns the first descendant element with the `slot="action"` attribute set.
If no such element exists,
it returns null.
- The setter accepts an element,
appends it to the toast element,
and sets the `slot="action"` attribute on it.
If any existing such elements exist,
the first one (i.e. the one that would be returned by the getter) is replaced.
(If the provided value is not an `Element`,
a `TypeError` is thrown.)
To see examples of the `action` getter and setter in use,
read on to the next section.
#### Contents
At a technical level, the `` element can be used as a generic container.
However, the authoring conformance requirements,
as well as the API,
steer the developer in to the following content model:
- All children except an action need to be [phrasing content](https://html.spec.whatwg.org/#phrasing-content-2),
that is not [interactive content](https://html.spec.whatwg.org/#interactive-content-2).
These children provide the toast's message.
- There may be zero or one actions,
which are either `` or `` elements,
or autonomous custom elements,
decorated with the `slot="action"` attribute.
TODO: is this the right restriction on what can be an action?
What about `