@dev-to/react-plugin 0.3.0 → 0.4.0

package/dist/debugHtml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debugHtml.d.ts","sourceRoot":"","sources":["../src/debugHtml.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEhE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,iBAAiB,CAAA;IACxB,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,KAAK,EAAE,WAAW,CAAA;IAClB,gBAAgB,EAAE,oBAAoB,CAAA;IACtC,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,UAyf5D"}
+{"version":3,"file":"debugHtml.d.ts","sourceRoot":"","sources":["../src/debugHtml.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEhE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,iBAAiB,CAAA;IACxB,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,KAAK,EAAE,WAAW,CAAA;IAClB,gBAAgB,EAAE,oBAAoB,CAAA;IACtC,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,UAskB5D"}

package/dist/index.js

@@ -238,17 +238,14 @@ function renderDebugHtml(params) {
 
             ${hasConfig ? `
                 <table>
-                    <thead><tr><th>组件名称 <small class="muted">(Component Name)</small></th><th>映射入口 <small class="muted">(Short Path)</small></th></tr></thead>
+                    <thead><tr><th>组件名称 <small class="muted">(Component Name)</small></th><th>映射入口 <small class="muted">(Short Path)</small></th><th>包装地址 <small class="muted">(UMD Wrapper)</small></th></tr></thead>
                     <tbody>
                         ${Object.entries(resolvedDevComponentMap).map(([name, entry])=>{
         const abs = entryPathMap[name];
         const displayPath = abs ? getShortPath(abs) : entry;
-        return `<tr>
-                                <td><code class="code-name">${name}</code></td>
-                                <td>
-                                    ${abs ? `<a href="${toVsCodeUrl(abs)}" class="link-code" title="点击在 IDE 中打开"><code>${escapeHtml(displayPath)}</code></a>` : `<code>${escapeHtml(entry)}</code>`}
-                                </td>
-                            </tr>`;
+        const wrapperUrl = (originCandidates[0] || 'http://localhost:5173') + '/__dev_to_react__/loader/' + name + '.js';
+        const entryHtml = abs ? '<a href="' + toVsCodeUrl(abs) + '" class="link-code" title="点击在 IDE 中打开"><code>' + escapeHtml(displayPath) + '</code></a>' : '<code>' + escapeHtml(entry) + '</code>';
+        return '<tr><td><code class="code-name">' + name + "</code></td><td>" + entryHtml + '</td><td><div style="display: flex; align-items: center; gap: 6px;"><code style="flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 12px;">' + escapeHtml(wrapperUrl) + '</code><button class="copy-wrapper-btn" data-url="' + wrapperUrl + '" style="padding: 2px 8px; font-size: 11px; border: 1px solid var(--b); background: #fff; border-radius: 4px; cursor: pointer; color: var(--t); transition: .2s;" title="复制包装地址">\uD83D\uDCCB</button></div></td></tr>';
     }).join('')}
                     </tbody>
                 </table>
@@ -330,6 +327,56 @@ reactHmrHostPlugin(<span class="str">'Demo'</span>, { open: <span class="kw">tru
             </details>
         </div>
 
+        <div class="card">
+            <h3>🎁 UMD 动态包装器 (Auto-Generated Wrapper)</h3>
+            <p class="muted">无需额外配置，每个组件都自动生成一个轻量级 UMD 包装器，可直接在无 React 框架支持的宿主环境中使用。</p>
+
+            <div class="info-grid">
+                <div class="info-label">端点:</div>
+                <div class="info-value"><code>/__dev_to_react__/loader/{ComponentName}.js</code></div>
+                <div class="info-label">作用:</div>
+                <div class="info-value">自动将组件导出为 React 组件实例，无需宿主集成 @dev-to/react-loader</div>
+                <div class="info-label">依赖:</div>
+                <div class="info-value"><code>react</code> &amp; <code>react-dom@18</code> (CDN 或本地)</div>
+            </div>
+
+            <details>
+                <summary>包装器工作原理与集成示例</summary>
+                <div style="margin-top: 12px;">
+                    <h4 style="color: var(--t); font-size: 14px; margin-top: 0; margin-bottom: 8px;">🔧 什么是包装器？</h4>
+                    <p class="muted" style="margin-bottom: 12px;">
+                        包装器是一个自动生成的 UMD 模块，它包装了原始的 render 函数并导出为 React 组件。
+                        这样，无论宿主是否集成了 ReactLoader，都能直接作为 React 组件使用。
+                    </p>
+
+                    <h4 style="color: var(--t); font-size: 14px; margin-top: 16px; margin-bottom: 8px;">📖 集成方式</h4>
+                    <pre style="font-size: 12px; line-height: 1.7;">
+<span class="cmt">// 1. 加载 React 和 ReactDOM</span>
+<span class="kw">&lt;script&gt;</span> <span class="kw">src</span>=<span class="str">"https://unpkg.com/react@18/umd/react.production.min.js"</span> <span class="kw">&lt;/script&gt;</span>
+<span class="kw">&lt;script&gt;</span> <span class="kw">src</span>=<span class="str">"https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"</span> <span class="kw">&lt;/script&gt;</span>
+
+<span class="cmt">// 2. 加载包装器脚本</span>
+<span class="kw">&lt;script&gt;</span> <span class="kw">src</span>=<span class="str">"\${originCandidates[0] || 'http://localhost:5173'}/__dev_to_react__/loader/{ComponentName}.js"</span> <span class="kw">&lt;/script&gt;</span>
+
+<span class="cmt">// 3. 直接作为 React 组件使用</span>
+<span class="kw">const</span> root = ReactDOM.createRoot(document.getElementById(<span class="str">'app'</span>));
+root.render(React.createElement(window.ComponentName, { prop1: <span class="str">'value1'</span> }));
+
+<span class="cmt">// 或在宿主 React 组件中使用</span>
+<span class="kw">const</span> Component = window.ComponentName;
+<span class="kw">&lt;&gt;</span>&lt;Component prop1=<span class="str">"value1"</span> /&gt;<span class="kw">&lt;/&gt;</span></pre>
+
+                    <h4 style="color: var(--t); font-size: 14px; margin-top: 16px; margin-bottom: 8px;">⚡ 关键特性</h4>
+                    <ul class="muted" style="margin: 8px 0; padding-left: 20px;">
+                        <li><b>零配置</b>：自动为每个组件生成包装器，无需手动编写</li>
+                        <li><b>兼容现有宿主</b>：支持 CommonJS、AMD、浏览器全局三种模式</li>
+                        <li><b>自动依赖管理</b>：若未加载 React，包装器会自动从 CDN 加载（可配置）</li>
+                        <li><b>轻量级</b>：仅包含加载逻辑，核心渲染由 ReactLoader 负责</li>
+                    </ul>
+                </div>
+            </details>
+        </div>
+
         <div class="card">
             <h3>📦 构建与部署</h3>
             <p class="muted">执行 <code>vite build --mode lib</code> 将组件打包为 UMD 格式以供发布。</p>
@@ -468,6 +515,27 @@ CSS: <span class="str">dist/&lt;name&gt;/&lt;name&gt;.css</span></pre>
                 setTimeout(() => { copyFullBtn.textContent = '复制原始命令'; }, 2000);
             });
 
+            // 绑定包装地址复制按钮事件
+            document.querySelectorAll('.copy-wrapper-btn').forEach(btn => {
+                btn.onclick = (e) => {
+                    e.preventDefault();
+                    const url = btn.getAttribute('data-url');
+                    copy(url, () => {
+                        const originalText = btn.textContent;
+                        btn.textContent = '✓';
+                        btn.style.borderColor = '#10b981';
+                        btn.style.color = '#10b981';
+                        setTimeout(() => {
+                            btn.textContent = originalText;
+                            btn.style.borderColor = '';
+                            btn.style.color = '';
+                        }, 1500);
+                    });
+                };
+                btn.onmouseover = () => { btn.style.borderColor = 'var(--p)'; btn.style.color = 'var(--p)'; };
+                btn.onmouseout = () => { btn.style.borderColor = ''; btn.style.color = ''; };
+            });
+
             const serverActualPort = ${'number' == typeof actualPort ? actualPort : 'null'};
             document.getElementById('actualPortDisplay').textContent = serverActualPort || location.port || '-';
         })();
@@ -822,33 +890,42 @@ function createLoaderUmdWrapper(options) {
  * Global name: ${globalName}
  * Generated by ${constants_PLUGIN_LOG_PREFIX}
  *
- * This wrapper uses @dev-to/react-loader to dynamically load and render the component.
+ * This wrapper automatically exports a React component that can be used in any React environment.
+ * No need to manually integrate @dev-to/react-loader.
+ *
+ * ============= Quick Start =============
  *
- * Usage:
  * 1. Load React and ReactDOM:
  *    <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
  *    <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
  *
- * 2. Load ReactLoader:
- *    <script src="https://cdn.jsdelivr.net/npm/@dev-to/react-loader@latest/dist/index.umd.js"></script>
- *
- * 3. Load this wrapper:
+ * 2. Load this wrapper:
  *    <script src="${origin}/__dev_to_react__/loader/${componentName}.js"></script>
  *
- * 4. Render the component (returns a Promise):
- *    <div id="app"></div>
- *    <script>
- *      window.${globalName}.render(
- *        document.getElementById('app'),
- *        { prop1: 'value1', prop2: 'value2' }
- *      ).then(function(root) {
- *        console.log('Component rendered successfully');
- *      }).catch(function(error) {
- *        console.error('Failed to render component:', error);
- *      });
- *    </script>
+ * 3. Use as a React component:
+ *
+ *    // Option A: Direct React rendering
+ *    const Component = window.${globalName};
+ *    const root = ReactDOM.createRoot(document.getElementById('app'));
+ *    root.render(React.createElement(Component, { prop1: 'value1' }));
  *
- * Note: ReactLoader will be automatically loaded from CDN if not already available.
+ *    // Option B: Use in JSX (if using Babel)
+ *    const Component = window.${globalName};
+ *    root.render(<Component prop1="value1" />);
+ *
+ *    // Option C: Direct function call (legacy compatibility)
+ *    window.${globalName}(document.getElementById('app'), { prop1: 'value1' })
+ *      .then(root => console.log('Rendered'))
+ *      .catch(err => console.error('Error:', err));
+ *
+ * ============= Features =============
+ * ✓ Zero configuration required
+ * ✓ Automatic React/ReactDOM detection
+ * ✓ Supports CommonJS, AMD, and global scope
+ * ✓ Auto-loads ReactLoader from CDN if needed
+ * ✓ Works in any React environment
+ *
+ * Note: Make sure React v18+ and react-dom/client are available globally.
  */
 (function (root, factory) {
   if (typeof exports === 'object' && typeof module !== 'undefined') {
@@ -860,7 +937,9 @@ function createLoaderUmdWrapper(options) {
   } else {
     // Browser globals
     var globalObj = typeof globalThis !== 'undefined' ? globalThis : (typeof self !== 'undefined' ? self : root);
-    factory((globalObj.${globalName} = {}), globalObj.React, globalObj.ReactDOM, globalObj.DevToReactLoader);
+    var tempExports = {};
+    factory(tempExports, globalObj.React, globalObj.ReactDOM, globalObj.DevToReactLoader);
+    globalObj.${globalName} = tempExports.default;
   }
 })(this, function (exports, React, ReactDOM, ReactLoaderModule) {
   'use strict';
@@ -964,13 +1043,37 @@ function createLoaderUmdWrapper(options) {
     });
   }
 
-  // Export the API
-  exports.render = render;
-  exports.config = config;
-  exports.default = { render: render, config: config };
+  // Create a React component wrapper for the render function
+  function ComponentWrapper(props) {
+    var containerRef = React.useRef(null);
+    var isFirstRender = React.useRef(true);
 
-  // Mark as ES module
-  Object.defineProperty(exports, '__esModule', { value: true });
+    React.useEffect(function() {
+      if (!containerRef.current) return;
+
+      render(containerRef.current, props).catch(function(err) {
+        console.error('${constants_PLUGIN_LOG_PREFIX} Failed to render ${componentName}:', err);
+        console.error('${constants_PLUGIN_LOG_PREFIX} Props:', props);
+      });
+
+      if (isFirstRender.current) {
+        isFirstRender.current = false;
+        if (typeof console !== 'undefined' && console.info) {
+          console.info(
+            '%c${constants_PLUGIN_LOG_PREFIX}%c Successfully loaded and rendered component: %c${componentName}',
+            'color: #10b981; font-weight: bold;',
+            'color: #64748b;',
+            'color: #3b82f6; font-weight: bold;'
+          );
+        }
+      }
+    }, [props]);
+
+    return React.createElement('div', { ref: containerRef });
+  }
+
+  // Export the API
+  exports.default = ComponentWrapper;
 });
 `;
     return code;

package/dist/loaderUmdWrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loaderUmdWrapper.d.ts","sourceRoot":"","sources":["../src/loaderUmdWrapper.ts"],"names":[],"mappings":"AAGA,UAAU,6BAA6B;IACrC,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,MAAM,CAwKrF"}
+{"version":3,"file":"loaderUmdWrapper.d.ts","sourceRoot":"","sources":["../src/loaderUmdWrapper.ts"],"names":[],"mappings":"AAGA,UAAU,6BAA6B;IACrC,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,MAAM,CA2MrF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-to/react-plugin",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",