EWC Icon-button group Component

Overview

The EWC Icon-button group component provides standardized radiobuttons for Eurostat web applications. It offers a consistent visual identity across Eurostat digital products while allowing for customization to meet specific application needs.

Features

• Responsive design that adapts to different screen sizes
• Customizable (there are 4 buttons available, arbitrary order)
• Button group respects tri-state of button (pressed/not pressed/disabled)
• Accessibility compliant

Screenshot

Description

The component shows a group of icon-buttons, displayed in "pill-"design and behaving like radio-buttons - i.e. only one button can be in "pressed" state at any time.

The ewc-icon-button-group HTML tag encloses ewc-icon-buttons. It modifies their style, handles events and implements the logic.

Note that adding/removing children at runtime is not supported.

Regarding focus, arrow keys work alongside the tab key.

Within a button-group, only buttons that are not currently pressed and not disabled can be focussed.

API

Properties and Attributes

| Property | Attribute | Type | Default | Description |----------------|-----------------------|---------------------|---------|------------ | selectedIndex | selectedIndex | Number | 0 | The 0-based ordinal number of the button pressed. | selectedId | selectedId | Number | - | The id of the button pressed. Can be null if the id attribute is not set. | breakpoint | breakpoint | CSS String | 650px | if viewport width is smaller than this, the buttons are displayed without label. | selectedElement| | HTML element | - | The HTML element currently selected. Read only.

Notes:

• The attribute breakpoint does not support modification at runtime, all others do.
• The width of an ewc-icon-button (when used in conjunction with the ewc-icon-button-group) is determined as follows:
  • width of button-group < breakpoint: size or weight attribute of ewc-icon-button
  • width of button-group > breakpoint: 125px as per definition in the EWC standards

Enabling / Disabling

While selection is handled via attributes and properties, enabling/disabling is done with the following public member functions.

setEnabledById(id, isEnabled)
setEnabledByIndex(index, isEnabled)

• isEnabled is a boolean
• id is of type string
• index of type number

Caution

• ❗Refrain from setting state on a button directly when used in a group.
• This is because ewc-button-icon group is not aware of state changes it doesn't initiate itself.
• For the state "true" and "false", let ewc-button-icon handle this via selectedIndex or selectedId
• To disable a button, use setEnabledByIndex or setEnabledById
• Note that reading the state of a button is unproblematic - this note is just about setting the state.

Responsabilities

• Precaution has to be taken in case the button being disabled is the currently selected one.
  • The user of the component retains full control over what's happening in this case.
  • For instance, programmatically switching to another button before disabling a certain button.
    • And of course the effect such a button switch has in the host project / application.
• Disabling all buttons is technically supported.
  • But what that means in the context of the application is the user's responsability - the component can't know that.
  • In this case, the same applies - the user is responsible for setting a button when not all buttons are disabled anymore.

Example code for toggling between state "disabled" and "false"

const button = document.getElementById("myButton")
const group = document.getElementById("myButtonGroup")
group.setEnabledByIndex(0, button.state==="disabled")

❗ Don't miss to see also usage-examples/ directory for more examples, especially how to handle enable/disabling of a single button and also all buttons at once.

Events

• When a user attempts to press a button, a custom event named "action" is dispatched.
• The event detail contains the 0-based index of the button which was pressed.
  • It's the component user's responsability to actually set the button state to "pressed".
  • This is for two reasons:
    • provides possibility to prevent the button from being pressed
    • is consistent with the usage of the ewc-icon-button

Please see usage-examples/ directory which contains working source-code demonstrating how this works.

UML

Usage

Installation

npm install @ewc-lib/ewc-icon-button-group

Import the component in your application:

// Using ES modules
import "@ewc-lib/ewc-css-common/custom-props.css"
import '@ewc-lib/ewc-icon-button-group';

Note about ewc-css-common

• "ewc-css-common/custom-props.css" is necessary and downloaded along with this component.
• It needs to be imported by the host project because it's imported neither by ewc-icon-button nor ewc-icon-button-group.

Using in static HTML

Example:

<ewc-icon-button-group selectedIndex="1" breakpoint="1000px">
  <ewc-icon-button icon="linechart" use-config="grp-linechart" label="Line chart"></ewc-icon-button>
  <ewc-icon-button icon="barchart"  use-config="grp-barchart" label="Bar chart"></ewc-icon-button>
</ewc-icon-button-group>

To use a standard ewc-icon-button in the context of ewc-icon-button-group, use-config must be specified. For an explanation about the attribute use-config, please refer to the readme.md of ewc-icon-button.

Note: The usage-example/ directory contains a working example.

Migration guide

Updating to 3.0.0-alpha (from any older version)

Option to use ID instead of index

Referring to a button in a group can now be done via ID, additionally to the previously existing index.

ID in the event details

e.detail was only a number before (containing an ordinal index). Now it's an object w/ 2 fields: index and id.

document.getElementById("lightEnabled").addEventListener("action",(e)=>{
  console.log("button clicked or selected w/ kdb: ", e.detail.id, e.detail.index)
})

The ID is taken from the HTML tag's "id" attribute. If it's missing, e.detail.id is null.

Notes

Accessibility

The component is designed with accessibility in mind:

• Proper semantic HTML structure
• Keyboard navigable elements
• Sufficient color contrast
• Screen reader friendly with appropriate ARIA attributes

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

European Union Public License (EUPL)

Changelog

• 3.2.0-alpha

  • latest design

• 3.1.1-alpha

  • bugfix: id in action event contains id of previously selected element instead of currently clicked element

• 3.1.0-alpha

  • change config (colors) to match latest design

• 3.0.0-alpha

  • properly support disabled state,
  • add selection by id
  • add id-info to event
  • update usage examples
  • update documentation

• 2.0.3-alpha

  • fix label casing bug

• 2.0.2-alpha

  • support integration, update dependency, add aria-label

• 2.0.1-alpha

  • update icons: linechart, barchart, hilo-chart (dotplot), table

• 1.0.2-alpha

  • when pressed no checkmark displayed but keep the icon
  • introduce narrow width display
  • use peerDependencies
  • update docu

• 1.0.1-alpha

  • remove button label on narrow width
  • introduce attribute "breakpoint"