I/6267

[pkwasnik]

Suggested merge commit message (convention)

Feature (docs): Mark UI buttons in the guides. Closes #6267.

---

Additional information

[pkwasnik]

I'd prefer a lighter border to distinguish it more from the UI border, e.g.: #D9D9D9 / hsl(0, 0%, 87%), but I am not sure if I should use only existing color vars or create a new one (and where to put it).

[oleq]

While I'm totally digging the look and feel of the balloon 💕, I also have certain concerns regarding the implementation.

I'm not sure why you went with the implementation that relies on ckeditor5-ui. Browsing the discussion under the issue I got the impression that we dumped this tempting concept of using the BalloonPanelView because it:

1. requires importing import { pinTourBalloon } from '@ckeditor/../../docs/assets/button-indicator.js'; in every snippet file (which is a PITA)
2. effectively makes ckeditor5 a dev dependency of (almost) every ckeditor5-* package for the sole purpose of importing a single helper, which is just wrong.

Have I missed something? I thought we're going with an external library to spare ourselves the hassle. @Reinmar, did you have an impact on this decision?

Anyway, also I spotted some issue with an error being thrown when the button that should get the tour balloon gets immediately wrapped in the "kebab dropdown" due to the narrow geometry of the viewport when the editor loads. But before we move on to this, maybe let's sort out this implementation toolkit decision as it may affect this and similar issues.

[oleq]

1. Only the classic editor has .ck-editor__top. Other editors such as inline or balloon don't have this structure and this will fail in their cases.
2. I think this will fail with multiple editor on the same page (how to reach the 3rd one?)
3. The selector you used will fail in case of nested toolbars (see the highlight feature). Check out the 4th button

vs the 5th one

Also:

1. To stay on the safe side I'd go with something like getToolbarButtonByIndex( toolbarView, index ) used like this getToolbarButtonByIndex( editor.ui.view.toolbar, 4 ) or getToolbarButtonByIndex( editor.plugins.get( 'BlockToolbar' ).toolbarView, 4 ).
2. We can deliver another method findToolbarButton( toolbarView, callback ), that will utilize ViewCollection#find, e.g. findToolbarButton( toolbarView, item => item.label === 'Bold' ) to make configurations bulletproof so when somebody reorders the toolbar or the default build config changes, the balloon will find its target. You could also use it to find dropdowns and other UI controls, e.g. item => item.buttonView && item.buttonView.label.startsWith( 'Heading' ) by duck typing. Not super-safe but should work.
3. You need to figure out which method is better by browsing our guides and checking out which UI views may need the balloon. We may only need the first helper. Or the latter. We may need them both. This requires research.

[pkwasnik]

My mistake, I misunderstood that. But switching now to an external library will not be a big deal as I already have it prepared in one of the previous PoC. Anyway, it will also require to be imported in every snippet, or there is another solution?

[oleq]

Can we import it once in snippet.js and store the reference somewhere in window or another namespace?