Snackbar Specification

Snackbar Specification

• Snackbar Specification
  • Owned by
  • Requires approval from
  • Signed off by
  • Revision History
  • Overview
    • Acceptance criteria
  • User stories
  • Functionality
    • End-user experience
    • Developer experience
      • Initialization
      • Additional notes
    • Localization
    • Keyboard navigation
  • API
    • Properties
    • Methods
    • Events
      • Slots
      • CSS Shadow Parts
  • Test Scenarios
  • Accessibility
    • ARIA
      • Animations
    • RTL
  • Assumptions and limitations

Owned by

Team Name: Design and Web Development (DnD)

Developer: Silvia Ivanova

Designer: Stefan Ivanov

Requires approval from

• Simeon Simeonov | Date:
• Stefan Ivanov | Date:

Signed off by

• Product Owner: Radoslav Mirchev | Date:
• Radoslav Karaivanov | 2 November 2023

Revision History

Version	Users	Date	Notes
1	Silvia Ivanova	20 January 2022	Update specification
2	Radoslav Karaivanov	2 November 2023	Added action slot. Updated specification.

Overview

A snackbar component is used to provide feedback about an operation by showing a brief message on the screen. It is usually non-interruptive to the user experience, thus it us displayed temporarily and closed without compulsory user action.

Acceptance criteria

1. The snackbar must support slotting user provided content.
2. The snackbar should support slotting additional action parts provided by the user.
3. The snackbar must be placed above all other viewport elements.
4. The snackbar should be positioned at the bottom of the viewport by default, unless configured otherwise.
5. The snackbar should disappear automatically by default.
6. The snackbar should support disabling auto-hide behavior when configured by the user.
7. The snackbar must emit an event, informing when an user has interacted with the default/slotted action part(s).
8. The snackbar must follow the design/theming guidelines imposed by the package.
9. It must follow the WAI-ARIA guidelines as closely as possible.

User stories

Developer stories:

As a developer I expect to be able to:

• to inform an end user about an application operation being executed/done by using the snackbar
• initialize a snackbar
• customize the content of the snackbar message through a slot
• show an interactive element if needed, either through the default snackbar action button or by providing my own through a slot
• react to end-user interaction with the action element by listening for an event
• control the snackbar visibility state, either through an attribute/property or through a method call
• adjust the auto hide duration of the snackbar
• control whether the snackbar will hide automatically
• control where the snackbar will position itself on the viewport when displayed
• customize the appearance of the snackbar component

Functionality

The snackbar component displays a rectangular container with a solid background and a shadow. By default it is positioned at the bottom of the viewport. It usually contains a single-line text message and an optional action element(s). The snackbar should be above all other screen elements and should be non-intrusive by default (non-modal and non-focus stealing). By default the component is hidden automatically after a certain time period passes or if configured, until the end-user interacts with it.

End-user experience

Design hand-off

Developer experience

Initialization

Default with slotted content

<igc-snackbar>...</igc-snackbar>

With default action button

<igc-snackbar action-text="OK">...</igc-snackbar>

With custom action slot

<igc-snackbar>
  ...
  <custom-button slot="action">...</custom-button>
</igc-snackbar>

Additional notes

• When showing/hiding the visibility state of the component through the open attribute, the default animations will not be triggered.
• Contrary, calling any of show/hide/toggle methods will trigger the respective animation.
• Setting a new value for displayTime while the component is being shown, will clear any auto-hide timers and start a new timeout with the passed value.
• When actionText is set, the default action button of the snackbar will be shown.
• When both actionText is set and the action slot has user provided content, the slotted content will take precedence.

Localization

No specific points are applicable for localization.

Keyboard navigation

No intrinsic implementation is required.

API

Properties

Property	Attribute	Modifiers	Type	Default	Description
open	open	Reflected	boolean	false	Whether the component is shown
displayTime	display-time	-	number	4000	Duration in ms in which the snackbar will be visible
keepOpen	keep-open	Reflected	boolean	false	Whether the component will auto hide after displayTime passes
position	position	Reflected	"bottom" | "middle" | "top"	bottom	Position of the snackbar in the viewport
actionText	action-text	-	string	-	When set, sets the text for the default action button and sets its text

Methods

Method	Params	Return type	Description
show	-	Promise<void>	Shows the snackbar with animation
hide	-	Promise<void>	Hides the snackbar with animation
toggle	-	void	Toggles between the shown/hidden state of the component

Events

Event	Args	Description
igcAction	-	Emitted when a click is registered in the action part of the snackbar

Slots

Name	Description
-	Default slot for the snackbar content
action	Renders the action part of the snackbar. Usually an interactive element (button)

CSS Shadow Parts

Part	Description
base	The base wrapper of the snackbar component
message	The snackbar content/message
action	The default snackbar action button
action-container	The container holding the actions

Test Scenarios

1. Should have correct DOM structure with no action(s) present.
2. Should have correct DOM structure with action(s) present.
3. Should project slotted content in the default slot.
4. Should project slotted content in the action slot.
5. Should abide by the value of displayTime before auto hiding.
6. Setting keepOpen should override any displayTime value.
7. Should control the visibility by setting open attribute.
8. Should control the visibility by calling show()/hide().
9. Should toggle the visibility by calling toggle().
10. Should emit igcAction event when clicking the default action button.
11. Should emit igcAction event when clicking a slotted action component.

Accessibility

As the snackbar is non-intrusive by design, it is non-focusable by default and it does not steal focus for itself or its children when shown. If that is a desired behavior, it is up to the developer to move focus after the snackbar is shown.

ARIA

role: status

aria-live: polite

These should cover the majority of use cases. Developers may override them by setting the appropriate ARIA attributes on the snackbar component.

Animations

The default snackbar animations take into account the prefers-reduced-motion media query, and when present, will complete immediately (duration of 0).

RTL

The component should work in a Right-To-Left context without additional setup or configuration.

Assumptions and limitations

None applicable.