[x-license] Improve v9 license key version mismatch error guidance

docs/data/introduction/licensing/licensing.md

@@ -124,13 +124,7 @@ This is [the relevant clause in the EULA.](https://mui.com/legal/mui-x-eula/#req
 When you purchase a commercial license, you'll receive a license key by email.
 This key removes all watermarks and console warnings.
 
-:::warning
-If you're upgrading from v8 to v9, you'll need to generate a new license key from your [MUI Store account](https://mui.com/store/account/orders/).
-The new v9 key will have the same expiration date as your existing v8 key.
-
-Upon renewal, you'll need to choose which license key to renew.
-Note that renewing a v9 license key is priced differently from a v8 renewal.
-:::
+{{"component": "modules/components/V9LicenseUpgradeWarning.js"}}
 
 :::warning
 Orders placed after **May 13, 2022** come with a license key by default that is only compatible with MUI X from `v5.11.0` and upwards.

docs/data/migration/migration-charts-v8/migration-charts-v8.md

@@ -186,6 +186,10 @@ Follow the [Material UI migration guide](/material-ui/migration/upgrade-to-v9/)
 +"@mui/system": "^7.3.0",
 ```
 
+## Update your license key (Pro and Premium)
+
+{{"component": "modules/components/V9LicenseUpgradeWarning.js"}}
+
 ## Run codemods
 
 The `preset-safe` codemod will automatically adjust the bulk of your code to account for breaking changes in v9. You can run `v9.0.0/charts/preset-safe` targeting only Charts or `v9.0.0/preset-safe` to target the other packages as well.

docs/data/migration/migration-data-grid-v8/migration-data-grid-v8.md

@@ -47,6 +47,10 @@ Follow the [Material UI migration guide](/material-ui/migration/upgrade-to-v9/)
 +"@mui/system": "^7.3.0",
 ```
 
+## Update your license key (Pro and Premium)
+
+{{"component": "modules/components/V9LicenseUpgradeWarning.js"}}
+
 ## Breaking changes
 
 ### Stabilized `experimentalFeatures`

docs/data/migration/migration-pickers-v8/migration-pickers-v8.md

@@ -59,6 +59,10 @@ Make sure to double-check them to avoid unexpected changes in your flow.
 If you have suggestions for how we could improve behaviors in the future, feel free to open a [GitHub issue](https://github.com/mui/mui-x/issues/new/choose) to discuss it.
 :::
 
+## Update your license key (Pro and Premium)
+
+{{"component": "modules/components/V9LicenseUpgradeWarning.js"}}
+
 ## Run codemods
 
 The `preset-safe` codemod will automatically adjust the bulk of your code to account for breaking changes in v9. You can run `v9.0.0/pickers/preset-safe` targeting only Date and Time Pickers or `v9.0.0/preset-safe` to target the other packages as well.

docs/data/migration/migration-tree-view-v8/migration-tree-view-v8.md

@@ -44,6 +44,10 @@ Follow the [Material UI migration guide](/material-ui/migration/upgrade-to-v9/)
 +"@mui/system": "^7.3.0",
 ```
 
+## Update your license key (Pro and Premium)
+
+{{"component": "modules/components/V9LicenseUpgradeWarning.js"}}
+
 ## Breaking changes
 
 ## Hooks

docs/public/_redirects

@@ -8,6 +8,8 @@
 # should all be prefixed with x-
 
 /r/x-get-license https://mui.com/pricing/ 302
+/r/x-license-account https://mui.com/store/account/licenses/ 302
+/r/x-license-key-upgrade https://support.mui.com/hc/en-us/articles/26762005295516-How-can-I-generate-a-v9-license-key/ 302
 /r/x-license-eula https://mui.com/legal/mui-x-eula/ 302
 /r/x-license-annual https://mui.com/legal/mui-x-eula/#annual-license 302
 /r/x-license-trial https://mui.com/x/introduction/licensing/#evaluation-trial-licenses 302

docs/src/modules/components/V9LicenseUpgradeWarning.js

@@ -0,0 +1,31 @@
+import { MarkdownElement } from '@mui/internal-core-docs/MarkdownDocs';
+
+export default function V9LicenseUpgradeWarning() {
+  return (
+    <MarkdownElement>
+      <aside className="MuiCallout-root MuiCallout-warning">
+        <div className="MuiCallout-icon-container">
+          <svg focusable="false" aria-hidden="true" viewBox="0 0 20 20">
+            <use xlinkHref="#warning-icon" />
+          </svg>
+        </div>
+        <div className="MuiCallout-content">
+          <p>
+            If you&apos;re upgrading from v8 to v9, you&apos;ll need to generate a new license key
+            from your <a href="https://mui.com/r/x-license-account/">MUI Store account</a>. The new
+            v9 key inherits the same expiration date as your existing v8 key, so there&apos;s no
+            extra cost during your current term. See{' '}
+            <a href="https://mui.com/r/x-license-key-upgrade/">
+              How can I generate a v9 license key?
+            </a>{' '}
+            for step-by-step instructions.
+          </p>
+          <p>
+            When it&apos;s time to renew, you&apos;ll need to choose which key to renew, note that
+            v9 renewals are priced differently from v8 renewals.
+          </p>
+        </div>
+      </aside>
+    </MarkdownElement>
+  );
+}

packages/x-license/src/Watermark/Watermark.tsx

@@ -57,6 +57,11 @@ function Watermark(props: WatermarkProps) {
       }}
     >
       {getLicenseErrorMessage(licenseStatus.status)}
+      {process.env.NODE_ENV !== 'production' && (
+        <div style={{ fontSize: 12, letterSpacing: 1, marginTop: 8 }}>
+          Open the browser console for details on how to resolve this.
+        </div>
+      )}
     </div>
   );
 }

packages/x-license/src/utils/licenseErrorMessageUtils.ts

@@ -63,10 +63,13 @@ export function showLicenseKeyVersionMismatchError() {
   showError([
     'MUI X: License key version mismatch.',
     '',
-    'The license key you are using is not compatible with the version of the MUI X packages installed.',
-    'This happens when using a license key from a previous major version (e.g. a v8 license with v9 packages).',
+    // #npm-tag-reference
+    'The license key you are using was issued for an older major version of MUI X (e.g. a v8 license with v9 packages installed).',
+    'Each major version uses a different license key format, so the key needs to be regenerated — your existing license is not lost.',
     '',
-    'To resolve this, you can either get an new license key at https://mui.com/r/x-get-license or from your account profile at https://mui.com/store/account/licenses/, or downgrade to an older MUI X version that matches your current license key.',
+    'To resolve this, you can either:',
+    '- Generate a new key compatible with the installed version from your account at https://mui.com/r/x-license-account/ (free for existing customers, the new key inherits your current expiration date). More details at https://mui.com/r/x-license-key-upgrade/.',
+    '- Or downgrade the MUI X packages to the major version that matches your current license key.',
   ]);
 }