diff --git a/site/src/pages/components/interest-invokers.explainer.mdx b/site/src/pages/components/interest-invokers.explainer.mdx index 3592947c..658b08b7 100644 --- a/site/src/pages/components/interest-invokers.explainer.mdx +++ b/site/src/pages/components/interest-invokers.explainer.mdx @@ -17,6 +17,7 @@ layout: ../../layouts/ComponentLayout.astro - [HIDs and Interest](#hids-and-interest) - [Mouse](#mouse) - [Keyboard](#keyboard) + - [The `keyboard-focusable` CSS property](#the-keyboard-focusable-css-property) - [Touchscreen](#touchscreen) - [Other](#other) - [Mouse delays](#mouse-delays) @@ -83,6 +84,8 @@ Users access the web using many different Human Interface Devices (HIDs), includ Mouse users will show interest in an element by mouse-hovering the element for a period of time. They will lose interest in that element when they de-hover the element (i.e. hover something unrelated) for a period of time. (See the [Mouse delays](#mouse-delays) section for more detail.) If the target is a popover, then both the element with `interesttarget` *and* the target popover need to be de-hovered. In this way, a user can hover to get a hovercard, and then move the mouse over to that hovercard (e.g. to select/copy some text) without the popover closing. +Note (see the [Keyboard][#keyboard] section for more detail) that hovering the element with `interesttarget` shows the popover in "partial activation" mode. Subsequently, hovering the target popover itself causes the target to be "fully activated". This enables use cases where *both* keyboard and mouse are being used. For example, a user might tab to focus an `interesttarget` element, which shows a popover. Then they move their mouse over to a button within that popover, activating the popover and making the button clickable. + ### Keyboard For keyboard users, there is a tension between discoverability and annoyance. The most discoverable way to "show interest" via the keyboard is simply for keyboard focus to trigger interest. The downside of this pattern is that users who are merely trying to keyboard-navigate through a document might be annoyed if popovers begin to appear as they tab through the document. An activation delay mitigates this somewhat, but doesn't solve the issue for users who stop tabbing on an `interesttarget` element inadvertently, and are then surprised by a popover. This problem is particularly bad in the case that the popover has interactive content, since it will be placed *next* in the tab navigation order, forcing the user on a "detour". The alternative way to "show interest" is a special keyboard hot-key, such as Alt-UpArrow. This alleviates the "surprise" problem, since the user must affirmatively choose to show interest, but it lacks discoverability. Many users might never know that there's a way to activate the additional content. @@ -92,24 +95,36 @@ For the above reasons, a somewhat more complicated approach is adopted for `inte - trigger interest in the element when it receives keyboard focus, after `interest-target-show-delay` seconds. - lose interest in the element when focus *leaves* the interest invoker or its target, after `interest-target-hide-delay` seconds. Also, hitting ESC will immediately lose interest in the element. -So essentially, delayed-focus triggers interest. To mitigate the "annoy the user" problems, the following additional behaviors take place. Note that these additional behaviors do *not* occur when interest is shown via mouse, touchscreen, or other: -- if the target is a popover, it is shown, but is rendered with `interactivity: inert`. This keeps the popover from inserting any additional tab stops into the sequential focus navigation order. -- a hotkey (e.g. Alt-UpArrow) will cause the popover to be "fully activated" which removes the `interactivity` rule. This makes it non-inert and available in the focus navigation order. This hot-key must be chosen by the UA to be convenient for the user, while also not conflicting with existing UA-provided and OS-provided hot-keys. Other ideas include Alt-Space or Ctrl-Space for the show interest hot key. The hotkey should not be an arrow key without a modifier, since that will interfere with scrolling. -- a new pseudo class (e.g. `:has-partial-interest` or similar) will match on the *target popover* only when it is in the "partially activated" inert state. If the popover does not contain any interactive elements, then the `:has-partial-interest` pseudo class will *not* apply, since there's no difference between "partial" and "full" activation. -- a new UA stylesheet rule will will be added: `:has-partial-interest::after {content: "Press Alt-UpArrow to activate this content"; interactivity: auto}`. This adds (developer-overridable) hints to the user about the hotkey, so that it is discoverable. Note the `interactivity` value here - that makes the hotkey information non-inert so it shows up in the a11y tree. +So essentially, delayed-focus triggers interest. To mitigate the "annoy the user" problems, the target popover is activated in "partial activation" mode, in which case none of its contents are keyboard focusable. To achieve that, the following additional behaviors take place: +- if the target is a popover, it is shown, but any interactive contents within the popover act as if they have `tabindex=-1`. This keeps the popover from inserting any additional tab stops into the sequential focus navigation order. +- a hotkey (e.g. Alt-UpArrow) will cause the popover to be "fully activated" which removes the special `tabindex=-1` behavior, making it available in the focus navigation order. This hot-key must be chosen by the UA to be convenient for the user, while also not conflicting with existing UA-provided and OS-provided hot-keys. Other ideas include Alt-Space or Ctrl-Space for the show interest hot key. The hotkey should not be an arrow key *without* a modifier, since that will interfere with scrolling. +- a new set of pseudo classes will match on the interest invoker *and* the target popover, only when it is in the "partially activated" inert state. For example, `:has-partial-interest` will match the invoker, and `:target-has-partial-interest` will match the popover. +- the special `tabindex=-1` behavior will be implemented with a new UA stylesheet rule: `:target-has-partial-interest {keyboard-focusable:not-focusable}`. See the [`keyboard-focusable` section](#the-keyboard-focusable-css-property) for more detail. +- a new UA stylesheet rule will will also be added: `:target-has-partial-interest::after {content: "Press Alt-UpArrow to activate this content"}`. This adds (developer-overridable) hints to the user about the hotkey, so that it is discoverable. This approach, while slightly more complicated, nicely meets the following use case requirements: - - Better user activation story for non-interactive "tooltips" that shouldn't be so hard to activate. - - Better discoverability story for rich "hovercards". + - Better user activation story for non-interactive "tooltips" that shouldn't be so hard to activate. Note that these have no behavior difference between "partially activated" and "fully activated", since they contain nothing interactive. + - Better discoverability story for rich "hovercards". The `::after` UA rule provides explicit instructions. - Less risk of annoyance for keyboard users, since rich hovercards don't insert themselves automatically into the sequential focus order. - - Ability to override inertness for key use cases, such as menus (where the author would add `:has-partial-interest {interactivity:auto}` to activate immediately on focus) and "large/obtrusive" tooltips (where the author would add `:has-partial-interest {display:none}` so content doesn't automatically show on focus). - - The partial interest state can be indicated to the user (e.g. with `:has-partial-interest {opacity:50%}`) if desired, and the helpful text about the hotkey can be customized or hidden if desired. + - Ability to override inertness for key use cases, such as menus (where the author would add `:target-has-partial-interest {keyboard-focusable:auto}` to activate immediately on focus) and "large/obtrusive" tooltips (where the author would add `:target-has-partial-interest {display:none}` so content doesn't automatically show on focus, but requires the hotkey). + - The partial interest state can be indicated to the user (e.g. with `:target-has-partial-interest {opacity:50%}`) if desired, and the helpful text about the hotkey can be customized or hidden if desired. - (Most importantly?) The default state "just works" for keyboard users, in the case that the developer only tested/developed using a mouse, and didn't do any of the above. Additionally, the appearance of the focus ring will be altered slightly when focus is on elements with `interesttarget`. This allows the user to discover that something is "different" about this element, and know that the keyboard activation hot-keys will allow them to activate popovers. Since accessibility guidelines state that color alone cannot be enough to differentiate states, this focus ring change will likely need to be something like a slightly-thicker outline, or other shape change. See https://github.com/openui/open-ui/issues/1133 for a much more detailed conversation with developers about keyboard behavior. That extended discussion led to the behaviors described in this section. +#### The `keyboard-focusable` CSS property + +As a prerequisite for `interesttarget`, a new CSS property needs to be added which has the following values: + +- `keyboard-focusable: auto`: the normal behavior. Some elements (such as buttons) are made focusable by the user agent, and others (such as `
`) are not. +- `keyboard-focusable: not-focusable`: when the computed style for an element has this value, the element will not be keyboard focusable. Note that the element might still be focusable overall (e.g. programmatically or via the mouse). The element, in other words, behaves as if it has `tabindex=-1`. + +This property inherits, so that children of the element also follow the behavior. An explicit `tabindex` value on an element should override the value of this property. + +Note: adding such a CSS property likely precludes the later addition of something like [`:focusable`](https://github.com/w3c/csswg-drafts/issues/7269), due to circularity concerns. + ### Touchscreen For touchscreen users, the widely-adopted standard for "showing interest" in an element is the [long-press gesture](https://en.wikipedia.org/wiki/Pointing_device_gesture#:~:text=0%3A04-,Long%20Press,-Duration%3A%205%20seconds). For native apps, this is the user-expected shortcut to show context menus and access other actions without explicitly activating the element. (See [this comment](https://github.com/openui/open-ui/issues/1052#issuecomment-2394446599) for more context on this point, from developers.) @@ -172,6 +187,8 @@ container:has(:has-interest) [interesttarget] { } ``` +A case has also been made that perhaps a pseudo class should match the **target** in this case. We propose `:target-has-interest` should match the target of the invoker, when it has been activated via showing interest in its interest invoker. + ## Implementation Details In the style of `commandfor`, we propose to add a global attribute called `interesttarget`, which can be used on `