camunda / camunda/linting

Make the annotation overlay tooltip configurable by the host application

Open
#175 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

backlog enhancement spring cleaning ux
Dominant language
JavaScript
Stars
5
Forks
4
PR merge metrics
No merged PRs in 30d

Description

Is your feature request related to a problem? Please describe.

Image Image

The linting annotation icon rendered on a diagram element (lib/modeler/OverlayComponent.js) uses a native title attribute for its hover hint:

<div class=${classNames('cl-icon', `cl-icon-${category}`)} onClick=${onClick} title="Click to show issue">

A native title gives downstream modelers no control over two things:

  1. Delay. The browser decides when the hint appears, typically after about a second. That is slow enough that the icon reads as non-interactive during the pause, which is exactly the moment the hint is needed.
  2. Styling. A native title cannot be styled at all. Downstream modelers that have their own tooltip component end up with two visually different tooltips a few pixels apart on the same canvas.

In Web Modeler this is visible side by side: the documentation overlay icon uses the product's own tooltip (dark, styled, ~200 ms delay) while the linting icon next to it falls back to the browser default. Same canvas, same interaction, two different hover experiences.

Describe the solution you'd like

Let the host application supply its own tooltip presentation for the annotation overlay, through config.linting. Roughly:

  • A config option to provide a custom overlay component, or a render hook that wraps the icon, so a host can put its own tooltip around it.
  • Failing that, a config option for the hint text and a non-native tooltip element with a configurable delay and a stable class name, so hosts can restyle it via CSS.

The default behaviour should stay as it is today for hosts that configure nothing.

Describe alternatives you've considered

  • Reimplement LintingAnnotations downstream. Workable but costly: a host would have to redo report grouping by element, getAnnotationPosition, the overlay lifecycle, and the scale.min behaviour, then keep that fork current as this package evolves. Roughly 100 lines duplicated per host to change one hover hint.
  • CSS-only override downstream. Not possible. Native title timing and appearance are browser-controlled and not reachable from CSS.
  • Hardcode a faster styled tooltip in this package. Fixes the delay but not the consistency problem, since each host's tooltip looks different.

Additional context

Observed with @camunda/linting 3.54.0 in Camunda Web Modeler (Camunda 8 SaaS and Self-Managed).

Related: https://github.com/camunda/camunda-hub/issues/27253 covers a separate downstream cursor fix on the same icon. That one is CSS-only and does not need a change here.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with lib/modeler/OverlayComponent.js and the linting configuration path described in the issue. Compare the possible host-supplied overlay or render-hook designs, including how the existing native title behaves when no option is configured. The work is done when hosts can control the annotation tooltip presentation without reimplementing the overlay, while the current default remains unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.