fix(checkbox,radio,toggle): add missing keyboard focus indicators

core/src/components/checkbox/checkbox.scss

@@ -1,4 +1,3 @@
-@import "../../themes/ionic.globals";
 @import "./checkbox.vars.scss";
 
 // Checkbox
@@ -119,9 +118,17 @@ input {
   display: none;
 }
 
+// The host is focusable, so the browser draws a native focus ring on it.
+// Suppress it in favor of the keyboard focus indicator.
+:host(:focus) {
+  outline: none;
+}
+
 .native-wrapper {
   display: flex;
 
+  position: relative;
+
   align-items: center;
 }
 
@@ -152,6 +159,29 @@ input {
   opacity: 0;
 }
 
+// Checkbox: Keyboard Focus
+// ---------------------------------------------
+
+:host(.ion-focused) .native-wrapper::after {
+  @include border-radius(50%);
+
+  display: block;
+  position: absolute;
+
+  width: 36px;
+  height: 36px;
+
+  transform: translate(-50%, -50%);
+
+  background: $checkbox-background-color-focused;
+
+  content: "";
+  opacity: 0.2;
+
+  inset-block-start: 50%;
+  inset-inline-start: 50%;
+}
+
 // Checkbox Bottom Content
 // ----------------------------------------------------------------
 

core/src/components/checkbox/checkbox.tsx

@@ -1,6 +1,6 @@
 import type { ComponentInterface, EventEmitter } from '@stencil/core';
-import { Build, Component, Element, Event, Host, Method, Prop, State, h } from '@stencil/core';
-import { checkInvalidState } from '@utils/forms';
+import { Build, Component, Element, Event, Host, Method, Prop, State, forceUpdate, h } from '@stencil/core';
+import { checkInvalidState, createItemMultipleInputsObserver } from '@utils/forms';
 import type { Attributes } from '@utils/helpers';
 import { inheritAriaAttributes, renderHiddenInput } from '@utils/helpers';
 import { createColorClasses, hostContext } from '@utils/theme';
@@ -37,6 +37,7 @@ export class Checkbox implements ComponentInterface {
   private errorTextId = `${this.inputId}-error-text`;
   private inheritedAttributes: Attributes = {};
   private validationObserver?: MutationObserver;
+  private itemFocusObserver?: MutationObserver;
 
   @Element() el!: HTMLIonCheckboxElement;
 
@@ -199,6 +200,10 @@ export class Checkbox implements ComponentInterface {
     // Always set initial state
     this.isInvalid = checkInvalidState(el);
     this.hasLabelContent = this.el.textContent !== '';
+
+    // Re-render when the item flips `item-multiple-inputs` so the focus
+    // indicator stays in sync.
+    this.itemFocusObserver = createItemMultipleInputsObserver(el, () => forceUpdate(this));
   }
 
   componentWillLoad() {
@@ -210,11 +215,15 @@ export class Checkbox implements ComponentInterface {
   }
 
   disconnectedCallback() {
-    // Clean up validation observer to prevent memory leaks.
+    // Clean up observers to prevent memory leaks.
     if (this.validationObserver) {
       this.validationObserver.disconnect();
       this.validationObserver = undefined;
     }
+    if (this.itemFocusObserver) {
+      this.itemFocusObserver.disconnect();
+      this.itemFocusObserver = undefined;
+    }
   }
 
   /** @internal */
@@ -338,6 +347,8 @@ export class Checkbox implements ComponentInterface {
     } = this;
     const mode = getIonMode(this);
     const path = getSVGPath(mode, indeterminate);
+    const inItem = hostContext('ion-item', el);
+    const inMultipleInputsItem = hostContext('ion-item.item-multiple-inputs', el);
 
     renderHiddenInput(true, el, name, checked ? value : '', disabled);
 
@@ -360,11 +371,15 @@ export class Checkbox implements ComponentInterface {
         onClick={this.onClick}
         class={createColorClasses(color, {
           [mode]: true,
-          'in-item': hostContext('ion-item', el),
+          'in-item': inItem,
           'checkbox-checked': checked,
           'checkbox-disabled': disabled,
           'checkbox-indeterminate': indeterminate,
           interactive: true,
+          // Focus styling should not apply when the checkbox is in an item,
+          // since the item handles the focus indicator instead. The exception
+          // is a multi-input item, which has no single indicator of its own.
+          'ion-focusable': !inItem || inMultipleInputsItem,
           [`checkbox-justify-${justify}`]: justify !== undefined,
           [`checkbox-alignment-${alignment}`]: alignment !== undefined,
           [`checkbox-label-placement-${labelPlacement}`]: true,

core/src/components/checkbox/checkbox.vars.scss

@@ -1,5 +1,10 @@
+@import "../../themes/ionic.globals";
+
 /// @prop - Top margin of checkbox's label when in an item
 $checkbox-item-label-margin-top: 10px;
 
 /// @prop - Bottom margin of checkbox's label when in an item
-$checkbox-item-label-margin-bottom: 10px;
+$checkbox-item-label-margin-bottom: 10px;
+
+/// @prop - Background color of focus indicator for checkbox when focused
+$checkbox-background-color-focused: ion-color(primary, tint);

core/src/components/checkbox/test/a11y/checkbox.e2e.ts

@@ -25,6 +25,70 @@ configs({ directions: ['ltr'], palettes: ['light', 'dark'] }).forEach(({ title,
   });
 });
 
+/**
+ * These tests assert the `ion-focusable` gating class the component controls,
+ * not the rendered focus ring. `ion-focused` is not asserted directly because
+ * it depends on keyboard-mode detection, which is unreliable on WebKit. The
+ * gating logic does not vary across modes.
+ */
+configs({ directions: ['ltr'], modes: ['md'] }).forEach(({ title, config }) => {
+  test.describe(title('checkbox: focus indicator'), () => {
+    test('standalone checkbox should be focusable', async ({ page }) => {
+      await page.setContent(
+        `
+        <ion-app>
+          <ion-checkbox aria-label="Checkbox">Checkbox</ion-checkbox>
+        </ion-app>
+      `,
+        config
+      );
+
+      const checkbox = page.locator('ion-checkbox');
+      await expect(checkbox).toHaveClass(/ion-focusable/);
+    });
+
+    test('checkbox in a single-input item should not show its own focus indicator', async ({ page }) => {
+      await page.setContent(
+        `
+        <ion-app>
+          <ion-item>
+            <ion-checkbox>Checkbox</ion-checkbox>
+          </ion-item>
+        </ion-app>
+      `,
+        config
+      );
+
+      // The item owns the focus indicator for single-input items, so the
+      // checkbox must not become focusable itself.
+      const checkbox = page.locator('ion-checkbox');
+      const item = page.locator('ion-item');
+      await expect(checkbox).not.toHaveClass(/ion-focusable/);
+      await expect(item).toHaveClass(/ion-focusable/);
+    });
+
+    test('checkbox in a multi-input item should be focusable', async ({ page }) => {
+      await page.setContent(
+        `
+        <ion-app>
+          <ion-item>
+            <ion-checkbox>Checkbox 1</ion-checkbox>
+            <ion-checkbox>Checkbox 2</ion-checkbox>
+          </ion-item>
+        </ion-app>
+      `,
+        config
+      );
+
+      // Multi-input items do not draw a single focus indicator, so each control
+      // must be able to show its own.
+      const checkboxes = page.locator('ion-checkbox');
+      await expect(checkboxes.nth(0)).toHaveClass(/ion-focusable/);
+      await expect(checkboxes.nth(1)).toHaveClass(/ion-focusable/);
+    });
+  });
+});
+
 configs({ directions: ['ltr'] }).forEach(({ title, config, screenshot }) => {
   test.describe(title('checkbox: a11y'), () => {
     test.describe(title('checkbox: font scaling'), () => {

core/src/components/checkbox/test/basic/checkbox.e2e.ts

@@ -47,7 +47,7 @@ configs().forEach(({ title, screenshot, config }) => {
 /**
  * This behavior does not vary across modes/directions
  */
-configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ title, screenshot, config }) => {
+configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ title, config }) => {
   test.describe(title('checkbox: ionChange'), () => {
     test('should fire ionChange when interacting with checkbox', async ({ page }) => {
       await page.setContent(
@@ -138,48 +138,6 @@ configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ title, screenshot, c
   });
 
   test.describe(title('checkbox: ionFocus'), () => {
-    test('should not have visual regressions', async ({ page, pageUtils }) => {
-      await page.setContent(
-        `
-        <style>
-          #container {
-            display: inline-block;
-            padding: 10px;
-          }
-        </style>
-
-        <div id="container">
-          <ion-checkbox>Unchecked</ion-checkbox>
-        </div>
-      `,
-        config
-      );
-
-      await pageUtils.pressKeys('Tab');
-
-      const container = page.locator('#container');
-
-      await expect(container).toHaveScreenshot(screenshot(`checkbox-focus`));
-    });
-
-    test('should not have visual regressions when interacting with checkbox in item', async ({ page, pageUtils }) => {
-      await page.setContent(
-        `
-        <ion-item class="ion-focused">
-          <ion-checkbox>Unchecked</ion-checkbox>
-        </ion-item>
-      `,
-        config
-      );
-
-      // Test focus with keyboard navigation
-      await pageUtils.pressKeys('Tab');
-
-      const item = page.locator('ion-item');
-
-      await expect(item).toHaveScreenshot(screenshot(`checkbox-in-item-focus`));
-    });
-
     test('should fire ionFocus when checkbox is focused', async ({ page, pageUtils }) => {
       await page.setContent(
         `
@@ -328,3 +286,80 @@ configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ title, screenshot, c
     });
   });
 });
+
+/**
+ * This behavior does not vary across directions
+ */
+configs({ directions: ['ltr'] }).forEach(({ title, screenshot, config }) => {
+  test.describe(title('checkbox: focus visual'), () => {
+    test('should render focus indicator when unchecked', async ({ page, pageUtils }) => {
+      // `ion-app` is required so `startFocusVisible` runs and applies the
+      // `ion-focused` class on keyboard focus, which drives the focus indicator.
+      await page.setContent(
+        `
+        <style>
+          #container {
+            width: fit-content;
+            padding: 10px;
+          }
+        </style>
+
+        <ion-app>
+          <div id="container">
+            <ion-checkbox>Unchecked</ion-checkbox>
+          </div>
+        </ion-app>
+      `,
+        config
+      );
+
+      const checkbox = page.locator('ion-checkbox');
+
+      // The focus listeners attach asynchronously, so the first Tab can miss
+      // them. Retry until `ion-focused` sticks before taking the snapshot.
+      await expect(async () => {
+        await page.evaluate(() => (document.activeElement as HTMLElement | null)?.blur());
+        await pageUtils.pressKeys('Tab');
+        await expect(checkbox).toHaveClass(/ion-focused/, { timeout: 250 });
+      }).toPass({ timeout: 5000 });
+
+      const container = page.locator('#container');
+
+      await expect(container).toHaveScreenshot(screenshot(`checkbox-focus`));
+    });
+
+    test('should render focus indicator when checked', async ({ page, pageUtils }) => {
+      await page.setContent(
+        `
+        <style>
+          #container {
+            width: fit-content;
+            padding: 10px;
+          }
+        </style>
+
+        <ion-app>
+          <div id="container">
+            <ion-checkbox checked>Checked</ion-checkbox>
+          </div>
+        </ion-app>
+      `,
+        config
+      );
+
+      const checkbox = page.locator('ion-checkbox');
+
+      // The focus listeners attach asynchronously, so the first Tab can miss
+      // them. Retry until `ion-focused` sticks before taking the snapshot.
+      await expect(async () => {
+        await page.evaluate(() => (document.activeElement as HTMLElement | null)?.blur());
+        await pageUtils.pressKeys('Tab');
+        await expect(checkbox).toHaveClass(/ion-focused/, { timeout: 250 });
+      }).toPass({ timeout: 5000 });
+
+      const container = page.locator('#container');
+
+      await expect(container).toHaveScreenshot(screenshot(`checkbox-focus-checked`));
+    });
+  });
+});