diff --git a/packages/web/src/scss/components/Toast/README.md b/packages/web/src/scss/components/Toast/README.md index 5d4ce9aaa8..7a46760025 100644 --- a/packages/web/src/scss/components/Toast/README.md +++ b/packages/web/src/scss/components/Toast/README.md @@ -7,6 +7,20 @@ Toast is a composition of a few subcomponents: - [Toast](#toast) - [ToastBar](#toastbar) +## JavaScript Plugin + +For full functionality, you need to provide Spirit JavaScript, which will handle toggling of the Toast component: + +```html + +``` + +You will find the [full documentation](#javascript-plugin-api) of the plugin below on this page. + +Please consult the [main README][web-readme] for how to include JavaScript plugins. + +Or, feel free to write the controlling script yourself. + ## Toast The Toast component is a container responsible for positioning the [ToastBar](#toastbar) component. It is capable of @@ -187,6 +201,25 @@ For example: ``` +### Opening the ToastBar + +Use our JavaScript plugin to open a Toast **that is present in the DOM,** e.g.: + +```html + +``` + +👉 Advanced toast queue control is not yet implemented. + ### Dismissible ToastBar To make the ToastBar dismissible, add the `ToastBar--dismissible` modifier class, a unique `id` attribute, and a close @@ -201,6 +234,7 @@ button: type="button" class="Button Button--small Button--square Button--inverted" data-spirit-dismiss="toast" + data-spirit-target="#my-dismissible-toast" aria-controls="my-dismissible-toast" aria-expanded="true" > @@ -214,8 +248,6 @@ button: 👉 Please keep in mind that the Button color should match the ToastBar color. -⚠️ The JavaScript functionality for dismissing the ToastBar is yet to be implemented. - ## Full Example ```html @@ -252,6 +284,42 @@ button: ``` +## JavaScript Plugin API + +| Method | Description | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `getInstance` | _Static_ method which allows you to get the FileUploader instance associated with a DOM element. | +| `getOrCreateInstance` | _Static_ method which allows you to get the FileUploader instance associated with a DOM element, or create a new one in case it wasn’t initialized. | +| `hide` | Hides the toast element. Returns to the caller before the toast has actually been hidden (i.e. before the `hidden.toast` event occurs). | +| `show` | Reveals the toast element. **Returns to the caller before the toast has actually been shown** (i.e. before the `shown.toast` event occurs). | + +```js +const toast = Toast.getInstance('#example'); // Returns a toast instance + +toast.show(); +``` + +### JavaScript Events + +| Method | Description | +| -------------- | ------------------------------------------------------------------------------------- | +| `hidden.toast` | This event is fired when the `hide` instance has finished being hidden from the user. | +| `hide.toast` | This event is fired immediately when the `hide` instance method has been called. | +| `show.toast` | This event fires immediately when the `show` instance method is called. | +| `shown.toast` | This event is fired when the `show` instance has finished being shown to the user. | + +```js +const myToastEl = document.getElementById('myToast'); +const toast = Toast.getOrCreateInstance(myToastEl); + +myToastEl.addEventListener('hidden.toast', () => { + // Do something… +}); + +toast.hide(); +``` + +[web-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/README.md [mdn-role-log]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/log_role [mdn-aria-live]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live [dictionary-alignment]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#alignment