From 055359ece5912d48352249bc96f119813dac9184 Mon Sep 17 00:00:00 2001
From: Maria Hutt <thetaPC@users.noreply.github.com>
Date: Wed, 4 Nov 2026 15:48:11 -0800
Subject: [PATCH] chore(playground): load the latest published Ionic in demos
 for unreleased majors

---
 _templates/README.md                      |  2 ++
 _templates/playground/new/demo.html.ejs.t |  7 ++--
 _templates/playground/new/index.js        | 40 ++++++++++++++++++++++-
 3 files changed, 45 insertions(+), 4 deletions(-)

diff --git a/_templates/README.md b/_templates/README.md
index dda6358c96d..70954f0d265 100644
--- a/_templates/README.md
+++ b/_templates/README.md
@@ -19,6 +19,8 @@ The CSS option will add extra files if you need to include custom CSS in your pl
 
 If you need a component for multiple versions of Ionic Framework, you (currently) need to run the generator once for each version.
 
+If the version you pick is not published to npm yet, such as the next major on a major branch, the generated `demo.html` loads the latest published version from the CDN instead, since the CDN has nothing to serve for an unpublished version. The demo renders, but APIs new in that version do not work in it until the version is published. The generator also adds a `TODO(FW-XXXX)` comment above the CDN links. Replace `FW-XXXX` with the ticket that tracks the update, and create one if it does not exist yet.
+
 ## Usage
 
 Once you've generated your playground, you need to add it to the main markdown file in the docs (e.g. [docs/api/button.mdx](../docs/api/button.mdx)) by doing something similar to the following example:
diff --git a/_templates/playground/new/demo.html.ejs.t b/_templates/playground/new/demo.html.ejs.t
index 3a6a9cadff9..62475d8262a 100644
--- a/_templates/playground/new/demo.html.ejs.t
+++ b/_templates/playground/new/demo.html.ejs.t
@@ -9,9 +9,10 @@ to: "<%= `static/usage/v${version}/${name}/${path}/demo.html` %>"
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title><%= h.changeCase.titleCase(name) %></title>
     <link rel="stylesheet" href="<%= directoryChanges %>../../common.css" />
-    <script src="<%= directoryChanges %>../../common.js"></script>
-    <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@<%= version %>/dist/ionic/ionic.esm.js"></script>
-    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@<%= version %>/css/ionic.bundle.css" /><% if (css){ %>
+    <script src="<%= directoryChanges %>../../common.js"></script><% if (cdnVersion !== version) { %>
+    <!-- TODO(FW-XXXX): load Ionic <%= version %> once it is published --><% } %>
+    <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@<%= cdnVersion %>/dist/ionic/ionic.esm.js"></script>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@<%= cdnVersion %>/css/ionic.bundle.css" /><% if (css){ %>
 
     <style>
       <%= component %> {
diff --git a/_templates/playground/new/index.js b/_templates/playground/new/index.js
index 11ea9e42a82..540b52364aa 100644
--- a/_templates/playground/new/index.js
+++ b/_templates/playground/new/index.js
@@ -1,5 +1,41 @@
 const changeCase = require('change-case');
 
+/**
+ * Returns the major version of Ionic for the demo to load from the CDN.
+ *
+ * The CDN only serves published versions, so a playground for a major that
+ * is not published yet loads the latest published one instead. Otherwise
+ * the demo requests a version that does not exist and renders nothing. With
+ * the fallback the demo renders, but APIs new in that major do not work in
+ * it until the major is published.
+ */
+const getCdnVersion = async (version) => {
+  try {
+    const response = await fetch('https://registry.npmjs.org/-/package/@ionic/core/dist-tags', {
+      signal: AbortSignal.timeout(5000),
+    });
+    const { latest } = await response.json();
+    const latestMajor = parseInt(latest, 10);
+
+    if (Number.isNaN(latestMajor)) {
+      throw new Error(`Unexpected latest version: ${latest}`);
+    }
+
+    if (Number(version) > latestMajor) {
+      console.log(
+        `\nIonic ${version} is not published yet, so the demo loads Ionic ${latestMajor} from the CDN and APIs new in Ionic ${version} will not work in it. Update the version in demo.html once Ionic ${version} is published, and replace FW-XXXX in its TODO with the ticket that tracks the update, creating one if it does not exist yet.`
+      );
+      return String(latestMajor);
+    }
+  } catch (error) {
+    console.warn(
+      `\nCould not check the published Ionic versions, so the demo loads Ionic ${version} from the CDN. If that version is not published yet, change it in demo.html.`
+    );
+  }
+
+  return version;
+};
+
 // see types of prompts:
 // https://github.com/enquirer/enquirer/tree/master/examples
 //
@@ -63,13 +99,15 @@ module.exports = {
               message: 'Generate custom CSS files?',
             },
           ])
-          .then((answers) => {
+          .then(async (answers) => {
             answers.name = answers.name || answers.component.replace('ion-', '');
 
             // if the playground is not for a component,
             // include an ion-card in the playground
             answers.component = answers.component || 'ion-card';
 
+            answers.cdnVersion = await getCdnVersion(answers.version);
+
             const playgroundName = changeCase.pascal(answers.path.split('/').pop());
             console.log(
               `\nTo use this playground in a docs markdown file, include\nthe following:\n\n## ${playgroundName}\n\nimport ${playgroundName} from '@site/static/usage/v${answers.version}/${answers.name}/${answers.path}/index.mdx';\n\n<${playgroundName} />\n`