## Problem/Motivation Every composition editor in this module is an optional submodule — except the two GrapesJS ones, which sit in the base module for no reason other than that they were built first (#3615583, before the submodule pattern existed). | Editor | Ships as | |---|---| | Mosaico | `campaign_mosaico` | | EmailBuilder.js | `campaign_emailbuilder` | | easy-email-editor | `campaign_easy_email` | | **GrapesJS Newsletter** | **base module** | | **GrapesJS MJML** | **base module** | The inconsistency has costs beyond tidiness: - **The base module carries editor-specific weight it does not need.** Five library definitions in `campaign.libraries.yml`, three JS files under `js/`, a `hook_requirements()` implementation in `campaign.install` that exists solely to warn about missing GrapesJS libraries, and a config schema entry — all of it inert on a site that never uses GrapesJS, which is every site that picked one of the other three editors. - **The pattern reads as arbitrary to a newcomer.** `README.md` documents GrapesJS under "optional" and then documents Mosaico, EmailBuilder.js and easy-email as "optional submodule", with no stated reason for the difference. There is none. - **It complicates the plugin-type story.** The module's pitch is that composition is a plugin type others implement. Two reference implementations living inside the base module blur where the contract ends and an implementation begins. Doing this **before the first release** matters: no version has been tagged from `1.0.x` yet, so today this affects `1.0.x-dev` sites only and needs an update hook rather than a documented breaking change. After `1.0.0-alpha1` it becomes a support burden. ## Proposed resolution Create `modules/campaign_grapesjs` and move both plugins into it, mirroring the submodule shape already established by `campaign_emailbuilder` (a `campaign:campaign` dependency, core requirement kept in lockstep with the base module). What moves: - `src/Plugin/Campaign/Composition/GrapesJsNewsletter.php`, `src/Plugin/Campaign/Composition/GrapesJsMjml.php` - `src/Composition/GrapesJsCompositionBase.php` — GrapesJS-specific, unlike `SiteLibrariesTrait` - `js/grapesjs.newsletter.js`, `js/grapesjs.mjml.js`, `js/grapesjs.asset-manager.js` - the five GrapesJS library definitions in `campaign.libraries.yml` - the `campaign_grapesjs` half of `campaign_requirements()` in `campaign.install` - `campaign.composition.plugin.grapesjs_newsletter` in `config/schema/campaign.schema.yml` - `tests/src/FunctionalJavascript/GrapesJsEditorTestBase.php`, `GrapesJsNewsletterTest.php`, `GrapesJsMjmlTest.php`, `tests/src/Kernel/GrapesJsAvailabilityTest.php` What stays: `SiteLibrariesTrait` (shared by all four editors), `CompositionPluginBase`, `CompositionManager`, the asset uploader service, and `CompositionEditorTestBase`. ### Decisions (settled in MR !25) - **Does `campaign.asset_upload` move too?** **Yes — it moved**, and its route was renamed `campaign_grapesjs.asset_upload` at `/campaign-grapesjs/asset/upload`. This was decided on precedent rather than taste: #3615645 faced the same question and chose per-editor protocol shims over one shared multi-format endpoint, converging Mosaico onto the base module's *service*, *permission*, *directory* and *usage tracker* — but explicitly not onto the controller. `campaign_mosaico.upload` is that shim and lives in Mosaico's own submodule; `AssetUploadController` is the GrapesJS counterpart, and its own docblock already conceded the response is "the shape the GrapesJS Asset Manager consumes". The base module keeps `AssetUploader`, `AssetUploadResult`, `AssetUsageTracker`, the restricted `upload campaign assets` permission and `public://campaign/images` — which is what "editor-agnostic" actually referred to. Moving it also takes an unused POST upload endpoint off every site running one of the other three editors. - **One submodule or two?** **One** (`campaign_grapesjs`). Beyond the shared base class and libraries, per-plugin granularity already exists *without* module granularity: `grapesjs-preset-newsletter` and `grapesjs-mjml` are separate npm packages, so `SiteLibrariesTrait` hides whichever plugin's library is absent. A site installing only `grapesjs-mjml` already sees only the MJML plugin, so splitting the module would buy nothing. - **Schema gap surfaced by the inventory.** **Already closed before this issue was worked** — #3615658 added `campaign.composition.plugin.grapesjs_mjml`, derived from the plugin's `defaultConfiguration()` rather than a test fixture, and proved the assertion covering it is no longer a tautology. It was a genuine omission, not deliberate. Both entries simply moved, and the tautology proof was re-run at the new location. ### Upgrade path Existing messages store the composition plugin id (`grapesjs_newsletter`, `grapesjs_mjml`) in a revisionable field. If the plugins move and the new submodule is not enabled, those messages lose their composition plugin — the manager drops unavailable definitions, and re-editing breaks. **This shipped without `hook_update_N()`** — a deliberate decision, not an omission. Site owners tracking `1.0.x-dev` enable `campaign_grapesjs` themselves, guided by a new README subsection that states the consequence plainly: with the submodule disabled, an existing message using either plugin has no composition plugin to open, and nothing warns at update time. Already-sent messages are unaffected, since their rendered body is stored on the message. That documentation is therefore the only mitigation. The hook remains available as a follow-up if `1.0.x-dev` breakage proves noisier than expected; it would scan all revisions of `campaign_message` for the two plugin ids, and would need a re-created `campaign.install`, since `hook_update_N()` has no OOP form. No released version ever shipped these plugins, so this is a `1.0.x-dev` concern only, and the README already carries a precedent for documenting exactly that (the Mosaico image directory move under "Upgrading a `1.0.x-dev` site"). ## Remaining tasks All complete in MR !25. Two entries below differ from the list this issue was filed with, and both are recorded above: - [x] Create the submodule; move code, JS, libraries, schema and tests. - [x] ~~Split `campaign_requirements()`~~ — **deleted `CampaignRequirements` outright** and added `\Drupal\campaign_grapesjs\Hook\GrapesJsRequirements`. This issue was filed before #3615656 replaced the procedural `campaign_requirements()` with an OOP `#[Hook]` class, and that class turned out to be *entirely* the GrapesJS check — so with GrapesJS gone the base module had no runtime requirement left to report and nothing to split. - [x] ~~Add the update hook that installs the submodule for affected sites.~~ **Deliberately not shipped** — see Upgrade path above. - [x] Update `README.md` (the GrapesJS section is now an optional submodule, with a `drush pm:enable campaign_grapesjs` step and its own "Upgrading a `1.0.x-dev` site" subsection) and `docs/architecture.md` (the "One asset surface, two protocols" section is rewritten: the base module owns the surface, each editor submodule owns its protocol adapter). - [x] Keep the `.gitlab-ci.yml` library download step working — its `$_WEB_ROOT/libraries/...` targets are site-level paths and were left untouched; only its authoritative-record comment changed. The moved FunctionalJavascript tests are confirmed **executed, not self-skipped** in CI, on both current core and Drupal 11.3.14 (the declared floor). - [x] Confirm phpstan still covers the moved code and that the full suite is green. ## API changes **Breaking for `1.0.x-dev` sites.** `Drupal\campaign\Composition\GrapesJsCompositionBase` and both plugin classes change namespace to `Drupal\campaign_grapesjs\…`. The plugin **ids** (`grapesjs_newsletter`, `grapesjs_mjml`) and their stored configuration shapes do not change, so message content survives; only the class names and the requirement to enable a module do. Library names change from `campaign/grapesjs*` to `campaign_grapesjs/*`. The asset upload endpoint moved with the plugins and was **renamed**: the route `campaign.asset_upload` at `/campaign/asset/upload` becomes `campaign_grapesjs.asset_upload` at `/campaign-grapesjs/asset/upload`, and `\Drupal\campaign\Controller\AssetUploadController` becomes `\Drupal\campaign_grapesjs\Controller\AssetUploadController`. Its `upload campaign assets` permission requirement, its `_csrf_token` mechanism and its `{"data": [...]}` wire format are unchanged. In-repo the URL is only ever generated server-side via `Url::fromRoute()` and reaches the editor JS through `drupalSettings`, so nothing hardcodes it; the CSRF token derives from the same `Url` object's internal path and follows the rename automatically. AI-Generated: Yes (Used Claude Code Opus 5 to generate the text of this issue.)