content: document focusable classes and usage

FabianGutierrezOpengov commented 7 months ago

Prerequisites

[X] I have read the Contributing Guidelines.
[X] I agree to follow the Code of Conduct.
[X] I have searched for existing issues that already report this problem, without success.

Ionic Framework Version

v6.x, v7.x

Current Behavior

.ion-focused nor :focus-visible selector is working for ion-toggle component and toggle/labels combo.

There are workarounds for this but not optimal

use ion-item, but ion-item is expected to be used under restricted scenarios
use :focus selector but causes the style for accessibility leak when non-keyboard focus is applied.

Expected Behavior

ion-toggle should provide a default keyboard focus accessibility style.
ion-toggle should expose a way to set custom focus accessibility style

Steps to Reproduce

go to https://stackblitz.com/edit/ionic-ion-toggle-focus-isse
use keyboard to navigate.
background of focus-visible element SHOULD BE RED, similar to the button

Code Reproduction URL

https://stackblitz.com/edit/ionic-ion-toggle-focus-isse

Ionic Info

Ionic:

Ionic CLI : 7.1.1 Ionic Framework : @ionic/angular 6.2.7 @angular-devkit/build-angular : 17.1.1 @angular-devkit/schematics : 17.1.1 @angular/cli : 17.1.1 @ionic/angular-toolkit : 7.0.0

Capacitor:

Capacitor CLI : 5.2.3 @capacitor/android : 5.2.3 @capacitor/core : 5.2.3 @capacitor/ios : 5.2.3

Utility:

cordova-res : not installed globally native-run : 1.7.4

System:

NodeJS : v20.11.0 (C:\Program Files\nodejs\node.exe) npm : 10.2.4 OS : Windows 10

Additional Information

No response

sean-perkins commented 6 months ago

Hello @FabianGutierrezOpengov thanks for reporting this.

Can you share more about the desired styling you are trying to accomplish?

:focus-visible is only applied when the element is the element that receives focus. In the case of web components, that can be an element within the shadow dom. This means applying :focus-visible on the host element, will not apply. This can be illustrated in this codepen: https://codepen.io/sean-perkins/pen/PoLrbXY. When tabbing to the button, the inner styles that target the element that receives focus is applied, however the styles on the component host are not.

ion-item is currently using an option to delegate focus from the content inside the shadow dom to the host element: https://github.com/ionic-team/ionic-framework/blob/e440051764fa6224a67224ef2b473ce7d51a9174/core/src/components/item/item.tsx#L35-L37

If I can better understand what your styling needs are, I can better determine if that approach makes sense here.

Thanks!

sean-perkins commented 6 months ago

Hello @FabianGutierrezOpengov, I followed up with the team further. I believe the ion-focusable class is what you are requiring.

<style>
ion-toggle.ion-focused {
  background-color: red;
}
</style>
<ion-toggle class="ion-focusable">Default Toggle</ion-toggle>

Demo: https://stackblitz.com/edit/ionic-ion-toggle-focus-isse-udrveu?file=index.html,theme%2Fvariables.css

By adding ion-focusable to the element, you can then use the .ion-focused selector instead of :focus-visible.

Let me know if this resolves your problem.

FabianGutierrezOpengov commented 6 months ago

@sean-perkins that seems to work wonderfully. thanks. now Im embarrased because I didnt see this helper before

I'd like request/suggest a change/improvement in documentation, after some investigation of what you mention I noticed that ion-focusable is documented here: https://ionic.io/docs/accessibility/keyboard but trying to google it with keywords like ion-focusable and ion-focused leads me usually yo this page https://ionicframework.com/docs/developing/managing-focus which is unrelated?

and now im confused because I see docs under a ionicframework.com and ionic.io? 👀 😅

Would be good if ion toggle provides a example of this helper class in their main documentation here https://ionicframework.com/docs/api/toggle at the accessibility section and/or explaining the ion-focusable utility under their own heading so SEO can do their job properly.

T

sean-perkins commented 6 months ago

@FabianGutierrezOpengov great call out! I also was not clear on where the information was located and search results directed me to the same page without the information.

I'll update the documentation and cross link where possible 👍

ionic-team / ionic-docs