Skip to content

Dialog: Allow to put the dialog title in a heading element (h1-h6) #2271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
rpkoller opened this issue Jul 26, 2024 · 4 comments
Closed

Dialog: Allow to put the dialog title in a heading element (h1-h6) #2271

rpkoller opened this issue Jul 26, 2024 · 4 comments
Labels
Comp: Dialog
Milestone
1.14.1

Comments

@rpkoller
Copy link
Contributor

rpkoller commented Jul 26, 2024 •
edited
Loading

With #2246 the element in the background of the dialog are getting removed from the AOM. The problem the title is just wrapped in a span which isn't semantic. The title is properly announced when dialog is opened (tested on drupal) but if the content of that modal doesnt contain any heading elements if you open up the rotor in for example voiceover the headings section wont be available at all. this might be potentially confusing since you are unable to get the context the dialog is about. there are no headings available and with VO-shift-i you only get announced the title and stats of the hidden page not the dialog modal. technically you would have to step through the modal with the voiceover cursor since the title isnt focusable or close the modal and reopen it again to get it reannounced.

which element to use instead of the generic span is not specified in the wcag, see this comment for context
w3c/wcag#2722 (comment) . according to the comment an h1 or any other heading level element is perfectly fine. the aria apg example uses an h2 for example: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog/ while in a discussion on the a11y slack https://web-a11y.slack.com/archives/C042TSFGN/p1708471859401949 the recommendation by a few folks to go with an h1. with the modal dialog open only the content of the modal is accessible the overall heading structure of the page is irrelevant. and james scholes emphasized that the modal title should be h1. there is no reason to use an h2 since all it does is to take away one heading level from the modal content (james is a screen reader user).

i "think" i've raised the aspect of the html element wrapping the title before in the context of the linked issue or the corresponding PR but unable to find the detail. but since it is still debatable which heading level to pick as well as the aspect of backwards compatability i wonder if it would be feasible to make the html element wrapping the title configurable? so adding somthing like titleElement to the options and set it to "span" per default that way it would be a none breaking change. the user would be able to to change the element proactively via the options?
@mgol
Copy link
Member

mgol commented Jul 30, 2024

Thanks for the report. I'd rather avoid adding more options as then we need to maintain them indefinitely. Since h1 seems to be OK per your description, I'd try that.

It'd be good to get that into 1.14.0 just in case someone considers this a compatibility break.

Would you like to submit a PR? I think we'd just need updating the wrapping span to a h1 in the uiDialogTitle definition and maybe add a simple test checking that the title is wrapped in a h1.

@mgol mgol added this to the 1.14.0 milestone Jul 30, 2024
@mgol
Copy link
Member

mgol commented Jul 30, 2024

I've just realized we cannot do this for all dialogs as non-modal ones don't get the aria-modal attribute set so out-of-dialog headings are still available. This would have to be conditional on the aria-modal attribute - but the modal option that sets it can be set during runtime and you cannot change tagName of an existing element.

I guess adding an option like uiDialogTitleTagName would be the safest and also non-breaking.

I'll move this to the 1.14.1 milestone since I want to get the stable 1.14.0 out ASAP.

@mgol mgol modified the milestones: 1.14.0, 1.14.1 Jul 30, 2024
@mgol
Copy link
Member

mgol commented Jul 30, 2024

@fnagel what do you think?

@rpkoller
Copy link
Contributor Author

I've just realized we cannot do this for all dialogs as non-modal ones don't get the aria-modal attribute set so out-of-dialog headings are still available. This would have to be conditional on the aria-modal attribute - but the modal option that sets it can be set during runtime and you cannot change tagName of an existing element.

I guess adding an option like uiDialogTitleTagName would be the safest and also non-breaking.

I'll move this to the 1.14.1 milestone since I want to get the stable 1.14.0 out ASAP.

uhhh you are right. and another downside i've just realized for changing the title wrapper from a span to an h1 is the heading hierarchy. in case the dialog modal is using more heading elements within the dialog. having an h1 might lead to a second h1 or a gap in between heading level. or if an h2 would have been picked instead of the h1. you can never know the content users will apply in their dialogs. so yeah adding an option would be the safest and none breaking approach. i could create an initial PR (going with uiDialogTitleTagName for the option name)

@rpkoller rpkoller mentioned this issue Jul 31, 2024
Merged
@mgol mgol closed this as completed in d564731 Sep 9, 2024
@mgol mgol changed the title Make the uiDialogTitle configurable Dialog: Allow to put the dialog title in a heading element (h1-h6) Sep 9, 2024
mgol pushed a commit to jquery/api.jqueryui.com that referenced this issue Sep 9, 2024
@rpkoller
Dialog: Document the uiDialogTitleHeadingLevel option
61e425b 
Ref jquery/jquery-ui#2271
Ref jquery/jquery-ui#2275
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Comp: Dialog
Milestone
1.14.1
Development

No branches or pull requests
2 participants
@rpkoller @mgol