Allow icon customization without webpack-specific plugins

[filipsobol]

Currently, the only way to customize icons is to use webpack-specific NormalModuleReplacementPlugin. However, this doesn't work with the new installation methods, which are bundler-agnostic.

We have had some discussions about how to allow replacing icons in NIM, and the first step would be to move all icons to a new package that only re-exports icons individually (not grouped into a single JavaScript object). This would allow icons to be tree-shaken by the bundlers when not used.

The next step is not clear yet, as there are two possible approaches:

1. Icons should behave like new translations and be passed to the editor configuration. This way, most people can pass the default icons, but those who want customization can pass a custom set of icons.
2. Plugins should import icons from the new package, and the developers who want to change them can use the override option available in npm and pnpm or resolutions available in yarn to override the icons package with their own custom package.

The first approach provides a better developer experience at the cost of introducing breaking changes for all developers using CKEditor5.
The second approach introduces a smaller breaking change that doesn't affect the majority of the projects, but at the cost of the worst developer experience for those who customize icons.

[trevordevore]

I vote for 1. Worst developer experience will remain forever. The one-time code change is a... one-time change.

[sunesimonsen]

I think option one sounds best.

Here is an idea - what if CKEditor had default icons (like it does today), but you can override them with an icon map you pass into the configuration. Wouldn't that maintain backward compatibility for most usages, while giving the power to override any icon?

[filipsobol]

Here is an idea - what if CKEditor had default icons (like it does today), but you can override them with an icon map you pass into the configuration. Wouldn't that maintain backward compatibility for most usages, while giving the power to override any icon?

Yes, this would maintain backwards compatibility and allow overriding icons. However, in this scenario, the final bundle would include both icon sets, which we want to avoid.

[filipsobol]

In this issue, we wanted to introduce not only an alternative to overriding icons that was available in the old installation methods, but also a new way to do it via the editor configuration.

The former was quite simple and involved moving all icons for free and commercial plugins to a new package named @ckeditor/ckeditor5-icons. This package can be overridden either using package managers (and the override / resolution fields) or using bundlers. This change is already done and will be available by the end of Q1.

However, the latter turned out to be more difficult to implement, as it required support for both old and new installation methods and current architecture. We've decided to drop this idea for now, as we may have better ways to do this in the future.

Below, I've described what we tried so that it will be easier for us to come back to this issue in the future.

---

Currently, icons are used in the global scope (example), plugins, and views. If we want icons to be customizable via the editor configuration, we need to be able to access it from all these places. Although we could remove icons from the global scope and use them only in plugins and views, the latter don't have access to the editor instance because views only accept the Locale instance in their constructor.

The first thing we tried was to introduce a new CKEDITOR_ICONS global. Being global, it would be available anywhere and could be updated based on editor configuration, but the solution was hacky and would not allow different icon sets when multiple editors are present (proof of concept).

The next thing we tried was to add the icon repository to Locale, which is available in views. Unfortunately, because some views are created lazily (for better performance), the icon repository (which others may rely on to get icons) may not contain all icons until the user opens some views.

Finally, we tried moving icons to CSS (either storing them in CSS variables or registering those CSS variables using JavaScript), but this caused problems with multicolor icons (proof of concept).

We may need to revisit this issue after we deprecate the old installation methods, or after planned UI updates.

The CSS Shapes proposal also looks interesting: https://drafts.csswg.org/css-shapes-2/#shape-examples