[Style] Warn the user about styles for unsupported elements

Problem/Motivation

I'd like users of my site to be easily able to add predefined CSS classes to images, in the same way that CKEditor 5 allows them to easily add predefined classes to text. But it isn't clear how to configure this.

The CKEditor 5 config page for a text format allows the Styles plugin to be used to add arbitrary CSS classes to specific HTML tags - these are displayed as a drop-down list which the user can select from. e.g. I can add "a.special-offer|Special Offer" to provide the user with a "Special Offer" style, which will add the "special-offer" class to a selected <a> tag in the text.

However, this does not work for images.

The Styles plugin will allow me to add an entry such as "img.feature|Featured Image" as a style, and this will appear as an option to the user in the Styles drop down. However, when the user selects an image, the Styles dropdown becomes greyed out, and there's a separate, pop-up toolbar with image-specific functions. This makes it impossible to use the styles drop-down to add the required style. (I imagine this is the expected behaviour.)

I presume that in order to allow the user to apply my custom style to an image, I'll need to add an option button to the image pop-up toolbar. How do I do that?

The CKEditor documentation for Image Styles says that custom CSS styles can be added. And it is clear that this is different from adding text Styles. These pages explain how to achieve this at the CKEditor config level. But what would I need to do in Drupal terms?

I can see that in core/modules/ckeditor5/ckeditor5.ckeditor5.yml there's some config relating to the imagestyle toolbar. I am happy to forgo a GUI interface, but even so, I imagine that what I want to do cannot be achieved simply by editing this file.

I looked at https://www.drupal.org/docs/core-modules-and-themes/core-modules/ckedito..., but it doesn't cover this kind of issue. I also looked at https://www.drupal.org/docs/core-modules-and-themes/core-modules/ckedito..., but wasn't sure it that was the right route to go down.

What are the steps for customising the imagestyle toolbar? Do I need to create a new plugin? Or can can I simply adjust some configuration for an existing plugin - as I can for styles for tags other than <img>?

Steps to reproduce

1. Go to the configuration page for the Basic HTML text format.
2. Ensure the Style button is in the Active Toolbar.
3. Under CKEditor 5 Plugin Settings > Style, add a line: img.feature|Featured Image
4. Click outside the text box.
5. Click Save Configuration.
6. Edit a page on the site with a rich text field. Ensure the field is set to use Basic HTML text format.
7. Add some text to the field.
8. Select some text, then click on the Styles dropdown. Note that you have the option to select the "Featured Image" style, even though this is not relevant for text (Doing so will have no effect).
9. Insert an image into the field.
10. Click on the image to select it.
11. Note that the Styles dropdown is now greyed out, making it impossible to select the "Featured Image" style, and instead, a pop-up toolbar is shown with image-related options.

Proposed resolution

❌ Provide some documentation which explains how to add custom buttons to the image pop-up toolbar, including a button which adds a specified class to the image.

✅ It would be helpful if the Styles Plugin could warn users when they attempt to define a style for an <img> tag that this will not be effective.

❌ Or, better still, extend the Styles Plugin so that defining a style for an <img> tag causes a suitable button to appear in the image pop-up toolbar.

Remaining tasks

Review.

User interface changes

A helpful validation error message now appears immediately:

API changes

None.

Data model changes

None.

Release notes snippet

TBD