Skip to content

Radio Specification

Jump to bottom
Simeon Simeonoff edited this page Jul 16, 2021 · 12 revisions

Contents

  1. Overview
  2. User Stories
  3. Functionality
  4. Test Scenarios
  5. Accessibility
  6. Assumptions and Limitations
  7. References

Owned by

Team Name: Design and Web Development (DnD)

Developer: Simeon Simeonoff

Designer: Stefan Ivanov

Requires approval from

  • Diyan Dimitrov | Date:

Signed off by

  • Product Owner: Radoslav Mirchev | Date:
  • Radoslav Karaivanov | Date:

Revision History

Version Users Date Notes
1 Simeon Simeonoff Date 16 Jul 2021 Initial Proposal

1. Overview

The igc-radio component renders a single radio button. Radio buttons aren't useful on their own and are usually a part of a bigger unit or group (see igc-radio-group) of radio buttons.

Objectives

Provide an API for the most common use cases when selecting an option from a set of available options. The igc-radio button should also provide ways to set and get its validity when used in the context of Web Forms.

Acceptance criteria

  1. The radio button component should be identifiable via a property, like name.
  2. The radio button component should represent a unit of information, like value.
  3. The radio button component should provide a way to be disabled.
  4. The radio button component should be interacted with via mouse and/or keyboard.
  5. The radio button component should be accessible.
  6. The radio button component should have an optional label.
  7. The radio button component should emit an event when it gains focus.
  8. The radio button component should emit an event when it loses focus.
  9. The radio button component should emit an event when its checked status changes.
  10. The radio button 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 name the radio button so that I can easily identify it in when used with other buttons of the same type.
  • Story 2: As a developer, I want to be able to set the value of the radio button so that I can associate a piece of information with a it.
  • Story 3: As a developer, I want to be able to disable the radio button so that the user is not able to select that button.
  • Story 4: As a developer, I want to be able to change the checked state of the radio button declaratively so that the button is selected at initialization.
  • Story 5: As a developer, I want to be able to change the invalid state of the radio button declaratively so that I set set its validity at initialization.
  • Story 6: As a developer, I want to be able to programmatically click the radio button so that I can interact with it via means other than a computer mouse.
  • Story 7: As a developer, I want to be able to programmatically focus the radio button so that I can manually trigger focus.
  • Story 8: As a developer, I want to be able to programmatically blur the radio button so that I can manually trigger blur.
  • Story 9: 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 radio button.
  • Story 10: As a developer, I want to be able to check the validity of the radio button so that I can handle form errors and/or warnings.
  • Story 11: As a developer, I want to be able to set a custom validation message so that the users of the radio button can easily identify and fix form errors and/or warnings.
  • Story 12: As a developer, I want to be able to customize the appearance of the radio button so that it better fits the design language of my application.

End-user stories

  • Story 1: As an end-user, I want to be able to identify if a radio button is disabled or not.
  • Story 2: As an end-user, I want to be able to select a radio button in a group of other buttons via the arrow keys on my keyboard or my computer mouse.
  • Story 3: As an end-user, I want to be able to able to differentiate between selected and deselected radio buttons.
  • 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 radio button component is small and circular in shape. When selected it is represented by a concentric circle with two rings where the inner ring is filled. A deselected radio button is represented by a single outlined circle. The radio button can have an optional label that makes it easy do identify when used in a radio group. The user can click on either the circle or the label to select the radio button. Navigating between radio buttons in a group using the arrow keys on a keyboard also changes the currently selected radio button.

3.2. Developer Experience

3.2.1 Standalone Usage (impractical):

<igc-radio value="banana" checked>Label</igc-radio>

3.2.2 Group Usage (intended):

<igc-radio-group>
  <igc-radio value="apple" checked>Apple</igc-radio>
  <igc-radio value="banana">Banana</igc-radio>
  <igc-radio value="mango">Mango</igc-radio>
  <igc-radio value="orange" disabled>Orange</igc-radio>
</igc-radio-group>

3.3 API

3.3.1 Properties

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

Name Description Type Default value Reflected
name Sets the name of the radio button. string - false
value Sets the value of the radio button. string - false
checked Sets the checked state of the radio button. Boolean false true
disabled Sets the disabled state of the avatar. Boolean false true
invalid Sets the validity of the radio button. Boolean false true
3.3.2 Events

The igc-radio emits the following events:

Name Description Type
igc-focus Emitted when the radio button gains focus. -
igc-blur Emitted when the radio button loses focus. -
igc-change Emitted when the radio button changes its checked state -
3.3.3 Events

The igc-radio exposes the following methods:

Name Description Arguments
click Simulates a click on the radio button. -
focus Sets the radio on focus. options: FocusOptions
blur Removes the focus from the radio -
reportValidity Checks for validity and shows a validation message if the component is invalid. -
setCustomValidity Sets a custom validation message. If message is not empty, the field will be considered invalid. message: string
3.3.4 Slots
Name Description
(default) The radio label.
3.3.5 CSS Parts
Name Description
base The radio button base wrapper.
control The radio button control.
label The radio button label.

4. Test Scenarios

5. Accessibility

Aria attributes set on the input control:

Clone this wiki locally