Button Group Specification

Button group and toggle button specification

• Button group and toggle button specification
  • Owned by
    • Requires approval from
    • Signed off by
    • Revision history
  • Toggle button
    • Overview
      • Acceptance criteria
    • User stories
    • Functionality
      • End-user experience
      • Developer experience
        • Basic usage
        • With slotted content
      • Localization
      • Keyboard navigation
    • API
      • Properties
      • Methods
      • Slots
      • CSS Shadow Parts
    • Test scenarios
    • Accessibility
      • ARIA
      • RTL support
    • Assumptions and limitations
  • Button group
    • Overview
    • Acceptance criteria
    • User stories
    • Functionality
      • End-user experience
      • Developer experience
        • Default initialization
        • Vertical orientation
        • Initialization with multiple selection enabled
        • Initial selection through child
        • Initial selection through selected-items attribute
      • Localization
      • Keyboard navigation
    • API
      • Properties
      • Events
      • Slots
      • CSS parts
    • Test scenarios
    • Accessibility
      • ARIA
      • RTL
    • Assumptions and limitations

Owned by

Team name: Astrea

Developer name: Riva Ivanova

Designer name: Marin Popov

Requires approval from

• Radoslav Karaivanov | Date: 2023-09-28
• Svilen Dimchevski | Date:

Signed off by

• Radoslav Mirchev | Date:
• Damyan Petev | Date:

Revision history

Version	Author	Date	Notes
1	Radoslav Karaivanov	2023-08-08	Initial version of the specification
2	Radoslav Karaivanov	2023-09-12	Updated specification

Toggle button

Overview

An <igc-toggle-button> wraps a native button element and exposes additional value and selected properties. It is used in the context of an <igc-button-group> to facilitate the creation of group/toolbar like UX behaviors.

Acceptance criteria

The igc-toggle-button:

• must support user provided slotted content.
• must expose a disabled property which is controlled through an attribute and must have a visual state reflecting its disabled state.
• must expose a selected property which is controlled through an attribute and must have a visual state reflecting its selected state.
• must expose a value property which is controlled through an attribute.
• must support vertical sizing based on its parent igc-button-group or by setting an explicit CSS variable on the element itself.
• must follow the WAI-ARIA guidelines as closely as possible and be accessible with both keyboard and pointer devices.

User stories

Developer stories:

As a developer I expect to be able to:

• set a selected attribute so that the component can be programmatically initialized or updated based on external factors
• set a value attribute so that I can use that value when an end-user interacts with the component
• slot content in the exposed component slots so I can achieve customization in scenarios where additional visual indication is needed or certain design guidelines are required

End-user stories:

As an end-user I expect to be able to:

• have distinct visual indication reflecting the current state of the element (selected, disabled)
• interact with the control with keyboard and pointer devices

Functionality

End-user experience

Design hand-off

Developer experience

The <igc-toggle-button> is used in combination with the <igc-button-group> component to achieve toolbar like UX.

Basic usage

<igc-button-group>
  <igc-toggle-button value="1">First</igc-toggle-button>
  <igc-toggle-button value="2">Second</igc-toggle-button>
  <igc-toggle-button value="3">Third</igc-toggle-button>
</igc-button-group>

With slotted content

Emulating a text formatting toolbar:

<igc-button-group selection="multiple">
  <igc-toggle-button aria-label="Bold" value="bold">
    <igc-icon name="bold"></igc-icon>
  </igc-toggle-button>
  <igc-toggle-button aria-label="Italic" value="italic">
    <igc-icon name="italic"></igc-icon>
  </igc-toggle-button>
  <igc-toggle-button aria-label="Underline" value="underline">
    <igc-icon name="underline"></igc-icon>
  </igc-toggle-button>
</igc-button-group>

Localization

No specific points are applicable for localization.

Keyboard navigation

No additional implementation is required.

API

Properties

Property	Attribute	Reflected	Type	Default	Description
disabled	disabled	Yes	boolean	false	Determines whether the button is disabled.
selected	selected	Yes	boolean	false	Determines whether the button is selected.
value	value	No	string		The value attribute of the control.

Methods

Method	Type	Description
blur	(): void	Removes focus from the button.
click	(): void	Simulates a mouse click on the element.
focus	(options?: FocusOptions): void	Sets focus on the button.

Slots

Name	Description
(default)	Renders the label/content of the button.

CSS Shadow Parts

Part	Description
toggle	The native button element.

Test scenarios

Automation

1. The action button is correctly rendered.
2. The action button is correctly initialized with its default component state.
3. The action button passes automated WAI-ARIA tests.
4. The action button disabled state can be toggled and is correctly reflected.
5. The action button selected state can be toggled and is correctly reflected.

Accessibility

ARIA

• <igc-toggle-button> transfers its aria-label attribute, if present, to the native button element.
• <igc-toggle-button> sets the aria-pressed attribute value of the underlying native button based on its current selected state.

RTL support

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

Assumptions and limitations

None applicable.

Button group

Overview

The igc-button-group groups a series of igc-toggle-buttons together, exposing features such as layout and selection.

Acceptance criteria

The <igc-button-group> must support the following features out-of-the-box.

1. Supports slotting of igc-toggle-button(s) inside it.
2. Support for horizontal and vertical layout orientation for the slotted igc-toggle-button(s) inside it.
3. Support for controlling the type of selection; single (default), single required and multiple.
4. Support for setting and managing selection state, both declaratively (attribute) and through API (property).
5. Support for setting the disabled state of all projected buttons under the component.
6. Supports sizing the underlying buttons through a CSS variable.
7. Follows the WAI-ARIA guidelines as closely as possible.

User stories

Developer stories:

As a developer I expect to be able to:

• create a button group with slotted igc-toggle-button(s).
• control the layout and orientation of elements projected into the group.
• set a disabled attribute so that the control and its children can't be modified or interacted with.
• control the selection behavior (single/single-required/multiple).
• set/get the current selection either through an attribute on the button group or through attribute(s) on its children.

End-user stories:

As an end-user I expect to be able to:

• have distinct visual indication reflecting the different states the control is in (selected, disabled, etc.)
• interact with the control with keyboard and with a pointer device

Functionality

The end-users must be able to select button(s) from the group, through pointer device and keyboard, based on the selection mode of the component. The igc-button-group comes fully styled in accordance with the currently active theme.

End-user experience

Design hand-off

Developer experience

Events are emitted when a user interacts with an underlying igc-toggle-button, that is either through a pointer click or a Space/Enter key being pressed on a child button.

Changing the selected property of an underlying igc-toggle-button is reflected in the selection state of the group. However that operation does not emit an event.

On initial render any selected attributes present on the underlying buttons will take priority over the selected-items attribute of the button group.

On initial render if the selection mode is either single or single-required and there are multiple selected buttons underneath, only the last one will remain selected.

When the selection mode is set to single-required, the button group behaves similar to a radio group. That is once there is a selected button, it cannot be deselected through user interactions.

When the selection mode is set to single-required, interacting with the already selected button will not emit any events.

Runtime changes to the selection property of the group will remove the current selection state of the component.

Default initialization

<igc-button-group>
  <igc-toggle-button value="left">Left</igc-toggle-button>
  ...
</igc-button-group>

Vertical orientation

<igc-button-group alignment="vertical">
  <igc-toggle-button value="left">Left</igc-toggle-button>
  ...
</igc-button-group>

Initialization with multiple selection enabled

<igc-button-group selection="multiple">
  <igc-toggle-button value="left">Left</igc-toggle-button>
  ...
</igc-button-group>

Initial selection through child

<igc-button-group>
  <igc-toggle-button value="left" selected>Left</igc-toggle-button>
  <igc-toggle-button value="center">Center</igc-toggle-button>
  <igc-toggle-button value="right">Right</igc-toggle-button>
</igc-button-group>

Initial selection through selected-items attribute

<igc-button-group selected-items='["left"]'>
  <igc-toggle-button value="left">Left</igc-toggle-button>
  <igc-toggle-button value="center">Center</igc-toggle-button>
  <igc-toggle-button value="right">Right</igc-toggle-button>
</igc-button-group>

Localization

No specific points are applicable for localization.

Keyboard navigation

No additional implementation is required.

API

Properties

Property	Attribute	Reflected	Type	Default	Description
disabled	disabled	Yes	boolean	false	Disables all buttons inside the group
alignment	alignment	Yes	"horizontal" | "vertical"	"horizontal"	Sets the orientation of the buttons in the group
selection	selection	No	"single" | "single-required" | "multiple"	"single"	Controls the mode of selection for the button group
selectedItems	selected-items	No	string[]	[]	Gets/Sets the currently selected buttons (their values)

Events

Name	Description	Cancelable	Parameters
igcSelect	Emitted when a button is selected through user interaction	No	The value of the button
igcDeselect	Emitted when a button is deselected through user interaction	No	The value of the button

Slots

Name	Description
(default)	Renders igc-toggle-button component.

CSS parts

Name	Description
group	The button group container.

Test scenarios

Automation

• should initialize a button group
• should initialize a button group with initial selection state through attribute (single/multiple)
• should initialize a button group with initial selection state through children selection attribute (single/multiple)
• should be able to update selection state through group's selection property
• should be able to update selection state through the selected property of its children
• should be able to select only a single button through UI when selection is single
• should be able to select multiple buttons through UI when selection is multiple
• should not be able to interact through UI when the group is disabled
• event is correctly emitted on user interaction
• passes automated WAI-ARIA tests

Accessibility

ARIA

In order for assistive technologies (such as screen readers) to convey that a series of buttons is grouped, the igc-button-group should have by default its role set to group.

RTL

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

Assumptions and limitations

While virtually any element can be slotted inside the igc-button-group, it only operates over igc-toggle-button(s).