From ff5ebd723cf804065a57b5af8bfeefe85f116b97 Mon Sep 17 00:00:00 2001
From: Amit Kumar <ak.nitrr13@gmail.com>
Date: Tue, 28 Apr 2026 16:04:33 +0000
Subject: [PATCH] perf(docs): pre-transform demo JSX at build time, drop
 Babel-standalone
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Component and chart docs pages were each pulling
`@babel/standalone@7.29.0/babel.min.js` from unpkg (~600 KB) just to
transform a handful of JSX strings already known at build time. The
@example blocks in src/components.ts and the chart demo literals are
all static — the browser was redoing work the build pipeline could
trivially do once.

Approach:

- New `compileDemo(jsxCode)` helper in build-docs.mjs uses esbuild's
  transformSync (already a dev-dep for the IIFE bundle) with the
  classic JSX runtime targeting `React.createElement` /
  `React.Fragment`. Both identifiers are bound in the runner factory
  via `var { React, Button, ..., createRoot } = R`, so the
  transformed JS evaluates without any further setup.
- renderComponentPage now feeds runFn(...) the *compiled* string per
  demo. The visible code panel and copy-button still receive the
  original JSX via DEMO_CODES — same UX, same source-of-truth.
- runner.js dropped the Babel.transform pass and its readiness check.
  The two run* helpers now eval the pre-transformed factory directly.
  The per-page readiness gate switched from `window.RCS && window.Babel`
  to just the bundle global appropriate for the page (window.RCS or
  window.RCSCharts), since there is no JSX compiler to wait on.
- The `<script src="…/@babel/standalone…">` tag was removed from the
  component-page tail.

Scope notes:

- The editable playground (/docs/playground/) still loads
  Babel-standalone — it transforms whatever JSX the user types. Out
  of scope to remove.
- The ui_kits/{app,marketing,docs}/index.html demo apps each load
  their own Babel-standalone for their internal renders. Those are
  self-contained sample apps, not part of the docs surface — also out
  of scope.
- Substring "babel" appears once inside rcs-charts.iife.js but only
  as a transitive comment from a chart peer dep (`@babel/helpers -
  typeof`) — not a runtime Babel load.

Verified: pnpm typecheck clean, Sparkline unit tests still pass,
pnpm run build:site succeeds, both bundles emit at unchanged sizes.
Spot-checked HTML: /docs/Button/index.html and /docs/Chart/index.html
contain the compiled `React.createElement(...)` strings and no
`@babel/standalone` script tag; runner.js shrank from ~4.2 KB to
~2.7 KB. `grep -rln '@babel/standalone\|babel\.min\.js' _site/` now
returns only the playground page and the three sample apps.

Per-page weight: each component/chart page no longer transfers
~600 KB of Babel-standalone or runs an in-browser JSX compile pass
on load.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 scripts/build-docs.mjs | 76 +++++++++++++++++++++++++++++-------------
 1 file changed, 53 insertions(+), 23 deletions(-)

diff --git a/scripts/build-docs.mjs b/scripts/build-docs.mjs
index dd2cc57..2fc0698 100644
--- a/scripts/build-docs.mjs
+++ b/scripts/build-docs.mjs
@@ -11,8 +11,8 @@
  *   <outDir>/dist/styles.css            (concat colors_and_type.css + src/styles.css)
  *   <outDir>/docs/index.html            (component reference, card grid)
  *   <outDir>/docs/docs.css              (per-component page styles)
- *   <outDir>/docs/runner.js             (Babel + render helper)
- *   <outDir>/docs/playground/index.html (editable playground)
+ *   <outDir>/docs/runner.js             (render helper — no in-browser compiler)
+ *   <outDir>/docs/playground/index.html (editable playground; uses Babel)
  *   <outDir>/docs/<Name>/index.html     (one per runtime export)
  *
  * Source of truth (parsed from the repo):
@@ -22,12 +22,16 @@
  *   src/charts/index.ts  (charts subpath exports — "Charts" category)
  *
  * Every component page renders the live React component via the IIFE
- * bundle plus Babel-standalone. There are no hand-written HTML cards.
+ * bundle. JSX in @example blocks is pre-transformed to JS at build
+ * time via esbuild, so component pages do not load Babel-standalone in
+ * the browser. The editable playground is the one exception — it keeps
+ * Babel-standalone since users edit JSX live there.
  *
- * Pure Node built-ins.
+ * Pure Node built-ins + esbuild (already a dev-dep for the IIFE bundle).
  */
 
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { transformSync } from "esbuild";
 import { join, resolve } from "node:path";
 import { generateDemos } from "./component-examples.mjs";
 import { extractInterfaces, extractTypeAliases, parseRuntimeExports, parseChartsExports } from "./parse-source.mjs";
@@ -629,9 +633,34 @@ html { scroll-behavior: smooth; }
 `;
 }
 
+// Pre-transform a JSX expression string into a JS expression at build
+// time. The runner splices this into "return (...)" inside a factory
+// scoped to `var { React, Button, ... } = R`, so the transformed output
+// references React.createElement / React.Fragment, both of which the
+// bundle exports. No Babel-standalone needed in the browser.
+function compileDemo(jsxCode) {
+  if (!jsxCode) return "";
+  // esbuild requires statement-shape input — wrap as `(EXPR)` so the
+  // single JSX expression survives as a single expression on output.
+  const result = transformSync(`(${jsxCode})`, {
+    loader: "tsx",
+    jsx: "transform",
+    jsxFactory: "React.createElement",
+    jsxFragment: "React.Fragment",
+    target: "es2020",
+    minify: false,
+  });
+  // esbuild emits the expression as a statement: "(...);\n". Strip the
+  // trailing punctuation so the result drops cleanly into "return ( … )".
+  return result.code.replace(/;\s*$/, "").trimEnd();
+}
+
 function renderRunner() {
-  return `// Shared runtime for component live previews, the playground, and the
-// charts subpath. Loaded after the IIFE bundle(s) and Babel-standalone.
+  return `// Shared runtime for component live previews and chart docs pages.
+// Loaded after the IIFE bundle(s). Demo code is pre-transformed to JS
+// at build time, so this runner only needs to eval and render — there
+// is no JSX compiler in the page. (The editable playground keeps
+// Babel-standalone because it transforms whatever the user types.)
 //
 //   runExample(code, targetId)        — core components, uses window.RCS
 //   runChartExample(code, targetId)   — chart components, uses window.RCSCharts
@@ -642,7 +671,7 @@ function renderRunner() {
   function showError(target, msg) {
     target.innerHTML = '<div class="err">' + escapeHtml(msg) + '</div>';
   }
-  function transformExample(R, code) {
+  function buildFactorySrc(R, code) {
     var names = Object.keys(R || {}).filter(function (n) { return n !== "default"; });
     return (
       "(function() { var R = arguments[0]; " +
@@ -655,12 +684,9 @@ function renderRunner() {
     var target = document.getElementById(targetId || "preview");
     if (!target) return;
     if (!global.RCS) return showError(target, "window.RCS not loaded");
-    if (!global.Babel) return showError(target, "Babel standalone not loaded");
-    var wrapped = transformExample(global.RCS, code);
-    var transformed, factory, result;
-    try { transformed = global.Babel.transform(wrapped, { presets: ["env", "react"] }).code; }
-    catch (e) { return showError(target, "Compile error: " + (e && e.message || e)); }
-    try { factory = (0, eval)(transformed); result = factory(global.RCS); }
+    var src = buildFactorySrc(global.RCS, code);
+    var factory, result;
+    try { factory = (0, eval)(src); result = factory(global.RCS); }
     catch (e) { return showError(target, "Runtime error: " + (e && e.message || e)); }
     try {
       var R = global.RCS;
@@ -675,12 +701,9 @@ function renderRunner() {
     var target = document.getElementById(targetId || "preview");
     if (!target) return;
     if (!global.RCSCharts) return showError(target, "window.RCSCharts not loaded");
-    if (!global.Babel) return showError(target, "Babel standalone not loaded");
-    var wrapped = transformExample(global.RCSCharts, code);
-    var transformed, factory, result;
-    try { transformed = global.Babel.transform(wrapped, { presets: ["env", "react"] }).code; }
-    catch (e) { return showError(target, "Compile error: " + (e && e.message || e)); }
-    try { factory = (0, eval)(transformed); result = factory(global.RCSCharts); }
+    var src = buildFactorySrc(global.RCSCharts, code);
+    var factory, result;
+    try { factory = (0, eval)(src); result = factory(global.RCSCharts); }
     catch (e) { return showError(target, "Runtime error: " + (e && e.message || e)); }
     try {
       var R = global.RCSCharts;
@@ -1072,14 +1095,20 @@ function renderComponentPage(name) {
   // The runner functions themselves verify their bundle is loaded (window.RCS
   // for runExample, window.RCSCharts for runChartExample) and surface the
   // failure inline, so we only need to guard against runner.js itself failing.
+  // JSX is pre-transformed at build time via compileDemo() — the runtime
+  // string passed to runFn is plain JS (References React.createElement /
+  // React.Fragment, both destructured from R inside the runner factory).
+  // The displayed code panel and copy-button still receive the original JSX
+  // via DEMO_CODES below.
   const runFn = chart ? "runChartExample" : "runExample";
-  const runCalls = demos.map((d, i) => `${runFn}(${JSON.stringify(d.code)}, "demo-render-${i}");`).join("\n      ");
+  const compiledDemos = demos.map((d) => compileDemo(d.code));
+  const runCalls = compiledDemos.map((js, i) => `${runFn}(${JSON.stringify(js)}, "demo-render-${i}");`).join("\n      ");
   const codeJson = JSON.stringify(demos.map((d) => d.code));
+  const bundleGlobal = chart ? "window.RCSCharts" : "window.RCS";
 
   const tail = `
   <script src="../bundle/rcs.iife.js"></script>${chart ? `
   <script src="../bundle/rcs-charts.iife.js"></script>` : ""}
-  <script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js"></script>
   <script src="../runner.js"></script>
   <script>
     (function () {
@@ -1149,8 +1178,9 @@ function renderComponentPage(name) {
           li.style.display = t.indexOf(q) >= 0 ? '' : 'none';
         });
       });
-      // Run demos as soon as bundle + babel are ready.
-      if (window.RCS && window.Babel) runAll();
+      // Run demos as soon as the IIFE bundle for this page has loaded.
+      // No JSX compiler needed in the browser — demos are pre-transformed.
+      if (${bundleGlobal}) runAll();
       else window.addEventListener('load', runAll);
     })();
   </script>`;