Clarity: Signpost Help Component (New)

[lil-kim]

Select one ... (check one with "x")

[ ] bug
[X] feature request
[ ] enhancement

Description

Signposts provide contextual info/help in a popover that can be initiated or dismissed by the user

Features

• User initiated viewing or hiding of the popover
• Headings, images, text/image links (optional)
• A vertical scroll bar (default browser) may be used if the content exceeds the max height (504 px)
• A trigger element: When clicked, the “i” icon triggers the popover into view
• Anchor arrows may be positioned on any corner or centered on any side of the popover. See diagram for placement. (May be subject to change in implementation)
• Max width is 360 px, obviating the need for responsiveness on smaller screens

Usage

• Use to show contextual help or information
• May be used when a tool tip is too small for the amount of content
• When the information presented needs to stay in view at length. Unlike tooltips, the user is able to mouse away without losing the view.

Interaction

• By default, popovers should appear on the right side of the trigger element. Alternate positions may be used if the default is not possible.
• The popover may be dismissed by either clicking outside of it or by clicking the “X” icon.
• To keep the interface clean, show one popover at a time.
• When a popover is visible, clicking an icon to open another will automatically dismiss the first one.

Recommendations

• The popover should not be so large that it dominates the screen
• Make sure that the popover doesn’t obstruct other important information on the screen.
• With the exception of text links, don’t insert any actionable components such as buttons in the popover.

Basic Signpost Design

Signpost help with header / text link / image

Min/Max Width and Height (including anchor point)

Min-width 216 px; Min-height 84 px
Max-width 360 px; Max-height 504 px

Basic Spec

• On hover/click, the grey “i” icon (trigger element) becomes blue #007CBB. It remains blue until the popover is dismissed.
• When the “i” icon is clicked, the popover becomes visible.
  

Heading and Image Spec

H4 (Metropolis Light)

Icon Positioning

Align the icon 6 px to the right of the item. If a table or stack view has multiple signposts, the icon may be placed in a separate column or aligned to the right side of the grid.

Anchor Point Positioning

1. Anchor placed along center line of popover
   2, 3. Anchor placed on corner of popover

Popover positioning

• Clarity version:

• OS and version:

• Browser: [all | Chrome XX | Firefox XX | IE XX | Safari XX | Mobile Chrome XX | Android X.X Web Browser | iOS XX Safari | iOS XX UIWebView | iOS XX WKWebView ]

[xinyu900430]

Have we considered having an i icon with a circle around it? The character only icon seems to blend in with the text around [see attached image]. A circle icon might be a more common approach and makes it easier to stand out.
I understand that there is a concern that this might overlap with the info icon of the warning message. Maybe have an inclined i with a circle around? or a question mark "?" with circle around. Just some ideas.

-Yu

[tonycgil]

I agree with @xinyu900430 suggestion in using a "?" for any help or in this case the Sign Post Help.
Throughout my experience a "?" has always been the standard for "help" contextual text, and information text is triggered by an "i" icon. Thoughts?

[tonycgil]

...or perhaps changing the description to "Signposts provide contextual information in..." instead of "Signposts provide contextual help in..." since we're using an "i". If that's the case, then what does the "?" for help text look like when displayed in a popover?

[jpapadami]

Wanted to offer some feedback concerning the change of the old info icon with the newly proposed one. Since this icon is also used for info alert messages they might also be used for info inline messages. This might cause users to think that all such info icons are clickable, opening up a signpost help, which won't be the case.

[tonycgil]

Hi @jpapadami, how can I see such example? Can you share the steps to get info inline messages?

[jpapadami]

There are currently no info inline messages that I am aware of, but was an old pattern in Flex and something that could be used down the line unless we decide to deprecate this pattern. There are also info app level messages that use the same info icon (just white).

What I'm trying to say is that using an icon that is also used somewhere else (for now at in info alert and app level message) might cause the user to expect a signpost help. Maybe Yu's suggestion to use a circle with a "?" might be better.

To add on to your discussion of "i" and "?", I would agree that a ? has always been for help context, so that is why I would use "?" for signpost helps. I would use "i" when text is explicitly visible, like in info alerts, app level alerts, and possible info inline messages (if we don't deprecate this pattern).

[lil-kim]

The reason that we're not using the "?" is because it's reserved for Help that takes you to a new page.

[clementcur]

hi guys, any ETA for the implemented component?

[hippee-lee]

Hi @clementcur
I'm starting the implementation work for this component today or tomorrow.

[youdz]

Here is the API we just agreed on for the Angular component:

<clr-signpost>
    <clr-icon shape="info" clrSignpostToggle></clr-icon>
    <clr-signpost-content *clrIfOpen clrDirection="right-top">
        Lorem ipsum...
    </clr-signpost-content>
</clr-signpost>

The goal is for the <clr-icon shape="info" clrSignpostToggle></clr-icon> to be optional and defaulting to the info icon, but designing a strict API initially and having to allow different icons in the future would create too many breaking changes.
This means that the simplest of cases would still need two elements:

<clr-signpost>
    <clr-signpost-content *clrIfOpen>
        Lorem ipsum...
    </clr-signpost-content>
</clr-signpost>

*clrIfOpen is going to be ad hoc for now, we have a separate task to extract it and make it reusable for other components. It will request a provider declared by <clr-signpost> to communicate with the rest of the component. It should accept a boolean input so that the user can "force" the signpost open or closed, and expose a boolean output to allow for two-way binding (so that the consumer can react to the signpost opening or closing).
For instance, to just pre-open the signpost, you'll write:

<clr-signpost-content *clrIfOpen="true">
    Lorem ipsum...
</clr-signpost-content>

But due to Angular's structural directive microsyntax limitations, you'll need to write the de-sugarized form to use two-way binding:

<ng-template [(clrIfOpen)]="myOpenProperty">
    <clr-signpost-content>
        Lorem ipsum...
    </clr-signpost-content>
</ng-template>

The extra verbosity is acceptable as a compromise to obtain a simpler API in the basic case, and hopefully https://github.com/angular/angular/issues/12121 will get some love someday.

[vinaykhegde]

can I change max height from 504px to say 200px?

[hippee-lee]

You have several options here. I mad a stackblitz that handles this in three ways: https://stackblitz.com/edit/clarity-light-theme-v012-signpost-max-height

In the future, please post these types of questions on StackOverflow with a stackblitz for what you have tried and then tag it with the vmware-clarity label. Generally, additional comments on closed issues might not get noticed.