Simplified markup for checkbox, radio, range, and toggle

[liamdebeasi]

Definitions

Impacted Components: ion-checkbox, ion-radio, ion-range, ion-toggle
Form Control/Form Component: A single impacted component such as ion-checkbox or ion-toggle.

Summary

We would like to make the following changes to the impacted components:

1. Move the label inside of the form component so that the label and control are contained within a single shadow root.
2. Move form-specific features currently on ion-item onto the appropriate form components.
3. Remove form control interactions and behaviors that exist in the ion-item code.

Motivation

Form components in Ionic are impacted by multiple issues:

1. Screen readers announce form controls twice. Axe also warns of "nested form interactive" errors:
   bug: axe DevTools reports several items as "not announced by screen reader"  #23511
   bug: Checkbox touch target issue when there is a link in the text - A11y issue  #23289
   bug: adding aria labels to host and input element inside shadow root causes issues with nvda #23213
   bug: AXE: Elements must use only allowed ARIA attributes for ion-select #22715

2. Form components are tightly coupled with ion-item leading to unexpected behaviors:
   bug: Angular ion-item combined with stacked ion-label loses item-label-stacked class once ion-chip is added #24312
   bug: ion-chip is disabled when ion-input is disabled when both are in same ion-item #23331
   bug: Ion-input is broken with 4.7.x #19084
   bug: ion-label inside ion-item aligns wrongly or disappers if custom Angular component is used in this ion-item when stacked or floating position is set #22736
   bug: ion-button inside of an ion-label not clickable in v6 #24215
   bug: delegatesFocus patch for ios causes rendering issues with item sliding in chrome #25273

3. Form component usage is verbose and requires both ion-item and ion-label in order to behavior correctly.

Proposed Design

We would like to move all form component APIs from ion-item onto the form components themselves. The following changes will be made:

1. The affected form components will receive a slot that can be used to specify the label.
2. A property will be added to each form component to let developers control the position of the label.
3. A property will be added to each form component to let developers control how the label and control are justified within a line.
4. For components that do not need a visible label, developers will be able to set aria-label to ensure the form control remains accessible.
5. Helper and error text slots will be added to the impacted form components.

The following image highlights how the label placement and justification features can be used:

Old Usage:

<ion-radio-group value="pepperoni">
  <ion-item>
    <ion-label>Pepperoni</ion-label>
    <ion-radio slot="start" value="pepperoni"></ion-radio>
  </ion-item>
  
  <ion-item>
    <ion-label>Sausage</ion-label>
    <ion-radio slot="start" value="sausage"></ion-radio>
  </ion-item>
  
  <ion-item>
    <ion-label>Pineapple</ion-label>
    <ion-radio slot="start" value="pineapple"></ion-radio>
  </ion-item>
</ion-radio-group>

<ion-item>
  <ion-label>Receive email notifications?</ion-label>
  <ion-toggle></ion-toggle>
  <span slot="helper">We will definitely sell your email on the dark web</span>
</ion-item>

New Usage:

<ion-radio-group value="pepperoni">
  <ion-radio label-placement="end" justify="start" value="pepperoni">Pepperoni</ion-radio>
  <ion-radio label-placement="end" justify="start" value="sausage">Sausage</ion-radio>
  <ion-radio label-placement="end" justify="start" value="pineapple">Pineapple</ion-radio>
</ion-radio-group>

<ion-toggle>
  Receive email notifications?
  <span slot="helper">We will definitely sell your email on the dark web.</span>
</ion-toggle>

Notable Changes:

1. ion-item and ion-label are no longer used.
2. The label and helper text has been moved inside of the form control.
3. The label-placement property displays the label after the radio (as opposed to before the radio).
4. The justify property packs both the label and the radio at the start of the line.

Benefits

1. There is less boilerplate required to get form components added to Ionic apps.
2. It is clear which properties apply to which form components.
3. Decouples form components from ion-item, allowing the Ionic team to provide for a more predictable user experience.

Drawbacks

1. This is a significant change to how developers have typically used form components.

Migration Path and Breaking Changes

This change would ship in Ionic 7.0 at the earliest. We would like to support both the old usage and the new usage for the entire Ionic 7 lifecycle. This will allow developers to migrate their form components at their own pace. It will also reduce the barrier to upgrading to Ionic 7.0.

The following features will be deprecated in Ionic 7.0:

1. The helper and error slots on ion-item
2. Any form component-specific logic and functionality in ion-item

Note: We do not plan to make any breaking changes in Ionic 7.0 as a result of this proposal.

The following features will be removed in Ionic 8.0 at the earliest:

1. The helper and error slots on ion-item
2. Any form component-specific logic and functionality in ion-item

[liamdebeasi]

Hi everyone,

Thank you for your feedback on this RFC! We will be moving forward with this proposed change in an upcoming release of Ionic Framework.