search

PreTeXtBook / pretext

PreTeXt: an authoring and publishing system for scholarly documents
https://pretextbook.org
Other
254 stars 203 forks source link

Add a valid href to knowled xref's #2107

Closed ascholerChemeketa closed 3 months ago

ascholerChemeketa commented 4 months ago

Make sure a valid href is available for xref links in case knowl.js is not loaded.

<a href="./some-page.html" class="xref" data-knowl...

Instead of

<a href class="xref" data-knowl...

@davidfarmer - Question for David: The knowl code strips out the href of all xref knowls and ignores the default behavior of clicking on them. Thus I can't find any harm from having the href value there. Can you think of any weird situation where it might cause issues?

rbeezer commented 4 months ago

Code is fine - thanks. Will wait for @davidfarmer to check-off (just made him a reviewer).

More than just no JS. Places like the Runestone assignment page can decide if they want to have a link or support knowls. (In the present case, Runestone may just use links temporarily.) Also, a traditional link could be places in the "Ooops this knowl didn't load!" message.

Minor code formatting note - look out how comments are formatted, nice right margin. Maybe odd, but there you have it.

davidfarmer commented 4 months ago

I don't know if a screen reader or other AT might react to the presence of an href.

rbeezer commented 4 months ago

I don't know if a screen reader or other AT might react to the presence of an href.

Knew I was forgetting something. Maybe that would be a good thing? A screenreader user might be more comfortable following a link than whatever happens when a knowl is opened/closed?

We added @hef for accessibility reasons, and it is now empty. Surely whatever that does can only be worse?

Adding @Alex-Jordan as a reviewer for an accessibility opinion.

ascholerChemeketa commented 4 months ago

I believe that standard behavior for AT tools is to announce the name of the link, not the href. I can confirm that is what NVDA does. <a href="somewhere.com">Lemma 1.1.1</a> is pronounced as "Link to Lemma 1.1.1".

Like Rob, I have to believe that having a valid address can only help.

Accessibility-wise, I do think it would be good to distinguish knowl links from links. i.e. communicate that a particular link is going to add some content to the current page as opposed to navigating away (expected behavior for a link). Currently, they look the same to accessibility tools.

To improve the accessibility of knowl links, the HTML should probably look like: <a href="somwehere.html" role="button" aria-label="Reveal content of Lemma 1.1.1" title="Reveal content of Lemma 1.1.1" ...knowl-stuff...>Lemma 1.1.1</a>

Links are expected to navigate a page, not perform other actions. role=button is the way to communicate that this link is not a navigation link, that if functions like a button. https://www.w3.org/TR/wai-aria/#button https://www.w3.org/TR/wai-aria/#link

The aria-label is what the screen reader will actually read. The construct above is pronounced by NVDA as "Reveal content of Lemma 1.1.1 button".

The title should be ignored by a screenreader since there is an aria-label. But it will provide a tooltip for someone hovering over the link. Seems helpful to specify there also that the anchor is going to "Reveal" something as opposed to navigate.

Happy to update PR with that if desired.

Roger @rbeezer - will try to do better mirroring the comment format.

ascholerChemeketa commented 4 months ago

Refinement to my suggestion:

Initial link should look like: <a href="somwehere.html" ...knowl-stuff...>Lemma 1.1.1</a> That way it is a valid link and described as such by AT (Pronounced as "Lemma 1.1.1 link")

The knowl code should modify that by adding the role, aria-label, and title to transform it into something that is understood correctly by AT: <a href="somwehere.html" role="button" aria-label="Reveal content of Lemma 1.1.1" title="Reveal content of Lemma 1.1.1" ...knowl-stuff...>Lemma 1.1.1

rbeezer commented 4 months ago

Thanks for looking into the accessibility stuff. (Sorry, I missed post from two days ago.)

It all sounds good, and now the knowl code is where you can mess with it. ;-)

We will want to do localizations for Reveal content of and perhaps this will be easier for other languages if we just say Reveal Lemma 1.1.1? Maybe this means an adjustment to the attributes/content (so the XSL can place the localization, not the JS).

Its never simple....

ascholerChemeketa commented 4 months ago

Yes, to handle localization with PreTeXt, there would need to be some attribute like data-knowl-label that the XSL generated using the appropriate word.

ascholerChemeketa commented 3 months ago

Closing to merge this work with "knowl without JQuery rewrite" PR that will be coming soon and will incorporate the additional accessibility features.