Re: aria-action2036 aria-keyshortcuts

> On Mar 14, 2016, at 6:40 AM, Rich Schwerdtfeger <richschwer@gmail.com> wrote:
> 
>> On Mar 12, 2016, at 6:33 PM, James Craig <jcraig@apple.com <mailto:jcraig@apple.com>> wrote:
>> 
>> This needs more work.
>> 
>>> [ARIA 1.1] Indicates keyboard shortcuts that can be pressed to activate widgets, such as a button, link or menuitem. 
>> 
>> This may be misleading to authors. It implies they don't have to register for the JavaScript key handlers.
>> 
> This has been in since day one. I am not sure why this stands out now especially since aria does not specify browser behavior. 
> 
> Would you prefer something like:
> 
> Indicates keyboard shortcuts that an author has implemented to activate widgets, such as a button, link or menuitem. 

That's a good clarification, yes. Thank you.

>>> Authors SHOULD avoid keys other than ASCII letters. 
>> 
>> This would be fine except you follow it up with two paragraphs and a list contradicting this requirement, even showing conflicting examples.
>> 
>>> For example, the double-quote character can be encoded as "Shift+&#39;" in HTML.
>> 
>> and 
>> 
>>>  • "Control+&quot;"
> 
>> Doesn't this last one conflict as well? &quot; (") is Shift+' on US English keyboards, so the example "Control+&quot;" is in direct conflict with the recommendation to expose this as "Control+Shift+&39;", and in direct conflict with the recommendation to stick with ASCII letters.
>> 
>>> Authors must ensure aria-keyshortcuts are global for active elements to which they are applied in a document. Authors must provide a sequence of operations to reveal the shortcut to the user by making it visible so that it may be discovered by a user of an assistive technology. An example would be a visible and enabled menu item within a document. If the menu item exposes a keyboard shortcut it is assumed that as long as the document has focus, pressing that keyboard shortcut will activate that menu item. Authors must ensure that when elements having aria-keyshortcuts are marked disabled those keyboard shortcuts are unavailable. Authors may choose to make as shortcut unavailable to the user when it is invisible or hidden.
>> 
>> The first three of these requirements are written in language that is unclear.
>> - Undefined, ambiguous terms ("global", "sequence of operations", etc.) 
> 
> Sequence of operations seems nit picky. Would you prefer “must provide a means” or do you want to have a definition for that too?

I'm not trying to be nit-picky, but I don't think that's any more clear. I'm not sure what this requirement means:
"Authors must provide a sequence of operations to reveal the shortcut to the user by making it visible so that it may be discovered by a user of an assistive technology. "

"Making it visible" implies rendering shortcuts visually, or perhaps listing them on a page, but there are other ways some users of assistive technology could discover the shortcuts without a visual rendering. There may be multiple requirements here. 

If this is a intended to encourage a visual rendering for mainstream users, it should be an RFC-2119, "SHOULD" rather than a "MUST" and not confuse readers by mentioning assistive technology. Perhaps, "Authors SHOULD include a way for sighted users to learn keyboard shortcuts. For example, in a visual tooltip."

If this requirement is intended to be a benefit to assistive technology users, I thought the attribute provided that benefit on its own. Isn't the intention that AT will announce this shortcut somehow? If so, why would an author need to make a shortcut visible in order for AT users to perceive it?

>> - Run-on sentence: "...of operations to reveal the shortcut to the user by making it visible so that it may be discovered by a user..."
>> - Odd phrasings: "Authors must ensure that when elements having..."
>> - Tense changes: "An example would be a [menu item]. If the menu item exposes…”
> 
> I will look at this. 

We may need some platform-specific RFC statements, too. For example, I would not recommend authors expose any combination of Control+Option (not exactly but more or less Control+Alt) on OS X, since those are the default activation keys for VoiceOver. Users would need to trigger the "ignore next key press" behavior in order to use the specified key shortcut, which would be tedious. 

I am certain there are keyboard anti-patterns on other platforms as well. For example, many browsers reserve their own hotkeys. There should be a requirement to avoid native browser hotkeys, which is very difficult to do unless you're changing keys per platform.

>> The fourth requirement ("Authors MAY choose...") is irrelevant and can be removed.
> This is not irrelevant when we say that keyboard shortcuts are global to the document. If they are global and then all of a sudden they are unavailable, because they are not visible,  this is an important distinction. 

>>> Authors may choose to make as shortcut unavailable to the user when it is invisible or hidden.


This is only relevant to the business logic of the web application. I don't agree that this is relevant for a technical specification. 

Keyboard shortcuts become unavailable all the time. For example, the "Send" shortcut in a mail application is only available when there is a draft message to send and only when it's the front-most window. Having contextual keyboard shortcuts is a common pattern that does not need to be addressed in the ARIA spec.

James

>> 
>>> On Mar 9, 2016, at 3:22 PM, Richard Schwerdtfeger <richschwer@gmail.com <mailto:richschwer@gmail.com>> wrote:
>>> 
>>> Thank you to you and the Apple i18n team for the feedback. I made extensive to the the branch to reflect the feedback:
>>> 
>>> https://rawgit.com/w3c/aria/action2036/aria/aria.html#aria-keyshortcuts <https://rawgit.com/w3c/aria/action2036/aria/aria.html#aria-keyshortcuts>
>>> 
>>> I did not, yet, take into account comments from the list regarding applying it to other roles yet as it is very hard to follow the spec. (as to what supports what) until Shane makes changes to respec. 
>>> 
>>> I am sure there were be additional comments as i introduced more normative text for authors. 
>>> 
>>> Rich
>>> 
>>> 
>>>> On Mar 1, 2016, at 4:08 AM, James Craig <jcraig@apple.com> wrote:
>>>> 
>>>>> On Feb 28, 2016, at 8:42 AM, Richard Schwerdtfeger <richschwer@gmail.com> wrote:
>>>>> 
>>>>> Here is a draft of the spec. with the changes:
>>>>> https://rawgit.com/w3c/aria/action2036/aria/aria.html#aria-keyshortcuts
>>>> 
>>>> 1. Changelog reference to aria-kbdshortcuts is a broken link.
>>>> 
>>>> 2. Examples list "Ctrl" (KeyboardEvent spec value is "Control".)
>>>> 
>>>> 3. [From the Apple i18n team] It's recommended to avoid anything other than ASCII letters. Even numbers and common punctuation often require modifiers. For example, in French keyboard layouts, the number keys are not available until you hold the Control key, so a keyboard shortcut defined as "Control+2" would be ambiguous (This is just the way you type "2") or impossible to input (Control modifier may not be passed to the web application).
>>>> 
>>>> As such this requirement may need to be reconsidered. 
>>>> 
>>>>> The valid names for non-modifier keys are any printable character such as "A", "B", "1", "2", "$", "Plus" for a plus sign, "Space" for the spacebar, or the names of any other non-modifier key specified in the DOM Level 3 KeyboardEvent key Values spec [DOM-Level-3-Events-key] - for example, "Enter", "Tab", "ArrowRight", "PageDown", "Escape", or "F1".
>>>> 
>>>> Next example:
>>>> 
>>>>> When specifying an alphabetic key, both the uppercase and lowercase variants are considered equivalent: "a" and "A" are the same, as are "ü" and "Ü".
>>>> 
>>>> In light of all the i18n warnings about this property, avoid the umlauts and accented characters altogether, as it shines a light on the problems. Worse, it makes it seem like the WG is unaware that the problems exists, making the group appear naïve or foolish.
>>>> 
>>>> It's impossible to enter ü or Ü on most keyboards without a modifier (Ü is actually a set of two key shortcuts on Mac OS X "Option+u" for the umlaut, immediately followed by "Shift+u") so this requirement conflicts with the statement that immediately follows:
>>>> 
>>>>> When specifying a key on the keyboard that changes when you hold down a modifier key other than an alphabetic key, authors must specify the unmodified key name. 
>>>> 
>>>> This requirement is flanked on both sides by examples that conflict with it. (See ü above and &quot; below.)
>>>> 
>>>> The first clause is also hard to understand. I think "other than an alphabetic key" may be a misplaced modifier in this sentence, or if it's not, the sentence should be rewritten to avoid the ambiguity.
>>>> 
>>>>> For example, on most U.S. English keyboards, the percent sign "%" can be printed by pressing Shift+5. The correct way to specify this shortcut is "Shift+5". It is incorrect to specify "%" or "Shift+%". However, note that on some international keyboards the percent sign may be an unmodified key, in which case "%" and "Shift+%" would be correct on those keyboards.
>>>> 
>>>> Replace: s/printed/input/
>>>> Replace: s/would/could/
>>>> 
>>>>> If the key that needs to be specified is illegal in the host language or would cause a string to be terminated, authors must use the string escaping sequence of the host language to specify it. For example, the double-quote character can be encoded as "&quot;" in HTML.
>>>> 
>>>> This example also conflicts the previous requirement, because on a US English layout, the double quotation mark character should be specified as a shifted single quotation mark: "Shift+&#39;"
>>>> 
>>>>> Adding the aria-keyshortcuts attribute to an element does not change the behavior of the user agent by mapping the specified keyboard shortcuts to the triggering of the element's activation function. It is still up to the application to implement support for the keyboard shortcuts. 
>>>> 
>>>> These are non-requirements that should be rewritten as two RFC-2119 statements: ~"User Agents MUST NOT change keyboard behavior…" and ~"Authors MUST handle scripted keyboard events…"
>>>> 
>>>>> The aria-keyshortcuts attribute exposes the fact that these shortcuts exist so that assistive technologies can communicate this information to users.
>>>> 
>>>> It is not a "fact" that the shortcuts exist. They very well may not exist. Even rephrased, I don't think this sentence adds value. Consider dropping it.
>>>> 
>>>>> Keyboard shortcuts are assumed to be global. If a button is present in a document and it is visible and enabled, and it exposes a keyboard shortcut, it is assumed that as long as the document has focus, pressing that keyboard shortcut will activate that button. If the button or other element is not currently available to be activated normally, for example because it's currently invisible or hidden, or explicitly marked as disabled, that implies that the keyboard shortcut is unavailable too.
>>>> 
>>>> • If this paragraph is intended to be non-normative, it should be wrapped in a Note. 
>>>> • The second and third sentences are run-on sentences. 
>>>> • The term "document" here is ambiguous or perhaps incorrect. Should this work in a containing frame's document? Perhaps this should be "window"?
>>>> 
>>>> That's all I've got for now.
>>>> James