DOC-3147: Refine migration guide for TinyMCE 8.0: update breaking change descriptions, enhance license key system details, and clarify DOMPurify sanitization impacts.

Author: kemister85

modules/ROOT/pages/migration-from-7x.adoc

@@ -19,33 +19,37 @@ Any items marked **"High"** level require immediate attention during migration.
 [cols="2,3,1",options="header"]
 |===
 |Breaking Change |Impact |Level
-|xref:license-key-system-update[License Key System Update]
+|xref:license-key-system-update[License Key System]
 |Self-hosted deployments now require a new license key format and license key manager. Old keys are **not compatible**.
 |High
 
-|xref:dompurify-update-breaking-change[DOMPurify Update and Stricter Sanitization]
-|Sanitization is now stricter; content previously allowed may be stripped or altered. See migration guide for details.
+|xref:dompurify-update-breaking-change[DOMPurify Update]
+|Sanitization is now stricter; content previously allowed may be stripped or altered.
 |High
 
-|xref:editor-selection-setcontent-deprecated[editor.selection.setContent] Deprecated
+|xref:editor-selection-setcontent-deprecated[editor.selection.setContent]
 |Method deprecated. Use `editor.insertContent` instead.
 |Medium
 
-|xref:fire-method-deprecation[fire()] Method Deprecation
+|xref:fire-method-deprecation[fire()]
 |Method deprecated. Use `dispatch()` for event handling.
 |Medium
 
-|xref:pagebreak-split-block-default[pagebreak_split_block Default Value]
+|xref:pagebreak-split-block-default[pagebreak_split_block]
 |The default value changed from `false` to `true`, affecting how page breaks interact with block elements.
 |Low
 
-|xref:editor-documentbaseurl-removal[editor.documentBaseUrl] Removal
+|xref:editor-documentbaseurl-removal[editor.documentBaseUrl]
 |Undocumented property removed. Use `editor.editorManager.documentBaseURI` instead.
 |Low
 
-|xref:skipfocus-consolidation[skipFocus and skip_focus] Consolidation
+|xref:skipfocus-consolidation[skipFocus and skip_focus]
 |Options consolidated to `skipFocus` in `ToggleToolbarDrawer`.
 |Low
+
+|xref:split-button-css-breaking-change[Split buttons]
+|Split button CSS classes and structure have changed.
+|Low
 |===
 ====
 
@@ -58,7 +62,9 @@ Any items marked **"High"** level require immediate attention during migration.
 This section applies to self-hosted installations only. For cloud deployments, license key management is handled automatically.
 ====
 
-{productname} {release-version} introduces an enhanced license key system that requires specific attention during migration. The complete licensing documentation xref:license-key.adoc[License Key Management] covers:
+{productname} {release-version} introduces an enhanced license key system that requires specific attention during migration.
+
+The complete licensing documentation xref:license-key.adoc[License Key Management] covers:
 
 * Detailed explanations of all license types (GPL, Commercial, GPL with Premium Features)
 * Time-based vs Version-locked license key differences
@@ -68,17 +74,22 @@ This section applies to self-hosted installations only. For cloud deployments, l
 * Commercial License Key Manager setup and requirements
 * Troubleshooting and FAQ
 
-==== Key Migration Considerations
+**Impact**: The new license key system introduces breaking changes that require updates to your configuration and code.
 
-* *License Key Format Change:* Version 7 keys are **not compatible** with {productname} {release-version}. New keys use the prefix `T8LK:` for commercial licenses or `GPL+T8LK:` for GPL with Premium Features.
-* *Mandatory Key Requirement:* Self-hosted deployments now **require** a valid license key; without one, the editor will be set to readonly.
-* *Commercial License Manager:* Self-hosted commercial deployments **require** the new license key manager addon.
+**Key Migration Considerations**:
 
-==== Migration Steps
+* *License Key Format Change:* Version 7 keys are:
+** Not compatible with {productname} {release-version}.
+** New keys use the prefix `T8LK:` for commercial licenses or `GPL+T8LK:` for GPL with Premium Features.
+* *Mandatory Key Requirement:* Self-hosted deployments **now require** a valid license key; without one, the editor will be set to `readonly`.
+* *Commercial License Manager:* Self-hosted commercial deployments **require** the new License Key Manager addon.
 
-. *Obtain New License Key:*
-** link:https://www.tiny.cloud/contact/[Contact us] to obtain a new {productname} {release-version} license key, or use `gpl` for the open source version. See: xref:license-key.adoc#setting-the-license[setting the license] for details.
+**Migration Steps:**
 
+. *Obtain New License Key:*
++
+* link:https://www.tiny.cloud/contact/[Contact us] to obtain a new {productname} {release-version} license key, or use `gpl` for the open source version. See: xref:license-key.adoc#setting-the-license[setting the license] for details.
++
 . *Update Configuration:*
 +
 [source, javascript]
@@ -98,11 +109,12 @@ tinymce.init({
 
 ==== License Key Manager Setup
 
-When migrating to TinyMCE {release-version} with a commercial license, the license key manager addon is required for the editor to operate. The setup varies based on your deployment method:
+When migrating to {productname} {release-version} with a commercial license, the License Key Manager addon is required for the editor to operate. The setup varies based on your deployment method:
+
+*CDN/Static Hosting:*
+
+* Ensure the supplied `licensekeymanager` folder is in your {productname} plugins directory:
 
-. *CDN/Static Hosting:*
-** Ensure the supplied `licensekeymanager` folder is in your {productname} plugins directory:
-+
 [tree]
 ----
 your-site/
@@ -114,9 +126,10 @@ your-site/
 │   └── ... other plugins
 ----
 
-. *NPM/Module Bundler:*
-** Install TinyMCE and ensure the license key manager is imported:
-+
+*NPM/Module Bundler:*
+
+Install {productname} and ensure the license key manager is imported:
+
 [source, javascript]
 ----
 // Import TinyMCE
@@ -131,9 +144,10 @@ tinymce.init({
 });
 ----
 
-. *React/Next.js:*
-** When using the `@tinymce/tinymce-react` package:
-+
+*React/Next.js:*
+
+When using the `@tinymce/tinymce-react` package:
+
 [source, javascript]
 ----
 import { Editor } from '@tinymce/tinymce-react';
@@ -150,24 +164,25 @@ export default function MyEditor() {
 }
 ----
 
-. *PHP/Laravel:*
-** Ensure the license key manager is included when publishing {productname} assets:
-+
+*PHP/Laravel:*
+
+Ensure the license key manager is included when publishing {productname} assets:
+
 [source, php]
 ----
 <script src="{{ asset('path/to/tinymce/tinymce.min.js') }}"></script>
 <script src="{{ asset('path/to/tinymce/plugins/licensekeymanager/plugin.min.js') }}"></script>
 <script>
-tinymce.init({
-  selector: '#editor',
-  license_key: 'T8LK:...'
-});
+  tinymce.init({
+    selector: '#editor',
+    license_key: 'T8LK:...'
+  });
 </script>
 ----
 
 [IMPORTANT]
 ====
-* The license key manager is automatically included when using Tiny Cloud.
+* The license key manager is automatically included when using {companyname} Cloud.
 * The plugin does not need to be added to the `plugins` configuration option.
 * For bundled applications, the license key manager must be loaded before {productname} initialization.
 * For bundled applications, ensure the license key manager is not excluded during build optimization.
@@ -196,14 +211,20 @@ This change improves security and aligns with DOMPurify's recommended defaults.
 
 ==== Key Changes
 
-* **DOMPurify upgraded to 3.2.6** — The custom patch is now included upstream; maintaining a forked patch is no longer required.
+* **DOMPurify upgraded to 3.2.6**
 * **`SAFE_FOR_XML` enabled** — This setting enforces stricter handling of comments and attribute values, preventing certain XSS vectors.
 * **Content Impact** — HTML comments containing tags, Internet Explorer conditional comments, and attributes with HTML-like values may now be removed during sanitization. Content that was previously allowed may be stripped.
 
-==== Migration Guidance
+*Impact*: This change improves security by preventing potential XSS attacks through comments and attributes that were previously allowed. However, it may also result in content being stripped or altered unexpectedly.
+
+**Migration Steps:**
 
 * Review workflows and test content that previously relied on relaxed sanitization.
-* If custom comment handling is required, consider using DOMPurify hooks as recommended by the maintainers.
+* If custom comment handling is required, note that DOMPurify hooks cannot be used directly unless you fork TinyMCE or disable TinyMCE's built-in sanitization and implement your own with DOMPurify.
+* {productname} now provides the xref:content-filtering.adoc#allow_html_in_comments[Content Filtering: allow_html_in_comments option] option. Enabling this option allows HTML tags in comments with sanitization still enabled. 
+
+[WARNING]
+Using `allow_html_in_comments` increases the risk of XSS vulnerabilities. xref:security.adoc#allow_html_in_comments[allow_html_in_comments] is not recommended for production use unless you fully understand the implications and have appropriate security measures in place.
 
 .Example: Content Differences
 |===
@@ -227,6 +248,46 @@ This change improves security and aligns with DOMPurify's recommended defaults.
 For information on disabling DOMPurify sanitization (not recommended), see xref:security.adoc#xss_sanitization-option[xss_sanitization option].
 ====
 
+== Core Changes
+
+[[split-button-css-breaking-change]]
+=== Split button CSS structure updates
+// #TINY-8665
+
+{productname} {release-version} updates the internal structure of split buttons. Split buttons now render as two separate components with updated CSS classes:
+
+* `.tox-split-button__main` — Main action button
+* `.tox-split-button__chevron` — Dropdown chevron button
+
+**Impact**: This change improves the flexibility of split button styling and allows for more granular control over each component.
+
+**Migration steps:**
+
+Update all CSS selectors and styles that previously targeted the unified `.tox-split-button` class to target the new `.tox-split-button__main` and `.tox-split-button__chevron` classes.
+
+[source,css]
+----
+/* Before TinyMCE 8.0 */
+.tox-split-button {
+  /* Previous styling approach */
+}
+
+/* TinyMCE 8.0+ */
+.tox-split-button__main {
+  /* Main button styling */
+}
+
+.tox-split-button__chevron {
+  /* Chevron button styling */
+}
+----
+
+**Migration checklist:**
+
+* [ ] Search your CSS for `.tox-split-button` and update to use `.tox-split-button__main` and `.tox-split-button__chevron`.
+* [ ] Test all split button styles in your application to ensure they render correctly.
+* [ ] Update any custom plugins that use split buttons to reflect the new structure.
+
 == Core API Changes
 
 [discrete]
@@ -243,6 +304,12 @@ IMPORTANT: The following sections detail important changes that require updates
 
 The `editor.selection.setContent` API has been deprecated and will be removed in {productname} 9.
 
+*Impact*: This change simplifies content manipulation by consolidating insertion methods.
+
+**Migration steps:**
+
+To replace `editor.selection.setContent`, use `editor.insertContent` instead. The new method is more consistent with other content manipulation methods in {productname}.
+
 .Example Usage
 [source,javascript]
 ----
@@ -253,8 +320,6 @@ editor.selection.setContent('<p>New content</p>');
 editor.insertContent('<p>New content</p>');
 ----
 
-*Impact*: This change simplifies content manipulation by consolidating insertion methods.
-
 **Migration checklist:**
 
 * [ ] Replace all instances of `editor.selection.setContent` with `editor.insertContent`
@@ -282,7 +347,9 @@ console.log('documentBaseURI', editor.documentBaseURI.getURI());
 
 TIP: Use `tinymce.activeEditor.documentBaseURI.getURI()` for all base URL operations.
 
-.Required Changes
+**Impact**: This change improves URL handling consistency by removing an undocumented API that was not aligned with the documented `documentBaseURI` property.
+
+**Migration steps:**
 
 To update all references of `documentBaseUrl` to the new API, replace any usage of `editor.documentBaseUrl` (or similar) with `tinymce.activeEditor.documentBaseURI.getURI()`. The property `documentBaseUrl` has been removed, and the correct way to access the document base URL is now through the `documentBaseURI` property, which is a URI object. You can then call `.getURI()` on it to get the string value of the URL.
 
@@ -316,6 +383,10 @@ For more information see: link:https://www.tiny.cloud/docs/tinymce/latest/apis/t
 
 The `skipFocus` and `skip_focus` options for the `ToggleToolbarDrawer` command have been consolidated into a single, more consistent argument. This reduces API complexity and clarifies the intended behavior.
 
+**Impact**: This change simplifies focus management, reducing the risk of confusion and unexpected behavior.
+
+**Migration steps:**
+
 [source, javascript]
 ----
 // Old approach (Deprecated) in TinyMCE 8
@@ -325,8 +396,6 @@ editor.execCommand('ToggleToolbarDrawer', { skip_focus: false }, { skipFocus: tr
 editor.execCommand('ToggleToolbarDrawer', false, { skipFocus: true });
 ----
 
-**Impact**: This change simplifies focus management, reducing the risk of confusion and unexpected behavior.
-
 **Migration checklist:**
 
 * [ ] Locate all instances of `ToggleToolbarDrawer` command usage
@@ -403,7 +472,7 @@ The Image and Accessibility Checker plugins now follow the latest W3C standards
 **Migration checklist:**
 
 * [ ] Identify images previously using `role="presentation"` for decorative purposes in your content
-* [ ] Replace those with empty alt attributes (`alt=""`)
+* [ ] Replace those with empty alt attributes `alt=""`
 * [ ] Update image plugin configuration if customized
 * [ ] Test accessibility checker with updated content
 
@@ -554,8 +623,8 @@ Upgrading to {productname} {release-version} requires integrators to update thei
 
 For more guidance, refer to the:
 
-* link:https://www.tiny.cloud/docs[{productname} Documentation],
-* Utilize our in-house **Ask AI** widget for general support found in the bottom corner of every documentation page, or
+* link:https://www.tiny.cloud/docs[{productname} Documentation].
+* {productname}’s new **Ask AI** widget is ready to assist you, just click the icon in the bottom-right corner of any documentation page.
 * link:https://www.tiny.cloud/contact/[Contact {supportname}] for assistance.
 
 For additional details on {productname} {release-version} changes, see xref:8.0-release-notes.adoc#overview[{productname} {release-version} release notes].