From 84a6aa3621596aeadc434455b204b8c8d6fcef23 Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Thu, 20 Jun 2019 15:08:25 +0900 Subject: [PATCH 01/14] Clarify explainer and address some less-complex issues --- README.md | 81 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 67 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index c31532f..0e1b52b 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,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. @@ -97,7 +97,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'; @@ -121,10 +121,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. @@ -138,9 +134,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. +A broad goal of the standard toast API 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. +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. @@ -150,16 +146,30 @@ 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"`. +Read more about "pay-for-what-you-use" HTML elements [here](https://github.com/whatwg/html/issues/4697). ### The `` 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"` + - `"middle-left"` + - `"middle-center"` + - `"middle-right"` + - `"bottom-left"` + - `"bottom-center"` + - `"bottom-right"` + - Additionally values `"top-stretch"` and `"bottom-stretch"` will be provided to allow for toasts that span the screen width, + and will be treated as the default for `"top-"` and `"bottom-"` toasts 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. @@ -242,8 +252,11 @@ 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 fo 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`. - `multiple`: ??? - `newestOnTop`: ??? @@ -267,6 +280,8 @@ A `` 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, @@ -282,8 +297,7 @@ Finally, it returns the created `` element, allowing further manipulation by script. -`message` is a string that will be inserted as a text node -(TODO: or as a `

` element?) into the created ``. +`message` is a string that will be inserted as a text node into the created ``. `options` allows configuring both the attributes of the ``, and the options for this particular showing of the toast. @@ -368,5 +382,44 @@ 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 + +### 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]() put this well in [this comment]() 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. + +Toasts also often contain some sort of action the user can take which affects the state of the page +(e.g. un-sending an email on Gmail). +To provide this kind of behavior accessibly the element should live wholly in the page / DOM. +This will have the added benefit of preventing pages in the background from using toasts to fight for user attention. + +### Extending the `

` element +This approach was considered, but we decided to go a different route for a few reasons. +First and foremost, we felt the accessibility considerations for a toast and a dialog are fundamentally opposed, +as the dialog 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. + +### As a new global element (instead of a built-in module) +See [here](https://github.com/tkent-google/std-switch#as-a-new-global-element-instead-of-a-built-in-module). + +### Leaving this up to libraries +See [here](https://github.com/tkent-google/std-switch#leaving-this-up-to-libraries). + +## Extra Resources +See [here](https://github.com/tkent-google/std-switch#faqs) for std-switch FAQs, +and [here](https://github.com/whatwg/html/issues/4696) +and [here](https://github.com/whatwg/html/issues/4697) +for relevant open issues on WHATWG/html. From 1a5bf617d2681a7847631ef6b48bd43faa0c8976 Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Thu, 20 Jun 2019 16:33:23 +0900 Subject: [PATCH 02/14] Update README.md Co-Authored-By: Domenic Denicola --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0e1b52b..496cee4 100644 --- a/README.md +++ b/README.md @@ -253,7 +253,7 @@ 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 fo the provided `duration`, +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 `2000`. From 0d0d2e3636d73c9f9be3b648ba5d2f94608fc935 Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Thu, 20 Jun 2019 16:33:53 +0900 Subject: [PATCH 03/14] Update README.md Co-Authored-By: Domenic Denicola --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 496cee4..c5a4e83 100644 --- a/README.md +++ b/README.md @@ -146,7 +146,7 @@ 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"`. -Read more about "pay-for-what-you-use" HTML elements [here](https://github.com/whatwg/html/issues/4697). +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 From 5b523d1f8cb7ecc7faa3777c070a936a3508cb53 Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Thu, 20 Jun 2019 16:50:45 +0900 Subject: [PATCH 04/14] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c5a4e83..1b54762 100644 --- a/README.md +++ b/README.md @@ -392,7 +392,7 @@ See [TAG Security / Privacy Self Review](/security-privacy-self-review.md). ### 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]() put this well in [this comment]() on the TAG Design Review: +[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") From cd1cfa272c89c95d72085466d0059c72493a61bd Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Thu, 20 Jun 2019 16:52:05 +0900 Subject: [PATCH 05/14] Update README.md Co-Authored-By: Domenic Denicola --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1b54762..604eaf2 100644 --- a/README.md +++ b/README.md @@ -422,4 +422,4 @@ See [here](https://github.com/tkent-google/std-switch#leaving-this-up-to-librari See [here](https://github.com/tkent-google/std-switch#faqs) for std-switch FAQs, and [here](https://github.com/whatwg/html/issues/4696) and [here](https://github.com/whatwg/html/issues/4697) -for relevant open issues on WHATWG/html. +for relevant open issues on the HTML Standard regarding potential patterns for new built-in elements (including this one). From d3da6daca157394847a43904930cd4c74e2f6d66 Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Thu, 20 Jun 2019 16:53:02 +0900 Subject: [PATCH 06/14] Update README.md Co-Authored-By: fergald --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 604eaf2..faa8d62 100644 --- a/README.md +++ b/README.md @@ -252,7 +252,7 @@ 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, +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: From 8e6ec492ead1fce2ce379c326fe5e5f2aacf8c26 Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Fri, 21 Jun 2019 11:03:51 +0900 Subject: [PATCH 07/14] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index faa8d62..bc177b6 100644 --- a/README.md +++ b/README.md @@ -413,7 +413,7 @@ Additionally, the popular pattern of adding a call to action button on a toast w necessitates replacing tab-trapping with a less intrusive, easily restored alternative. ### As a new global element (instead of a built-in module) -See [here](https://github.com/tkent-google/std-switch#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). From 40b80a23021079888b91df01826dfa06b9ab7caa Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Fri, 21 Jun 2019 11:28:44 +0900 Subject: [PATCH 08/14] Contextify links and reference WICG Discourse --- README.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index faa8d62..6759bbf 100644 --- a/README.md +++ b/README.md @@ -338,6 +338,8 @@ For example, a CSS shadow part for the close button, or some CSS variables. +## Accessibility + ## Common Patterns ### Show existing toast @@ -419,7 +421,11 @@ See [here](https://github.com/tkent-google/std-switch#as-a-new-global-element-in See [here](https://github.com/tkent-google/std-switch#leaving-this-up-to-libraries). ## Extra Resources -See [here](https://github.com/tkent-google/std-switch#faqs) for std-switch FAQs, -and [here](https://github.com/whatwg/html/issues/4696) -and [here](https://github.com/whatwg/html/issues/4697) -for relevant open issues on the HTML Standard regarding potential patterns for new built-in elements (including this one). +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 about gauging interest in moving the explainer to incubate in a WICG repo. From 94b56109940607e377fe964477fc99a84b9493c5 Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Fri, 21 Jun 2019 12:16:37 +0900 Subject: [PATCH 09/14] Clarify discourse language --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 06f5e31..08f4bb8 100644 --- a/README.md +++ b/README.md @@ -428,4 +428,4 @@ Additionally, the idea of creating new polyfillable HTML elements is being explo 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 about gauging interest in moving the explainer to incubate in a WICG repo. +on the WICG discourse page to gauge and solicit community interest in moving the explainer to incubate in a WICG repo. From 6587007e23cdc0f2e5bebea33c839af44ef8758f Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Fri, 21 Jun 2019 12:48:47 +0900 Subject: [PATCH 10/14] Pull stretc h / mobile into issue #39 --- README.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 08f4bb8..ed6ba50 100644 --- a/README.md +++ b/README.md @@ -162,14 +162,11 @@ By default toasts are not shown. - `"top-left"` - `"top-center"` - `"top-right"` - - `"middle-left"` - - `"middle-center"` - - `"middle-right"` + - `"center"` - `"bottom-left"` - `"bottom-center"` - `"bottom-right"` - - Additionally values `"top-stretch"` and `"bottom-stretch"` will be provided to allow for toasts that span the screen width, - and will be treated as the default for `"top-"` and `"bottom-"` toasts on mobile. + - 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. From f3967829d6544f7aded1d812e6d1f306cd07742c Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Fri, 21 Jun 2019 13:12:23 +0900 Subject: [PATCH 11/14] Reshape Notification, dialog, and layering goal language --- README.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index ed6ba50..2a54347 100644 --- a/README.md +++ b/README.md @@ -134,8 +134,8 @@ which the standard toast aims to accomplish natively. either by stacking them in the view, or queueing them and displaying sequentially. -A broad goal of the standard toast API 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, +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. @@ -399,17 +399,21 @@ and collecting them in a user's notifications tray doesn't reflect the spirit of > These are not things you want an actual system notification for... > They really depend on the surrounding content/situation unlike regular notifications. -Toasts also often contain some sort of action the user can take which affects the state of the page -(e.g. un-sending an email on Gmail). -To provide this kind of behavior accessibly the element should live wholly in the page / DOM. -This will have the added benefit of preventing pages in the background from using toasts to fight for user attention. +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 `` element -This approach was considered, but we decided to go a different route for a few reasons. -First and foremost, we felt the accessibility considerations for a toast and a dialog are fundamentally opposed, -as the dialog engages in the kind of flow-breaking behavior we want toasts to avoid. +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. +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 `
` and `` and `` and ``. ### As a new global element (instead of a built-in module) See [here](https://github.com/whatwg/html/issues/4697). From 27a63e2b7141b4aeb80aeeaa5fe9ae44e93a3cb4 Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Fri, 21 Jun 2019 13:25:15 +0900 Subject: [PATCH 12/14] Change title and add introduction in style of tkent std-switch --- README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2a54347..0beee76 100644 --- a/README.md +++ b/README.md @@ -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? From 6f8c45ba16f5d4b206be7477202fa7336ab2b2ac Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Fri, 21 Jun 2019 13:27:11 +0900 Subject: [PATCH 13/14] Update README.md Co-Authored-By: Domenic Denicola --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0beee76..aac670c 100644 --- a/README.md +++ b/README.md @@ -422,7 +422,7 @@ necessitates replacing tab-trapping with a less intrusive, easily restored alter 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 `
` and `` and `` and ``. +similar to `
` and ``, or `` and ``. ### As a new global element (instead of a built-in module) See [here](https://github.com/whatwg/html/issues/4697). From ceb25b2a95c91cfbeb034d0b74cd21eb3460ca9a Mon Sep 17 00:00:00 2001 From: Jack Steinberg Date: Fri, 21 Jun 2019 13:32:45 +0900 Subject: [PATCH 14/14] Add issue links to default duration and accessiblity issues --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index 0beee76..1e239f2 100644 --- a/README.md +++ b/README.md @@ -266,6 +266,9 @@ The `options` include: - `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, @@ -346,6 +349,10 @@ or some CSS variables. ## Accessibility +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