Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify explainer and address some less-complex issues #36

Merged
merged 16 commits into from
Jun 21, 2019
Merged

Clarify explainer and address some less-complex issues #36

Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
84a6aa3
Clarify explainer and address some less-complex issues
Jun 20, 2019
1a5bf61
Update README.md
Jun 20, 2019
0d0d2e3
Update README.md
Jun 20, 2019
5b523d1
Update README.md
Jun 20, 2019
cd1cfa2
Update README.md
Jun 20, 2019
d3da6da
Update README.md
Jun 20, 2019
8e6ec49
Update README.md
Jun 21, 2019
40b80a2
Contextify links and reference WICG Discourse
Jun 21, 2019
f587f11
Merge branch 'spec-feedback-update' of https://github.com/jackbsteinb…
Jun 21, 2019
94b5610
Clarify discourse language
Jun 21, 2019
6587007
Pull stretc h / mobile into issue #39
Jun 21, 2019
f396782
Reshape Notification, dialog, and layering goal language
Jun 21, 2019
27a63e2
Change title and add introduction in style of tkent std-switch
Jun 21, 2019
6f8c45b
Update README.md
Jun 21, 2019
ceb25b2
Add issue links to default duration and accessiblity issues
Jun 21, 2019
68d9a6a
Merge branch 'spec-feedback-update' of https://github.com/jackbsteinb…
Jun 21, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 93 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
# std-toast
This document scopes out a web platform API for a 'toast' pop-up notification.
# 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?

Expand Down Expand Up @@ -35,7 +44,7 @@ The study group contains [a variety of such examples](study-group/Library-Demos.

## Why?

Modern web applications allow users to complete lots of actions per page,
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.

Expand Down Expand Up @@ -97,7 +106,7 @@ The second imports the `showToast()` function from the `"std:elements/toast"` mo
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 `alert()` is currently used.
similar to how the `alert()` function can be used show alerts.

```js
import { showToast } from 'std:elements/toast';
Expand All @@ -121,10 +130,6 @@ which the standard toast aims to accomplish natively.
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.

- Toasts almost always support a message, action, and close button.

- Toasts often support an icon and a title.

- 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.
Expand All @@ -138,9 +143,9 @@ which the standard toast aims to accomplish natively.
either by stacking them in the view,
or queueing them and displaying sequentially.

A broader goal of the standard toast is 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 default.
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.

Expand All @@ -150,16 +155,27 @@ TODO([#14](https://github.com/jackbsteinberg/std-toast/issues/14)): create an ex

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 `<std-toast>` element

#### 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.
- `open`: a boolean attribute, determining whether the toast is visible or not (according to the default styles).
By default toasts are not shown.
- `theme`: one of `"default"`, ???, or ???, conveying the semantic priority of the toast, and influencing its styling (both default and user-provided)
- TODO([#18](https://github.com/jackbsteinberg/std-toast/issues/18)): decide on list of themes to natively support and create and style them.
- `position`: one of `"top-left"`, `"top-center"`, `"top-right"`, `"middle-left"`, `"middle-center"`, `"middle-right"`, `"bottom-left"`, `"bottom-center"`, or `"bottom-right"`.
- `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`: a boolean attribute, determining whether an explicit close button is shown.
Expand Down Expand Up @@ -242,11 +258,17 @@ TODO: when we have a prototype, link to/show an example of this in action.

- `.show(options)`: shows the toast element,
by toggling its `open=""` attribute to true.
It will also start or reset the timeout of the toast,
to show for the provided `duration`,
or a default `duration` of `2000`ms.
The `options` include:
- `duration`: how long to show the toast, in milliseconds. Defaults to ???
- `duration`: how long to show the toast, in milliseconds. Defaults to `2000`.
jackbsteinberg marked this conversation as resolved.
Show resolved Hide resolved
jackbsteinberg marked this conversation as resolved.
Show resolved Hide resolved
- `multiple`: ???
- `newestOnTop`: ???

TODO([#37](https://github.com/jackbsteinberg/std-toast/issues/37)): should `2000` be the default?
Should it be longer for accessibility reasons? Should it change dependent on the amount of text in the toast?

TODO([#19](https://github.com/jackbsteinberg/std-toast/issues/19)): how do `multiple` and `newestOnTop` work?

- `.hide()`: hides the toast element,
Expand All @@ -267,6 +289,8 @@ A `<std-toast>` element can fire the following events:
- `"actionclick"`: the toast's call-to-action button or link was clicked, if one exists.
- TODO([#11](https://github.com/jackbsteinberg/std-toast/issues/11)): flesh out exactly how the action works and how this event is linked.

TODO([#35](https://github.com/jackbsteinberg/std-toast/issues/35)): split `"show"` and `"hide"` into `"will/didShow"` and `"will/didHide"`.

### `showToast(message, options)`

The `"std:elements/toast"` module also exports a convenience function,
Expand All @@ -282,8 +306,7 @@ Finally,
it returns the created `<std-toast>` element,
allowing further manipulation by script.

`message` is a string that will be inserted as a text node
(TODO: or as a `<p>` element?) into the created `<std-toast>`.
`message` is a string that will be inserted as a text node into the created `<std-toast>`.

`options` allows configuring both the attributes of the `<std-toast>`,
and the options for this particular showing of the toast.
Expand Down Expand Up @@ -324,6 +347,12 @@ For example,
a CSS shadow part for the close button,
or some CSS variables.

## Accessibility

jackbsteinberg marked this conversation as resolved.
Show resolved Hide resolved
TODO: determine proper accessibility roles / semantics.
See issues [#25](https://github.com/jackbsteinberg/std-toast/issues/25) and
[#29](https://github.com/jackbsteinberg/std-toast/issues/29) for ongoing initial discussions.

## Common Patterns

### Show existing toast
Expand Down Expand Up @@ -368,5 +397,52 @@ const toast2 = showToast("number 2", configs);
```

### Styling the toast

TODO

## Security and Privacy Considerations
See [TAG Security / Privacy Self Review](/security-privacy-self-review.md).

## Considered Alternatives

jackbsteinberg marked this conversation as resolved.
Show resolved Hide resolved
### Extending the Notification API
Toasts are intended to be ephemeral, context-specific messages,
and collecting them in a user's notifications tray doesn't reflect the spirit of the pattern.
[kenchris](https://github.com/kenchris) put this well in [this comment](https://github.com/w3ctag/design-reviews/issues/385#issuecomment-502070938) on the TAG Design Review:

> the difference is that this is a temporary notification / infobar,
> like you see for PWAs ("new version available, press reload to refresh")
> or like in GMail ("Chat is currently unavailable") etc.
> These are not things you want an actual system notification for...
> They really depend on the surrounding content/situation unlike regular notifications.

The toast is intended to be a completely in-page element,
not a system-level notification the way Notifications and Android toasts are.
Because of this page-level role, toasts do not require any user-granted permissions.

### Extending the `<dialog>` element
This approach was considered, and is still an open area of exploration,
but our current thoughts are to go a different route for a few reasons.
First and foremost, we felt the accessibility considerations for a toast and a dialog differ,
as the dialog typically engages in the kind of flow-breaking behavior we want toasts to avoid.
Additionally, the popular pattern of adding a call to action button on a toast with a baked-in time limit
necessitates replacing tab-trapping with a less intrusive, easily restored alternative.
domenic marked this conversation as resolved.
Show resolved Hide resolved
The line between the elements becomes blurrier from a functional perspective,
with action-button-containing toasts and non-modal dialogs,
but the intent and semantics are sufficiently different,
similar to `<blockquote>` and `<q>`, or `<meter>` and `<progress>`.

### As a new global element (instead of a built-in module)
See [here](https://github.com/whatwg/html/issues/4697).

### Leaving this up to libraries
See [here](https://github.com/tkent-google/std-switch#leaving-this-up-to-libraries).

## Extra Resources
jackbsteinberg marked this conversation as resolved.
Show resolved Hide resolved
This proposal comes in parallel with the [proposal for a standard switch element](https://github.com/tkent-google/std-switch),
which has a good [FAQs section](https://github.com/tkent-google/std-switch#faqs), many of which apply to this proposal as well.
Additionally, the idea of creating new polyfillable HTML elements is being explored in
[this issue](https://github.com/whatwg/html/issues/4696) on the HTML standard,
and the idea of creating new pay-for-what-you-use HTML elements if being explored in
[this issue](https://github.com/whatwg/html/issues/467) on the HTML standard.
There is also currently an [open discussion](https://discourse.wicg.io/t/proposal-toast-ui-element/3634)
on the WICG discourse page to gauge and solicit community interest in moving the explainer to incubate in a WICG repo.