Roadmap to CKEditor 5 stable in Drupal 9

This lays out what remains to be done after #3231364: Add CKEditor 5 module to Drupal core lands in Drupal core.

This plan was originally taken from the IS at #2966864: Add optional support for CKEditor 5 in D9 so we can remove CKE 4 from Drupal 10, and after that from #3201824: Roadmap to core.

Roadmap to Stable

1. Ensure that sites can update from using CKE4 to CKE5 safely when using no contributed CKEditor modules
   1. #3247634: [PP-1] [upstream] [drupalImage] Unlinking linked inline images while GHS is enabled: wrapping <a> is impossible to remove
   2. #3268306: [upstream] [GHS] Custom/unofficial HTML tags not retained: <drupal-media>, <drupal-entity>, <foobar>
   3. #3271418: [PP-1] [upstream] [drupalMedia] Linked media wrapped with <div> doesn't upcast correctly
   4. #3274651: Impossible to enable <ol type> or <ul type> with GHS
   5. #3276217: [drupalMedia] GHS attributes are not retained in linked media
   6. #3273983: Do not assume that plugin supporting <tag attr> also supports <tag> in SourceEditingRedundantTags and upgrade path
2. ✅ Ensure contrib modules can do everything: translations, automatic upgrade path from CKE4 …
   1. Currently none
3. ✅ Ensure CKE5 equivalent plugins of CKE4 generate/support equivalent markup: #3222801: [META] Ensure CKE5 equivalent plugins of CKE4 generate/support equivalent markup
   1. Currently none
4. Ensure CKE5 functionality matches that of Drupal core's CKE4:
   1. #3222756: [upstream] Allow using images from external source
   2. #3222797: Upgrade path from CKEditor 4's StylesCombo to CKEditor 5's Style
   3. #3274937: Get CKEditor 5 to work in (modal) dialogs
5. ✅ Documentation gates:
   1. Currently none
6. ✅ Theming CKEditor 5
   1. Currently none
7. ✅ Accessibility
   1. Currently none
8. Test coverage, reliability and maintainability matching or exceeding CKEditor 4's:
   1. #3247683: Disable CKEditor 5's automatic link decorators (in Drupal filters should be used instead) + explicitly test manual link decorators
   2. #3268983: [regression] FilterHtml throws Unsupported operand types error when * used in tag attribute
9. ✅ Low-hanging fruit major UX improvements over CKEditor 4:
   1. Currently none
10. Superior configuration UX:
    1. #3245967: Messages upon switching to CKEditor 5 are overwhelming
11. ✅ Performance
    1. Currently none.

Roadmap after Stable

1. Upstream Drupal improvements that would simplify or improve CKEditor 5:
   1. #3226673: API addition: \Drupal\editor\Plugin\EditorPluginInterface::getDefaultSettings() should accept old Editor + Format to generate smart defaults
   2. #3230829: editor_form_filter_format_form_alter() does not remove "editor_plugin" from form state when needed
   3. #3231322: Fix a @todo: move a form alteration to the CKEditor 5 plugin's subform definition
   4. #3231341: Deprecate EditorLinkDialog and EditorImageDialog in Drupal 9, remove in Drupal 10
   5. #3231342: Introduce ConfigEntityForm to standardize use of validation constraints for config entities
   6. #3231347: Add Editor::setFilterformat()
   7. #3231354: [META] Discuss: merge the Editor config entity into the FilterFormat config entity
   8. #3246260: [PP-1] Simplify CKEditor5ImageController once #2940383 lands
   9. #3263668: [PP-1] Re-enable inline form errors in assessActiveTextEditorAfterBuild function→ blocked on Vertical Tabs bug: #2911932: Correct vertical tab does not focus on form validation
   10. #3269101: [PP-1] Ensure enabled CKEditor 5 plugins remain available by calculating corresponding dependencies→ blocked on Text Editor module bug: #2950795: CKEditor 4+5 plugin module dependency not added to text format configuration
2. Obsoleteness of upgrade path in Drupal 11:
   1. #3239012: [late 2023] Deprecate the upgrade path from CKEditor 4
3. Performance:
   1. #3224261: [PP-2] Front-end performance: concatenate CKEditor 5 JS assets for every unique configuration
4. Media improvements
   1. #3196593: Ease the transition to Media: save image uploads in CKEditor 5 as media entities when media is enabled? (or module specific solution if core issue won't land)
   2. #3073901: Determine an upgrade path from CKEditor image button to media library (or module specific solution if core issue won't land)
5. Low-hanging fruit major UX improvements over CKEditor 4:
   1. #3227354: Add support for ckeditor5-autoformat
   2. #3274635: [PP-2] Use CKEditor 5's native <ol type> and <ul type> UX
6. Superior configuration UX:
   1. #3225033: Whenever "Enable image uploads" is enabled for a text editor, the editor_file_reference filter should be enabled
   2. #3227948: Hide incompatible filters
7. Maintainability:
   1. #3248432: [drupalImage] Split DrupalImageEditing into multiple plugins
   2. #3273746: Move media-embed-error class styling from core themes to CKEditor 5
   3. #3275237: Don't convert, instead use response.entity_type in DrupalImageUploadEditing

Completed

This section mimics the structure of the above sections.

💯 Roadmap to Alpha

1. ✅ Create the ckeditor5 module
2. ✅ Create an @Editor PHP plugin with the ID ckeditor5.
3. ✅ Create a Drupal.editors JS plugin with the ID ckeditor5.
4. ✅ Getting CKE5 (CKEditor 5) to load at all on the /node/add/article form.
5. ✅ #3201820: Manually test that CKE 5 can be used in off-canvas
6. ✅ Enable a Drupal + CKE5 ecosystem
   1. #3196178: Provide test module to verify contrib can extend CKEditor5
   2. #3200008: Validation and editor settings
7. ✅ A CKE5 configuration UI
   1. #3198297: Toolbar UI for selecting and sorting buttons
8. ✅ Ensure Quick Edit integration works
   1. #3201648: Add test coverage for Quick Edit integration
   2. #3205090: Field html not restored when cancelling Quick Edit
9. ✅ Evaluate CK4 plugins and match features
   1. #3194650: Support media elements and browse media library
   2. #3194111: Support inline image upload
   3. #3201646: Add support for image caption (<img data-caption>)
10. ✅ #3201821: Add JavaScript test coverage for CKE 5
11. ✅ #3206686: IE11 warning for CKE5 in Drupal 9

💯 Roadmap to Beta

1. ✅ #3215506: Plugins should be enableable based on toolbar configuration
2. ✅ Ensure filter_html's HTML restrictions are respected inside CKE5 — tackled in #3201637: Figure out how to prevent data loss during upgrade/migration path
3. ✅ #3206687: Toolbar UI accessibility review
4. ✅ #3201641: Improve the HTML filter configuration UX
5. Enable translation features for CKEditor 5
   1. ✅ #3202664: CKEditor 5's UI language should match Drupal's interface translation

Roadmap to Stable

1. Ensure that sites can update from using CKE4 to CKE5 safely when using no contributed CKEditor modules
   1. Ensure that Arbitrary HTML is not lost: #3216021: Automatically use CKE5's General HTML Support feature on text formats without any TYPE_HTML_RESTRICTOR filter + add `sourceEditing` button
   2. #3201637: Figure out how to prevent data loss during upgrade/migration path
   3. #3216015: Generate CKEditor 5 configuration based on pre-existing text format configuration
   4. #3245079: Automatic upgrade path always enables all <h*> tags when only >=1 was enabled before
   5. #3245320: Automatic upgrade path always disables image uploads — in the UI
   6. #3228464: API for contrib projects to load CKEditor translations
   7. #3227822: [GHS] Ensure GHS works with our custom plugins, to allow adding additional attributes
   8. #3268174: Bug in CKE 4 → 5 upgrade path "format" does not always map to "heading", it could map to "codeBlock" too, or both, or neither
   9. #3269868: [drupalImage] Some Image attributes are lost in edge cases where image upcasts into inline image
   10. #3273527: Upgrade path never configures the ckeditor5_heading plugin to allow <h1>
   11. #3273312: Upgrading from CKEditor 4 for a text format that has FilterInterface::TYPE_MARKUP_LANGUAGE filters enabled
   12. #3268318: [drupalMedia] <a> with GHS allowed attributes downcast wraps data-caption with <a>
   13. #3230230: Enable table captions; override CKE5's default downcast to generate <table><caption></table> instead of <figure><table><figcaption></figure>
   14. #3268311: [upstream] [drupalMedia] GHS-enabled markup in data-caption crashes CKEditor 5
   15. #3272516: Deprecate FilterInterface::getHTMLRestrictions()' forbidden_tags functionality
   16. #3273510: CKEditor 5 crash when multiple alignment buttons are activated due to duplicate configuration thanks to #3259593: Alignment being available as separate buttons AND in dropdown is confusing
2. Ensure contrib modules can do everything: translations, automatic upgrade path from CKE4 …
   1. #3226335: Follow-up for #3216015: allow contrib & custom Drupal modules providing CKEditor 4 plugins to specify their CKEditor 5 equivalents + settings to be migrated
   2. #3228778: Drupal-specific CKEditor 5 plugins should be able to use Drupal's JS translation API: Drupal.t()
   3. #3245723: Follow-up for #3201637: omitting PrimitiveTypeConstraint violations for filter settings is implemented too broadly
   4. #3245807: DX: allow contrib modules to subclass \Drupal\Tests\ckeditor5\Kernel\ValidatorsTest
   5. #3274278: Migrate "codetag" contrib CKEditor 4 plugin to built-in equivalent in core's CKEditor 5
   6. #3273325: CKE5 and contrib: better "next action" description on upgrade path messages
3. Ensure CKE5 equivalent plugins of CKE4 generate/support equivalent markup: #3222801: [META] Ensure CKE5 equivalent plugins of CKE4 generate/support equivalent markup
   1. Infra: #3215466: Attribute values not accounted for in CKEditor5PluginManager::getProvidedElements
   2. Infra: #3207660: Allow using a subset of the tags supported by the enabled CKEditor 5 plugins
   3. #3222851: <cite>
   4. #3222847: <img width height>
   5. #3222838: Configure basicStyles.Italic to output <em> instead of <i>
   6. #3222842: <a hreflang> + <blockquote cite>
   7. #3222847: <img width height>
   8. #3220293: Make all supported heading types visible in the UI
   9. #3222840: <ol start>
   10. #3222852: <dl> <dt> <dd> by introducing "Manually editable HTML tags" configuration on Source Editing
   11. #3224256: <h* id> (or more generically: <$block id>)
   12. #3222808: Follow-up for #3201646: markup in image captions is lost
   13. #3228346: Follow-up for #3222852: revert ineditable attributes (<blockquote cite> and <a hreflang>) now that Source Editing plugin can handle arbitrary elements & attributes
   14. #3246168: Images are not linkable through UI; already linked images are unlinked (data loss!)
   15. #3246169: Embedded media are not linkable through UI; already linked embedded media are unlinked (data loss!)
   16. #3259493: [GHS] Unable to limit attribute values: ::allowedElementsStringToHtmlSupportConfig() does not generate configuration that CKEditor 5 expects
   17. #3246365: [drupalMedia] Show the Image Media's default alt text that is being overridden
   18. #3260853: [GHS] Partial wildcard attributes (<foo data-*>, <foo *-bar-*>, <foo *-bar>) and attribute values (<h2 id="jump-*">) not yet supported
   19. #3260869: Resolve mismatch between <$block> interpretation by CKEditor 5 and Drupal
   20. #3268860: Elements wrapping <drupal-media> are not retained
   21. #3268307: $block wildcard resolves into a superset of the actual $block tags
4. Ensure CKE5 functionality matches that of Drupal core's CKE4:
   1. #3201646: Add support for image caption (<img data-caption>)
   2. #3211050: Add "Alignment" plugin
   3. #3211125: Add "Block Indentation" plugin, but only allow list indentation
   4. #3211282: Add plugins which are provided as a part of essential plugin: Undo/Redo
   5. #3211610: Add "Horizontal line" plugin.
   6. #3227871: Add ckeditor5-paste-from-office to allow pasting from Microsoft Office & Google Docs
   7. #3227875: Add ckeditor5-remove-format to allow removing formatting from pasted content
   8. #3227890: Add ckeditor5-special-characters to allow inserting special characters for users that do not know the native picker
   9. #3247246: Attribute value encoding not compatible with Xss::filter()
   10. #3248448: Dialog loading text is unstyled
   11. #3260554: [drupalMedia] Support alignment on <drupal-media>
   12. #3246380: [drupalMedia] Media previews do not update after alt text was modified
   13. #3224652: [drupalImage] Add ckeditor5-image's imageresize plugin to allow image resizing
   14. #3246385: [drupalMedia] Support captions on <drupal-media>
   15. #3264775: [drupalMedia] Toolbar should be visible when element inside <drupalMedia> is focused
   16. #3264727: [drupalMedia|drupalImage] Allow removing data-align in the UI, and making an image inline
   17. #3245950: [upstream] <script> tag support in GHS
   18. #3256566: [upstream] <style> tag support in GHS
   19. #3263384: Add ckeditor5-code-block package and CodeBlock plugin
   20. #3245720: [drupalMedia] Support choosing a view mode for <drupal-media>
   21. #3276974: [drupalMedia] Media View Modes don't work if alignment not enabled
   22. #3269657: [drupalMedia] The CKEditor 4 → 5 upgrade path for the media_embed filter should not forcefully allow the `data-view-mode` attribute on `<drupal-media>`
5. ✅ Documentation gates:
   1. #3205654: ckeditor5_hook_help()
   2. #3201186: Create ckeditor5.api.php (the core equivalent of README.md) + CKEditor5PluginDefinition::toArray()
   3. #3243850: hook_ckeditor5_plugin_info_alter()'s example sets ['drupal']['config'], but that's not one of the documented definition properties
   4. #3248430: Improve Drupal.ckeditor5 documentation
   5. #3248425: Ensure that all classes and functions in Drupal-specific CKEditor 5 plugins are documented
6. Theming CKEditor 5
   1. #3202666: Follow-up for #3198297 Improve admin CSS DX
   2. #3194084: Support functionality equivalent to ckeditor_stylesheets
7. Accessibility
   1. #1872206: Improve CKEditor toolbar configuration accessibility
   2. #3218252: Toolbar configuration fieldset aria cleanup
   3. #3218260: Safari focus outline on buttons leaves artifacts after blur
   4. #3207451: Toolbar UI Button size accessibility
   5. #3238257: Fragment link pointing to <textarea> should be redirected to CKEditor 5 instance when CKEditor 5 replaced that textarea
   6. #3245735: Follow-up for #3222852: validation errors are not associated with the correct form element
   7. #3258030: Text fields using CKEditor 5 do not get visual error indicator
   8. #3258668: Extraneous closing parentheses and curly brace in visually-hidden button description text
   9. #3231321: Improve keyboard accessibility in a particular edge case
   10. #3261942: Compatibility issues with inline form errors
   11. #3218297: Voiceover + Safari reads aria-describedby twice when focusing toolbar button
   12. #3248440: [drupalMedia] Media embed attributes are rendered in container div in editing view
   13. #3239423: Toolbar UI accessibility review: round 2
   14. #3270112: Excessive aria-live announcing from ckeditor5-admin-help-message live region
   15. #3270110: Toolbar config items missing "press arrow to do {x}" instructions for screenreaders
   16. #3270108: Editor does not load when using Edge + WHCM
   17. #3222757: [drupalImage] Make image alt text required or strongly encouraged
8. Test coverage, reliability and maintainability matching or exceeding CKEditor 4's:
   1. #3206522: Add FunctionalJavascript test coverage for media library
   2. #3201641: Improve the HTML filter configuration UX
   3. #3228920: Improve internal consistency: consistent variable names and return type syntax
   4. #3231327: Plugin definition DX: validate ckeditor5.drupal.elements items
   5. #3231362: Refactor ImageUpload's ::validateImageUploadSettings() into the proper validate and submit methods
   6. #3228505: Plugin definition DX: automatically check for plugin definitions whether their ::getDefaultSettings() matches the config schema
   7. #3243867: ckeditor5_module_implements_alter() looks like it has incorrect logic
   8. #3245400: Add an @throws PHPDoc everywhere exceptions are thrown
   9. #3246280: Defense in depth: add anti-CSRF token to this module's routes
   10. #3246521: Make plugin.manager.ckeditor4to5upgrade.plugin a private service
   11. #3246524: Make more (all?) classes @internal
   12. #3247711: Simplify and accelerate builds: update our use of the CKEditor 5 DLL manifest
   13. #3248188: Plugin definition DX: validate drupal.conditions
   14. #3248423: Decide how CKEditor 5-provided types should be referenced
   15. #3259174: Add missing CKE5 SmartDefaultSettings test coverage (wildcard tag with unsupported attribute)
   16. #3228334: Refactor HTMLRestrictionsUtilities to a HtmlRestrictions value object
   17. #3206523: Add FunctionalJavascript test coverage for image upload
   18. #3267721: Add DrupalCI step for ensuring that CKEditor 5 build files are build correctly
   19. #3231337: [drupalMedia] Remove manual dataDowncast from DrupalMediaEditing
   20. #3231328: SmartDefaultSettings should select the CKE5 plugin that minimizes creation of HTML restriction supersets
   21. #3228580: Follow-up for #3222852: additional test coverage for real-time validation race conditions
   22. #3265626: Changes to "Manually editable HTML tags" lost if form is submitted without triggering AJAX
   23. #3231334: Global attributes (<* lang> and <* dir="ltr rtl">): validation + support (fix data loss)
   24. #3229078: Unit tests for all @CKEditor5Plugin plugin classes
9. Low-hanging fruit major UX improvements over CKEditor 4:
   1. #3261599: Use CKEditor 5's native <ol start> support (and also support <ol reversed>)
10. Superior configuration UX:
    1. #3201641: Improve the HTML filter configuration UX
    2. #3216015: Generate CKEditor 5 configuration based on pre-existing text format configuration
    3. #3226694: Follow-up for #3216015: refactor SmartDefaultSettings to return messages rather than sending them
    4. #3248177: Language toolbar item cannot be removed from the toolbar
    5. #3259443: Plugin settings do not appear when a configurable plugin is added AFTER removing all buttons
    6. #3261585: Remove IE11 warning for CKEditor 5 in Drupal 10, since Drupal 10 does not support IE anyway
    7. #3260857: Expand SourceEditingRedundantTagsConstraintValidator to also check attributes and attribute values
    8. #3261943: Confusing behavior after pressing "Apply changes to allowed tags" with invalid value
    9. #3228691: Restrict allowed additional attributes to prevent self XSS
11. Performance
    1. #3248469: Research if the CKE off-canvas CSS reset could be optimized
    2. #3264512: Enable aggregation for CKEditor 5 assets
    3. #3260032: CKEditor 5 adds ie11.user.warnings library to every page, triggering a FOUC even for anonymous users
12. ✅ Moving things into core that can only happen once it is in core:
    1. #3231324: Use core icons where possible after moving to core
    2. #3231325: Use pre-existing filter format config from YAML instead of duplicating it in PHP