refactor(menu): add comments

Author: thetaPC

core/src/components/menu/menu.tsx

@@ -8,6 +8,7 @@ import type { Attributes } from '@utils/helpers';
 import { inheritAriaAttributes, assert, clamp, isEndSide as isEnd } from '@utils/helpers';
 import { menuController } from '@utils/menu-controller';
 import { BACKDROP, GESTURE, getPresentedOverlay } from '@utils/overlays';
+import { isPlatform } from '@utils/platform';
 import { hostContext } from '@utils/theme';
 
 import { config } from '../../global/config';
@@ -631,8 +632,22 @@ export class Menu implements ComponentInterface, MenuI {
   private beforeAnimation(shouldOpen: boolean, role?: string) {
     assert(!this.isAnimating, '_before() should not be called while animating');
 
-    // add aria-hidden to the menu
-    this.el.setAttribute('aria-hidden', 'true');
+    /**
+     * When the menu is presented on an Android device, TalkBack's focus rings
+     * may appear in the wrong position due to the transition (specifically
+     * `transform` styles). This occurs because the focus rings are initially
+     * displayed at the starting position of the elements before the transition
+     * begins. This workaround ensures the focus rings do not appear in the
+     * incorrect location.
+     *
+     * If this solution is applied to iOS devices, then it leads to a bug where
+     * the overlays cannot be accessed by screen readers. This is due to
+     * VoiceOver not being able to update the accessibility tree when the
+     * `aria-hidden` is removed.
+     */
+    if (isPlatform('android')) {
+      this.el.setAttribute('aria-hidden', 'true');
+    }
 
     // this places the menu into the correct location before it animates in
     // this css class doesn't actually kick off any animations
@@ -690,12 +705,18 @@ export class Menu implements ComponentInterface, MenuI {
     }
 
     if (isOpen) {
+      /**
+       * When the menu is presented on an Android device, TalkBack's focus rings
+       * may appear in the wrong position due to the transition (specifically
+       * `transform` styles). The menu is hidden from screen readers during the
+       * transition to prevent this. Once the transition is complete, the menu
+       * is shown again.
+       */
+      this.el.removeAttribute('aria-hidden');
+
       // emit open event
       this.ionDidOpen.emit();
 
-      // remove aria-hidden from menu
-      this.el.removeAttribute('aria-hidden');
-
       /**
        * Move focus to the menu to prepare focus trapping, as long as
        * it isn't already focused. Use the host element instead of the