@salesforce/vite-plugin-webapp-experimental 1.47.0 → 1.48.0

package/dist/babel/reactDesignTimeLocatorBabelPlugin.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * React design-time Babel plugin.
+ *
+ * Injects DOM-locating and text metadata attributes into HTML JSX elements at compile-time.
+ *
+ * Attributes injected (when location is available):
+ * - data-source-file="<file_path>:<line>:<col>"
+ *
+ * Optional text metadata:
+ * - data-text-type: none | static | dynamic | mixed | element
+ *
+ * NOTE: This is a Babel plugin. In this repo it's run via a Vite `transform` hook.
+ */
+declare const reactDesignTimeLocatorBabelPlugin: (api: object, options: Record<string, any> | null | undefined, dirname: string) => {
+    name: string;
+    visitor: {
+        JSXElement(this: import("@babel/core").PluginPass, path: any, state: any): void;
+    };
+};
+export default reactDesignTimeLocatorBabelPlugin;
+//# sourceMappingURL=reactDesignTimeLocatorBabelPlugin.d.ts.map

package/dist/babel/reactDesignTimeLocatorBabelPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactDesignTimeLocatorBabelPlugin.d.ts","sourceRoot":"","sources":["../../src/babel/reactDesignTimeLocatorBabelPlugin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,iCAAiC;;;iEAiCnB,GAAG,SAAS,GAAG;;CAmEjC,CAAC;AAEH,eAAe,iCAAiC,CAAC"}

package/dist/babel/reactDesignTimeLocatorBabelPlugin.js

@@ -0,0 +1,112 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { declare } from "@babel/helper-plugin-utils";
+/**
+ * React design-time Babel plugin.
+ *
+ * Injects DOM-locating and text metadata attributes into HTML JSX elements at compile-time.
+ *
+ * Attributes injected (when location is available):
+ * - data-source-file="<file_path>:<line>:<col>"
+ *
+ * Optional text metadata:
+ * - data-text-type: none | static | dynamic | mixed | element
+ *
+ * NOTE: This is a Babel plugin. In this repo it's run via a Vite `transform` hook.
+ */
+const reactDesignTimeLocatorBabelPlugin = declare((api) => {
+    api.assertVersion(7);
+    const t = api.types;
+    function isReactFragmentName(nameNode) {
+        // <Fragment> or <React.Fragment>
+        if (t.isJSXIdentifier(nameNode) && nameNode.name === "Fragment")
+            return true;
+        if (t.isJSXMemberExpression(nameNode) &&
+            t.isJSXIdentifier(nameNode.object, { name: "React" }) &&
+            t.isJSXIdentifier(nameNode.property, { name: "Fragment" })) {
+            return true;
+        }
+        return false;
+    }
+    function hasAttr(openingElement, name) {
+        return openingElement.attributes.some((attr) => {
+            return t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name) && attr.name.name === name;
+        });
+    }
+    function addAttr(openingElement, name, value) {
+        if (hasAttr(openingElement, name))
+            return;
+        openingElement.attributes.push(t.jsxAttribute(t.jsxIdentifier(name), t.stringLiteral(String(value))));
+    }
+    return {
+        name: "babel-plugin-react-design-time-locator",
+        visitor: {
+            JSXElement(path, state) {
+                const openingElement = path.node.openingElement;
+                // Ignore fragments (they don't render a DOM node).
+                if (isReactFragmentName(openingElement.name))
+                    return;
+                // Only support common JSX name node types:
+                // - <div> (JSXIdentifier)
+                // - <Button> (JSXIdentifier)
+                // - <React.Suspense> / <Mui.Button> (JSXMemberExpression)
+                if (!t.isJSXIdentifier(openingElement.name) &&
+                    !t.isJSXMemberExpression(openingElement.name)) {
+                    return;
+                }
+                // Decide whether this is a native DOM element or a component usage.
+                // We tag BOTH:
+                // - DOM elements are tagged directly (always works)
+                // - Components are tagged via props (works when the component forwards props, e.g. many MUI components)
+                let tagHead = "";
+                if (t.isJSXIdentifier(openingElement.name)) {
+                    tagHead = openingElement.name.name;
+                }
+                else if (t.isJSXMemberExpression(openingElement.name)) {
+                    // Member expressions are always components in React (e.g. <Foo.Bar>)
+                    tagHead = openingElement.name.property?.name ?? "";
+                }
+                if (!tagHead)
+                    return;
+                // Ignore node_modules
+                const filename = state?.file?.opts?.filename;
+                if (!filename || filename.includes("node_modules"))
+                    return;
+                // Analyze children for text metadata
+                const children = path.node.children ?? [];
+                const relevantChildren = children.filter((child) => {
+                    return !(t.isJSXText(child) && child.value.trim() === "");
+                });
+                let textType = "none"; // none | static | dynamic | mixed | element
+                if (relevantChildren.length === 1) {
+                    const child = relevantChildren[0];
+                    if (t.isJSXText(child)) {
+                        textType = "static";
+                    }
+                    else if (t.isJSXExpressionContainer(child)) {
+                        textType = "dynamic";
+                    }
+                    else {
+                        textType = "element";
+                    }
+                }
+                else if (relevantChildren.length > 1) {
+                    textType = "mixed";
+                }
+                // Inject location info (best-effort)
+                const loc = path.node.loc;
+                if (loc?.start) {
+                    const source = `${filename}:${loc.start.line}:${loc.start.column}`;
+                    addAttr(openingElement, "data-source-file", source);
+                }
+                // Inject text metadata
+                addAttr(openingElement, "data-text-type", textType);
+            },
+        },
+    };
+});
+export default reactDesignTimeLocatorBabelPlugin;

package/dist/index.d.ts

@@ -9,6 +9,13 @@ export interface PluginOptions {
     orgAlias?: string;
     /** Enable verbose logging */
     debug?: boolean;
+    /**
+     * Enable design-time features (inject `data-source-file`, serve & inject design interactions script).
+     *
+     * Defaults to:
+     * - enabled when Vite `mode` is `"design"` (e.g. `vite --mode design`)
+     */
+    designMode?: boolean;
 }
 export default function webappsPlugin(options?: PluginOptions): Plugin;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAUlD,MAAM,WAAW,aAAa;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAID,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAiIzE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAWlD,MAAM,WAAW,aAAa;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAID,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAiNzE"}

package/dist/index.js

@@ -4,7 +4,9 @@
  * For full license text, see the LICENSE.txt file
  */
 import { loadManifest, getOrgInfo } from "@salesforce/webapp-experimental/app";
+import { getDesignModeScriptContent } from "@salesforce/webapp-experimental/design";
 import { createProxyHandler } from "@salesforce/webapp-experimental/proxy";
+import reactDesignTimeLocatorBabelPlugin from "./babel/reactDesignTimeLocatorBabelPlugin.js";
 import { getBasePath, getCodeBuilderBasePath, getPort, getDevServerTarget, DEFAULT_API_VERSION, DEFAULT_PORT, } from "./utils.js";
 const codeBuilderProxyUrl = process.env.CODE_BUILDER_FRAMEWORK_PROXY_URI;
 export default function webappsPlugin(options = {}) {
@@ -14,14 +16,20 @@ export default function webappsPlugin(options = {}) {
     let orgInfo;
     let manifest;
     let proxyHandler;
+    // Allow tests or callers to force design mode without needing to run the `config` hook.
+    let designModeEnabled = options.designMode ?? false;
     return {
         name: "@salesforce/vite-plugin-webapp-experimental",
+        enforce: "pre",
         async config(config, env) {
             const rootPath = config.root ?? process.cwd();
+            // If caller explicitly set it, keep that value. Otherwise derive from Vite mode.
+            designModeEnabled = options.designMode ?? env.mode === "design";
             // Note: At this stage we may not have the correct manifest path yet,
             // so we only load the org info to get the API version
             // Development server configuration
             let version;
+            version = DEFAULT_API_VERSION;
             try {
                 orgInfo = await getOrgInfo(options.orgAlias);
                 version = orgInfo?.apiVersion || DEFAULT_API_VERSION;
@@ -71,6 +79,33 @@ export default function webappsPlugin(options = {}) {
             // Add middleware to handle all requests (API, rewrites, redirects, and dev server forwarding)
             // Must run BEFORE Vite's internal middlewares (hence not returning a post-hook function)
             server.middlewares.use(async (req, res, next) => {
+                // Serve design mode interactions script
+                // NOTE: Live Preview and other proxies may host the dev server behind a path prefix,
+                // so we intentionally match by suffix rather than strict equality.
+                const urlPath = stripUrlQuery(req.url);
+                if (designModeEnabled &&
+                    (urlPath === "/design-mode-interactions.js" ||
+                        urlPath.endsWith("/design-mode-interactions.js"))) {
+                    try {
+                        const script = getDesignModeScriptContent();
+                        if (script !== null) {
+                            res.setHeader("Content-Type", "application/javascript");
+                            res.setHeader("Cache-Control", "no-cache");
+                            res.end(script);
+                            return;
+                        }
+                        console.error(`[webapps-plugin] Design mode script not found. Run 'npm run build:design' in @salesforce/webapp-experimental.`);
+                        res.writeHead(404);
+                        res.end("Design mode script not found");
+                        return;
+                    }
+                    catch (error) {
+                        console.error("[webapps-plugin] Error serving design mode script:", error);
+                        res.writeHead(500);
+                        res.end("Error loading design mode script");
+                        return;
+                    }
+                }
                 // Let proxy handler handle all requests
                 if (proxyHandler) {
                     try {
@@ -95,6 +130,35 @@ export default function webappsPlugin(options = {}) {
                 }
             });
         },
+        async transform(code, id) {
+            // Only inject design-time locator attributes when design mode is enabled
+            if (!designModeEnabled)
+                return null;
+            // Strip Vite query string (e.g. ?import, ?v=hash)
+            const filepath = id.split("?", 1)[0] ?? id;
+            // Best-effort: only handle React source files where JSX loc info matters.
+            const isTsx = filepath.endsWith(".tsx");
+            const isJsx = filepath.endsWith(".jsx");
+            if (!isTsx && !isJsx)
+                return null;
+            if (filepath.includes("node_modules"))
+                return null;
+            const { transformAsync } = await import("@babel/core");
+            const result = await transformAsync(code, {
+                filename: filepath,
+                babelrc: false,
+                configFile: false,
+                sourceMaps: true,
+                parserOpts: {
+                    sourceType: "module",
+                    plugins: isTsx ? ["jsx", "typescript"] : ["jsx"],
+                },
+                plugins: [reactDesignTimeLocatorBabelPlugin],
+            });
+            if (!result?.code)
+                return null;
+            return { code: result.code, map: result.map };
+        },
         async handleHotUpdate({ file, server }) {
             // Watch for manifest changes and reload
             if (file.endsWith("webapplication.json")) {
@@ -114,5 +178,21 @@ export default function webappsPlugin(options = {}) {
                 }
             }
         },
+        transformIndexHtml(html) {
+            // Only inject design mode interactions script when design mode is enabled in dev
+            if (designModeEnabled) {
+                // Use a relative URL so it works when the app is hosted under a path prefix
+                // (e.g. VS Code Live Preview or Code Builder reverse proxies).
+                const designScriptTag = '<script src="design-mode-interactions.js"></script>';
+                return html.replace("</body>", `${designScriptTag}\n</body>`);
+            }
+            return html;
+        },
     };
 }
+function stripUrlQuery(url) {
+    if (!url)
+        return "";
+    const queryIndex = url.indexOf("?");
+    return queryIndex === -1 ? url : url.slice(0, queryIndex);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/vite-plugin-webapp-experimental",
   "description": "[experimental] Vite plugin for Salesforce Web Applications",
-  "version": "1.47.0",
+  "version": "1.48.0",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,9 +26,13 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@salesforce/webapp-experimental": "^1.47.0"
+    "@babel/core": "^7.28.4",
+    "@babel/helper-plugin-utils": "^7.28.3",
+    "@salesforce/webapp-experimental": "^1.48.0"
   },
   "devDependencies": {
+    "@types/babel__core": "^7.20.5",
+    "@types/babel__helper-plugin-utils": "^7.10.3",
     "vite": "^7.0.0",
     "vitest": "^4.0.6"
   },
@@ -41,5 +45,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "664bfe805c8d96ec2c7b8d3ce403295f420bf42c"
+  "gitHead": "5ccfffec66505f70bdf4e6679e886c7bdabfe0ff"
 }