Contextual help RFC

[Rocss]

Contextual help

Working branch
Draft PR

Contextual help shows a user extra information about the state of either an adjacent component or an entire view. It explains a high-level topic about an experience and can point users to more information elsewhere.

Spectrum guidelines
Spectrum CSS

Usage

Adding your dependency:

yarn add @spectrum-web-components/contextual-help

Import and register the component <sp-contextual-help>:

import @spectrum-web-components/contextual-help/sp-contextual-help;

Importing the base class of the ContextualHelp component as a type or for extension purposes:

import { ContextualHelp } from ‘@spectrum-web-components/contextual-help'

Examples

<sp-contextual-help headline=”Permission required”>
    Your admin must grant you permission before you can create a segment
    <sp-link slot=”link” href="/help">Learn about permissions</sp-link>
<sp-contextual-help>

Properties and attributes

property	type	default	description
variant	“info” | “help”	“info”	changes the icon from informative to question mark
placement	supports the placement of the popover	“bottom-start”	where to display the popover, relative to the trigger
offset	Number | 2-tupleAs per https://opensource.adobe.com/spectrum-web-components/components/imperative-api/#offset	0	Supports custom offset as per https://spectrum.adobe.com/page/contextual-help/#Popover-offset
label	string	“Informations” / “Help”	aria-label for the action button

Slots

• link: accessible link in the footer of the popover

Events

N/A - open / close events will be the ones propagated from the sp-overlay:
https://opensource.adobe.com/spectrum-web-components/components/overlay/#events

Dependencies

To achieve the Contextual help design we will require the following SWC dependencies:

• @spectrum-web-components/icons-workflow -we need two icons from here: sp-icon-help-outline and sp-icon-info-outline
• @spectrum-web-components/action-button - This is the trigger, extra-small, quiet, icon-only action button
• @spectrum-web-components/overlay
• @spectrum-web-components/dialog - lazy loaded? Would be needed on mobile
• @spectrum-web-components/popover - lazy loaded? Would be needed on web

Behavior

Mobile layout

On a mobile layout, the popover will be replaced with a dismissible dialog, similar with the example from here.
Users will be able to dismiss it by closing the “X” button in the dialog.

Accessibility

Keyboard navigation

Trigger will be a sp-action-menu, therefore will receive keyboard focus, and will be actionable on “Enter” / “Space”.
On the “Enter” keypress on the button, the Contextual help opens.

• [ON WEB] the keyboard navigation should not be limited to the contents of the Contextual help popover because this component does not require an action from the user in order to continue further. Tabbing out of the popover will close it.
• [ON MOBILE] If we decide to display a dismissible dialog on mobile devices, then I think we should trap the focus in this case?

Pressing “Esc” closes the popover and returns the focus to the action button.

Screen reader

Given that the trigger is an icon-only button, we need an accessible name for it. By default the component will provide aria-label=”Informations” or aria-label=”Help” depending on the type property.
Users will have the option to provide a custom accessible name for the button using the label property.
Open question: Based on the open/close state, should the button have an aria-expanded & aria-controls property?

Relation with other components

After discussions with Spectrum design: "contextual help can be used on it own paired with another component or as part of the field label itself for input components"
Open question: Should SWC support this component as a slot in sp-field-label, or should we let the consumers handle this?

[Rajdeepc]

Answer to your open questions about aria-expanded and aria-controls:

If the popover is open, aria-expanded should be set to "true" and aria-controls should point to the popover/dialog's ID. When closed, aria-expanded should be "false" and aria-controls should be removed.

[Rocss]

Hi @castastrophe / @pfulton, I was looking for your input on the following thing:
Looking at the Spectrum CSS implementation of the Contextual help, I see that it does not have a defined width/max-width on it. It adjusts to the parent's width, and that works well.
However, I don't think that works as well in actual library implementations, such as SWC. The popover is rendered outside of the parent's flow, because it is an overlaid content, and therefore does not reflect the parent's width or max-width.
See https://contextual-help--spectrum-web-components.netlify.app/storybook/?path=/story/contextual-help--default for reference.

Looking at the Spectrum design documentation and Figma, this component's popover seems to always have a specific width set.
As a consumer, and with the current implementation, I find it hard to set a width on the sp-popover, because it is inside the shadow-root, and it seems repetitive to always have to go and define a width for it.
Can we have a default width for it in Spectrum CSS as well (with default to whatever value it has in Figma), one that you can easily override using --mod properties?