Skip to content

Switch Specification

Jump to bottom
Radoslav Karaivanov edited this page Jul 23, 2021 · 9 revisions

Switch Specification

Contents

  1. Overview
  2. User Stories
  3. Functionality
  4. Test Scenarios
  5. Accessibility

Owned by

Team Name: Design and Web Development (DnD)

Developer: Silvia Ivanova

Designer: Stefan Ivanov

Requires approval from

  • Simeon Simeonov | Date:
  • Stefan Ivanov | Date: 20 Jul 2021

Signed off by

  • Product Owner: Radoslav Mirchev | Date:
  • Radoslav Karaivanov | Date: July 23, 2021

Revision History

Version Users Date Notes
1 Silvia Ivanova Date 16 July 2021 Update specification

1. Overview

The <igc-switch> component is used to provide a capability for making a binary choice of a single settings option.

Objectives

It is providing API for the most common use cases when it comes to a binary choice for a certain condition. The <igc-switch> component should also provide ways to set and get its validity when used in the context of Forms.

Acceptance criteria

  1. The switch component should have a toggle visual representation.
  2. The switch component should be identifiable via a property, like name.
  3. The switch component should represent a unit of information, like value.
  4. The switch component should provide a way to be disabled.
  5. The switch component should provide a way to be a required field.
  6. The switch component should have the ability to add a corresponding label (before or after).
  7. The switch component should be interacted via mouse and/or keyboard.
  8. The switch component should be accessible.
  9. The switch component should emit an event when it gains focus.
  10. The switch component should emit an event when it loses focus.
  11. The switch component should emit an event when its checked status changes.
  12. The switch component should be able to report validation errors in the context of web forms.

2. User Stories

Developer stories:

  • Story 1: As a developer, I want to be able to provide a way to display a binary choice - true or false.
  • Story 2: As a developer, I want to be able to name the switch, so that I can easily identify it when used with other selection controls of the same type.
  • Story 3: As a developer, I want to be able to set the value of the switch, so that I can associate a piece of information with it.
  • Story 4: As a developer, I want to be able to specify the default state of the switch - checked or unchecked.
  • Story 5: As a developer, I want to be able to disable the switch, so that the user cannot change its state.
  • Story 6: As a developer, I want to be able to place content between the opening and closing brackets of the switch component, so that it can be used as a corresponding label.
  • Story 7: As a developer, I want to be able to position the label of the switch either before or after the control, so that it better suits the design.
  • Story 8: As a developer, I want to be able to programmatically click the switch, so that I can interact with it via means other than a computer mouse.
  • Story 9: As a developer, I want to be able to programmatically focus the switch, so that I can manually trigger the focus event.
  • Story 10: As a developer, I want to be able to programmatically blur the switch, so that I can manually trigger the blur event.
  • Story 11: As a developer, I want to be able to listen to blur, focus, and change events, so that I can better manage the state of the switch component.
  • Story 12: As a developer, I want to be able to check the validity of the switch, so that I can handle form errors and/or warnings.
  • Story 13: As a developer, I want to be able to set a custom validation message, so that the users can easily identify and fix form errors and/or warnings.
  • Story 14: As a developer, I want to be able to customize the appearance of the switch component, so that it better fits the design language of my application.

End-user stories:

  • Story 1: As an end-user, I want to be shown a visual representation of certain state changes.
  • Story 2: As an end-user, I want to be able to identify if a switch is disabled or not.
  • Story 3: As an end-user, I want to be able to identify if a switch is checked or not.
  • Story 4: As an end-user, I want to be able to identify the option I am selecting via label or some other visual aid.
  • Story 5: As an end-user, I want to be able to identify if my selection is valid.

3. Functionality

3.1. End-User Experience

The switch component displays a toggle changing the state of a single settings option. When selected, the switch thumb (a small circle) moves from left to right and changes the color of the component. It comes with an optional corresponding label that can be position either before or after the selection control. The user can click on both the circle and the label to change the state of the switch.

3.2. Developer Experience

<igc-switch value="checked switch" checked disabled label-position="before">
Checked Switch
</igc-switch>

3.3. API

Properties

You should be able to configure the igc-switch by setting its properties:

Name Description Type Default value Reflected
name Sets the name of the switch string - false
value Sets the value of the switch string - false
checked Sets the initial state of the switch boolean false true
disabled Sets the accessibility state of the switch boolean false true
required Makes the switch a required field boolean false true
invalid Sets the validity of the switch boolean false true
labelPosition Sets the label postion of the switch Before / After after true
ariaLabel Sets the aria-label of the native input. string - false
ariaLabelledby Sets the aria-labelledby of the native input. string - false

Events

The igc-switch should emit the following events:

Name Description Type
igcChange Emitted when the switch changes its checked state -
igcFocus Emitted when the switch gains focus -
igcBlur Emitted when the switch loses focus -

Methods

The igc-switch exposes the following methods:

Name Description Arguments
click Simulates a click on the switch. -
focus Sets focus on the switch. options: FocusOptions
blur Removes focus from the switch. -
reportValidity Checks for validity and shows the browser's validation message if the control is invalid. -
setCustomValidity Sets a custom validation message. If message is not empty, the field will be considered invalid. message: string

Slots

Name Description
(default) The switch label.

CSS Parts

Name Description
base The base wrapper of the switch.
control The switch control.
thumb The position indicator of the switch.
label The switch label.

4. Test Scenarios

Automation

  • Scenario 1: Should change the switch checked state correctly.
  • Scenario 2: Should change the switch disabled state correctly.
  • Scenario 3: Should set the switch required option correctly.
  • Scenario 4: Should position the switch label correctly.
  • Scenario 5: Should set the switch validity correctly.
  • Scenario 6: Should emit event when the switch checked state changes.
  • Scenario 7: Should emit events when the switch gains or loses focus.

5. Accessibility

Clone this wiki locally