feat(snackbar): Implement full-featured Snackbar component #852
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -18,7 +18,7 @@ path: /catalog/snackbars/ | |
|
|
||
| The MDC Snackbar component is a spec-aligned snackbar/toast component adhering to the | ||
| [Material Design snackbars & toasts requirements](https://material.io/guidelines/components/snackbars-toasts.html#snackbars-toasts-specs). | ||
| It requires JavaScript to show and hide itself. | ||
|
|
||
| ## Design & API Documentation | ||
|
|
||
|
|
@@ -53,6 +53,23 @@ npm install --save @material/snackbar | |
| </div> | ||
| ``` | ||
|
|
||
| ### Start Aligned Snackbars (tablet and desktop only) | ||
|
|
||
| MDC Snackbar can be start aligned (including in RTL contexts). To create a start-aligned | ||
| snackbar, add the `mdc-snackbar--align-start` modifier class to the root element. | ||
|
|
||
| ```html | ||
| <div class="mdc-snackbar mdc-snackbar--align-start" | ||
| aria-live="assertive" | ||
| aria-atomic="true" | ||
| aria-hidden="true"> | ||
| <div class="mdc-snackbar__text"></div> | ||
| <div class="mdc-snackbar__action-wrapper"> | ||
| <button type="button" class="mdc-button mdc-snackbar__action-button"></button> | ||
| </div> | ||
| </div> | ||
| ``` | ||
|
|
||
| ### Using the JS Component | ||
|
|
||
| MDC Snackbar ships with a Component / Foundation combo which provides the API for showing snackbar | ||
|
|
@@ -125,6 +142,38 @@ properties and their usage. | |
| | multiline | Whether to show the snackbar with space for multiple lines of text | Optional | Boolean | | ||
| | actionOnBottom | Whether to show the action below the multiple lines of text | Optional, applies when multiline is true | Boolean | | ||
|
|
||
| ### Responding to a Snackbar Action | ||
|
|
||
| To respond to a snackbar action, assign a function to the optional `actionHandler` property in the object that gets passed to the `show` method. If you choose to set this property, you *must _also_* set the `actionText` property. | ||
|
|
||
| ```html | ||
| <div class="mdc-snackbar" | ||
| aria-live="assertive" | ||
| aria-atomic="true" | ||
| aria-hidden="true"> | ||
| <div class="mdc-snackbar__text"></div> | ||
| <div class="mdc-snackbar__action-wrapper"> | ||
| <button type="button" class="mdc-button mdc-snackbar__action-button"></button> | ||
| </div> | ||
| </div> | ||
| ``` | ||
|
|
||
| ```js | ||
| import {MDCSnackbar} from 'mdc-snackbar'; | ||
|
|
||
| const snackbar = new MDCSnackbar(document.querySelector('.mdc-snackbar')); | ||
| const dataObj = { | ||
| message: messageInput.value, | ||
| actionText: 'Undo', | ||
| actionHandler: function () { | ||
| console.log('my cool function'); | ||
| } | ||
| }; | ||
|
|
||
| snackbar.show(dataObj); | ||
| ``` | ||
|
|
||
|
|
||
| ### Keep snackbar when the action button is pressed | ||
|
|
||
| By default the snackbar will be dimissed when the user presses the action button. | ||
|
|
@@ -149,10 +198,18 @@ The adapter for snackbars must provide the following functions, with correct sig | |
| | `removeClass(className: string) => void` | Removes a class from the root element. | | ||
| | `setAriaHidden() => void` | Sets `aria-hidden="true"` on the root element. | | ||
| | `unsetAriaHidden() => void` | Removes the `aria-hidden` attribute from the root element. | | ||
| | `setActionAriaHidden() => void` | Sets `aria-hidden="true"` on the action element. | | ||
| | `unsetActionAriaHidden() => void` | Removes the `aria-hidden` attribute from the action element. | | ||
| | `setActionText(actionText: string) => void` | Set the text content of the action element. | | ||
|
|
||
| | `setMessageText(message: string) => void` | Set the text content of the message element. | | ||
|
|
||
| | `setFocus() => void` | Sets focus on the action button. | | ||
| | `visibilityIsHidden() => boolean` | Returns document.hidden property. | | ||
| | `registerBlurHandler(handler: EventListener) => void` | Registers an event handler to be called when a `blur` event is triggered on the action button | | ||
| | `deregisterBlurHandler(handler: EventListener) => void` | Deregisters a `blur` event handler from the actionButton | | ||
| | `registerVisibilityChangeHandler(handler: EventListener) => void` | Registers an event handler to be called when a 'visibilitychange' event occurs | | ||
| | `deregisterVisibilityChangeHandler(handler: EventListener) => void` | Deregisters an event handler to be called when a 'visibilitychange' event occurs | | ||
| | `registerCapturedInteractionHandler(evtType: string, handler: EventListener) => void` | Registers an event handler to be called when the given event type is triggered on the `body` | | ||
|
There was a problem hiding this comment. Nit: should we call it There was a problem hiding this comment. I don't think so. What this name suggests is that we are doing something with an interaction that has previously been captured (albeit immediately after). I agree we should be acknowledging that we are listening during the capture phase. 👍 |
||
| | `deregisterCapturedInteractionHandler(evtType: string, handler: EventListener) => void` | Deregisters an event handler from the `body` | | ||
| | `registerActionClickHandler(handler: EventListener) => void` | Registers an event handler to be called when a `click` event is triggered on the action element. | | ||
| | `deregisterActionClickHandler(handler: EventListener) => void` | Deregisters an event handler from a `click` event on the action element. This will only be called with handlers that have previously been passed to `registerActionClickHandler` calls. | | ||
| | `registerTransitionEndHandler(handler: EventListener) => void` | Registers an event handler to be called when an `transitionend` event is triggered on the root element. Note that you must account for vendor prefixes in order for this to work correctly. | | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: Could we also document it will throw an error in that case?