Be able to provide helpful hints in a contextual, non-intrusive manner using tooltips

[nikku]

Problem you would like to solve

As a user of the modeler I have issues navigating the properties panel and understanding individual items due to the lack or overload of information:

• Too little information: In some places, the properties panel showcases a very small amount of information. This leads to me not being able to understand how a certain feature works (Simplify multi instance configuration #3588).
• Too much information: In some places we show large amounts of information, specifically in connectors or timer definitions (cf. additional context). Much of that is duplicate and tends to become irrelevant once you know. Such wall of text can distract users from quickly skipping through the properties panel to discover or re-identify relevant information.

Proposed solution

Structure helpful hints in a manner that it is non-intrusive using tooltips:

• Tooltip shows structured information (code snippets, external links)
• Tooltip presence is indicated on the UI (on element/section hover/focus)
• Tooltip displays on demand (when user hovers/focuses a certain section)
• Tooltip can be focused to copy from, but also follow links presented in there
• Tooltips can be populated in different ways:
  • via bpmn-js-properties-panel and such
  • via element templates

Alternatives considered

None.

Additional context

Product hub epic: https://github.com/camunda/product-hub/issues/893

Current UI in connectors, meant to be user friendly; assistive documentation highlighted:

---

Breakdown:
1st iteration:

• Support tooltips for entries bpmn-io/properties-panel#202
  • Support tooltips in group headers bpmn-io/properties-panel#263
• Support tooltip population via context bpmn-io/properties-panel#261
• Integrate tooltips in bpmn-js-properties-panel
  • Identify places where we want to add tooltips: comment 1, comment 2, comment 3
  • Add tooltips to input field labels and group headers bpmn-io/bpmn-js-properties-panel#945

2nd:

• implement tooltips for element templates
  • Support tooltips in schema element-templates-json-schema#103
  • Support tooltips bpmn-io/bpmn-js-element-templates#8

Follow ups and improvements:

• Tooltip content isn't selectable bpmn-io/properties-panel#272
• Properties tooltips do not hide on blur when right-clicking links before #3756
• Remove native tooltips from groups bpmn-io/properties-panel#274
• Improve tooltips bpmn-io/bpmn-js-properties-panel#955
  • Add short explanatory text to bpmn-js-properties-panel doccumentation tooltips
  • Add missing tooltips: extension properties, script task, timer retries

[nikku]

A quick sketch on tooltip discovery:

Another one on overall tooltip UI (bpmn-io/properties-panel#202):

[nikku]

Context provided by @YanaSegal: We already have an existing tooltip component in web modeler. To be clarified if we want to use that one, move to a new one (Carbon).

Cf. existing component, used in Web Modeler:

[Nitish-u]

Hello @nikku, Is this issue still open? I wanted to know about this issue can you please tell me, where it is occurring and what adjustments you want. Actually i'm new to opensource contribution, till now i've contributed to my personal repo only.

[nikku]

If you want to contribute @Nitish-u, please checkout issues flagged accordingly as well as our contributing guide.

[smbea]

While bpmn-io/properties-panel#202 is being reviewed, I will try to identify places where we might want to replace the description with a tooltip or add one.

This will also help me figure out if there is a need to allow tooltip population by context/tooltip provider like we do for description for now.

[smbea]

[tooltips via context and tooltips for group headers]

In order to provide tooltip content as context, we need to provide ids for the trigger element. If we combine this with supporting tooltips on group headers, then we need to provide some id. The group id sometimes coincides with a field id (ex: documentation group and element documentation field; implementations group and field).

A way to avoid potential breaking changes by altering some of the ids so they don't match, is to use the data-group-id which adds the group- prefix. In a tooltip provider, this would look like:

- businessRuleImplementation: (element) => return <TOOLTIP_CONTENT>;

// for implementation field
+ businessRuleImplementation: (element) => return <TOOLTIP_CONTENT>; 
// for implementation group
+ `group-businessRuleImplementation`: (element) => return <TOOLTIP_CONTENT>;