@mandujs/core 0.5.2 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/bundler/build.ts

@@ -28,6 +28,9 @@ function createEmptyManifest(env: "development" | "production"): BundleManifest
       runtime: "",
       vendor: "",
     },
+    importMap: {
+      imports: {},
+    },
   };
 }
 
@@ -119,7 +122,8 @@ function scheduleHydration(element, id, priority, data) {
 }
 
 /**
- * 단일 Island hydrate
+ * 단일 Island hydrate (또는 mount)
+ * SSR 플레이스홀더를 Island 컴포넌트로 교체
  */
 async function hydrateIsland(element, id, data) {
   const loader = islandRegistry.get(id);
@@ -138,7 +142,7 @@ async function hydrateIsland(element, id, data) {
     }
 
     const { definition } = islandDef;
-    const { hydrateRoot } = await import('react-dom/client');
+    const { createRoot } = await import('react-dom/client');
     const React = await import('react');
 
     // Island 컴포넌트
@@ -147,8 +151,10 @@ async function hydrateIsland(element, id, data) {
       return definition.render(setupResult);
     }
 
-    // Hydrate
-    const root = hydrateRoot(element, React.createElement(IslandComponent));
+    // Mount (createRoot 사용 - SSR 플레이스홀더 교체)
+    // hydrateRoot 대신 createRoot 사용: Island는 SSR과 다른 컨텐츠를 렌더링할 수 있음
+    const root = createRoot(element);
+    root.render(React.createElement(IslandComponent));
     hydratedRoots.set(id, root);
 
     // 완료 표시
@@ -201,18 +207,45 @@ export { islandRegistry, hydratedRoots };
 }
 
 /**
- * Vendor 번들 소스 생성 (React 등 공유 의존성)
+ * React shim 소스 생성 (import map용)
  */
-function generateVendorSource(): string {
+function generateReactShimSource(): string {
   return `
 /**
- * Mandu Vendor Bundle (Generated)
- * 공유 의존성
+ * Mandu React Shim (Generated)
+ * import map을 통해 bare specifier 해결
  */
+import * as React from 'react';
+export * from 'react';
+export default React;
+`;
+}
 
-export * as React from 'react';
-export * as ReactDOM from 'react-dom';
-export * as ReactDOMClient from 'react-dom/client';
+/**
+ * React DOM shim 소스 생성
+ */
+function generateReactDOMShimSource(): string {
+  return `
+/**
+ * Mandu React DOM Shim (Generated)
+ */
+import * as ReactDOM from 'react-dom';
+export * from 'react-dom';
+export default ReactDOM;
+`;
+}
+
+/**
+ * React DOM Client shim 소스 생성
+ */
+function generateReactDOMClientShimSource(): string {
+  return `
+/**
+ * Mandu React DOM Client Shim (Generated)
+ */
+import * as ReactDOMClient from 'react-dom/client';
+export * from 'react-dom/client';
+export default ReactDOMClient;
 `;
 }
 
@@ -292,57 +325,77 @@ async function buildRuntime(
 }
 
 /**
- * Vendor 번들 빌드
+ * Vendor shim 번들 빌드 결과
+ */
+interface VendorBuildResult {
+  success: boolean;
+  react: string;
+  reactDom: string;
+  reactDomClient: string;
+  errors: string[];
+}
+
+/**
+ * Vendor shim 번들 빌드
+ * React, ReactDOM, ReactDOMClient를 각각의 shim으로 빌드
  */
-async function buildVendor(
+async function buildVendorShims(
   outDir: string,
   options: BundlerOptions
-): Promise<{ success: boolean; outputPath: string; errors: string[] }> {
-  const vendorPath = path.join(outDir, "_vendor.src.js");
-  const outputName = "_vendor.js";
+): Promise<VendorBuildResult> {
+  const errors: string[] = [];
+  const results: Record<string, string> = {
+    react: "",
+    reactDom: "",
+    reactDomClient: "",
+  };
 
-  try {
-    // 벤더 소스 작성
-    await Bun.write(vendorPath, generateVendorSource());
+  const shims = [
+    { name: "_react", source: generateReactShimSource(), key: "react" },
+    { name: "_react-dom", source: generateReactDOMShimSource(), key: "reactDom" },
+    { name: "_react-dom-client", source: generateReactDOMClientShimSource(), key: "reactDomClient" },
+  ];
 
-    // 빌드
-    const result = await Bun.build({
-      entrypoints: [vendorPath],
-      outdir: outDir,
-      naming: outputName,
-      minify: options.minify ?? process.env.NODE_ENV === "production",
-      sourcemap: options.sourcemap ? "external" : "none",
-      target: "browser",
-      define: {
-        "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
-        ...options.define,
-      },
-    });
+  for (const shim of shims) {
+    const srcPath = path.join(outDir, `${shim.name}.src.js`);
+    const outputName = `${shim.name}.js`;
 
-    // 소스 파일 정리
-    await fs.unlink(vendorPath).catch(() => {});
-
-    if (!result.success) {
-      return {
-        success: false,
-        outputPath: "",
-        errors: result.logs.map((l) => l.message),
-      };
+    try {
+      await Bun.write(srcPath, shim.source);
+
+      const result = await Bun.build({
+        entrypoints: [srcPath],
+        outdir: outDir,
+        naming: outputName,
+        minify: options.minify ?? process.env.NODE_ENV === "production",
+        sourcemap: options.sourcemap ? "external" : "none",
+        target: "browser",
+        define: {
+          "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
+          ...options.define,
+        },
+      });
+
+      await fs.unlink(srcPath).catch(() => {});
+
+      if (!result.success) {
+        errors.push(`[${shim.name}] ${result.logs.map((l) => l.message).join(", ")}`);
+      } else {
+        results[shim.key] = `/.mandu/client/${outputName}`;
+      }
+    } catch (error) {
+      await fs.unlink(srcPath).catch(() => {});
+      errors.push(`[${shim.name}] ${String(error)}`);
     }
-
-    return {
-      success: true,
-      outputPath: `/.mandu/client/${outputName}`,
-      errors: [],
-    };
-  } catch (error) {
-    await fs.unlink(vendorPath).catch(() => {});
-    return {
-      success: false,
-      outputPath: "",
-      errors: [String(error)],
-    };
   }
+
+  return {
+    success: errors.length === 0,
+    react: results.react,
+    reactDom: results.reactDom,
+    reactDomClient: results.reactDomClient,
+    errors,
+  };
 }
 
 /**
@@ -411,7 +464,7 @@ function createBundleManifest(
   outputs: BundleOutput[],
   routes: RouteSpec[],
   runtimePath: string,
-  vendorPath: string,
+  vendorResult: VendorBuildResult,
   env: "development" | "production"
 ): BundleManifest {
   const bundles: BundleManifest["bundles"] = {};
@@ -422,7 +475,7 @@ function createBundleManifest(
 
     bundles[output.routeId] = {
       js: output.outputPath,
-      dependencies: ["_runtime", "_vendor"],
+      dependencies: ["_runtime", "_react"],
       priority: hydration?.priority || "visible",
     };
   }
@@ -434,7 +487,14 @@ function createBundleManifest(
     bundles,
     shared: {
       runtime: runtimePath,
-      vendor: vendorPath,
+      vendor: vendorResult.react, // primary vendor for backwards compatibility
+    },
+    importMap: {
+      imports: {
+        "react": vendorResult.react,
+        "react-dom": vendorResult.reactDom,
+        "react-dom/client": vendorResult.reactDomClient,
+      },
     },
   };
 }
@@ -523,10 +583,10 @@ export async function buildClientBundles(
     errors.push(...runtimeResult.errors.map((e) => `[Runtime] ${e}`));
   }
 
-  // 4. Vendor 번들 빌드
-  const vendorResult = await buildVendor(outDir, options);
+  // 4. Vendor shim 번들 빌드 (React, ReactDOM, ReactDOMClient)
+  const vendorResult = await buildVendorShims(outDir, options);
   if (!vendorResult.success) {
-    errors.push(...vendorResult.errors.map((e) => `[Vendor] ${e}`));
+    errors.push(...vendorResult.errors);
   }
 
   // 5. 각 Island 번들 빌드
@@ -544,7 +604,7 @@ export async function buildClientBundles(
     outputs,
     hydratedRoutes,
     runtimeResult.outputPath,
-    vendorResult.outputPath,
+    vendorResult,
     env
   );
 

package/src/bundler/types.ts

@@ -57,9 +57,13 @@ export interface BundleManifest {
   shared: {
     /** Hydration 런타임 */
     runtime: string;
-    /** 벤더 번들 (React 등) */
+    /** React 번들 경로 */
     vendor: string;
   };
+  /** Import map for bare specifiers (react, react-dom, etc.) */
+  importMap?: {
+    imports: Record<string, string>;
+  };
 }
 
 /**

package/src/client/index.ts

@@ -17,6 +17,7 @@
 // Island API
 export {
   island,
+  wrapComponent,
   useServerData,
   useHydrated,
   useIslandEvent,
@@ -25,6 +26,7 @@ export {
   type IslandMetadata,
   type CompiledIsland,
   type FetchOptions,
+  type WrapComponentOptions,
 } from "./island";
 
 // Runtime API
@@ -41,7 +43,7 @@ export {
 } from "./runtime";
 
 // Re-export as Mandu namespace for consistent API
-import { island } from "./island";
+import { island, wrapComponent } from "./island";
 import { hydrateIslands, initializeRuntime } from "./runtime";
 
 /**
@@ -54,6 +56,12 @@ export const Mandu = {
    */
   island,
 
+  /**
+   * Wrap existing React component as island
+   * @see wrapComponent
+   */
+  wrapComponent,
+
   /**
    * Hydrate all islands on the page
    * @see hydrateIslands

package/src/client/island.ts

@@ -166,6 +166,65 @@ export function useIslandEvent<T = unknown>(
   };
 }
 
+/**
+ * 기존 React 컴포넌트를 Island로 래핑
+ *
+ * @example
+ * ```typescript
+ * // 기존 React 컴포넌트
+ * import DatePicker from 'react-datepicker';
+ *
+ * // Island로 래핑 (serverData가 그대로 props로 전달됨)
+ * export default Mandu.wrapComponent(DatePicker);
+ *
+ * // 또는 props 변환이 필요한 경우
+ * export default Mandu.wrapComponent(DatePicker, {
+ *   transformProps: (serverData) => ({
+ *     selected: new Date(serverData.selectedDate),
+ *     onChange: (date) => console.log(date),
+ *   })
+ * });
+ * ```
+ */
+export interface WrapComponentOptions<TServerData, TProps> {
+  /** 서버 데이터를 컴포넌트 props로 변환 */
+  transformProps?: (serverData: TServerData) => TProps;
+  /** 에러 시 표시할 UI */
+  errorBoundary?: (error: Error, reset: () => void) => ReactNode;
+  /** 로딩 중 표시할 UI */
+  loading?: () => ReactNode;
+}
+
+export function wrapComponent<TProps extends Record<string, any>>(
+  Component: React.ComponentType<TProps>,
+  options?: WrapComponentOptions<TProps, TProps>
+): CompiledIsland<TProps, TProps>;
+
+export function wrapComponent<TServerData, TProps>(
+  Component: React.ComponentType<TProps>,
+  options: WrapComponentOptions<TServerData, TProps> & { transformProps: (serverData: TServerData) => TProps }
+): CompiledIsland<TServerData, TProps>;
+
+export function wrapComponent<TServerData, TProps>(
+  Component: React.ComponentType<TProps>,
+  options?: WrapComponentOptions<TServerData, TProps>
+): CompiledIsland<TServerData, TProps> {
+  const { transformProps, errorBoundary, loading } = options || {};
+
+  return island({
+    setup: (serverData: TServerData) => {
+      return transformProps ? transformProps(serverData) : (serverData as unknown as TProps);
+    },
+    render: (props: TProps) => {
+      // React.createElement를 사용하여 Component 렌더링
+      const React = require("react");
+      return React.createElement(Component, props);
+    },
+    errorBoundary,
+    loading,
+  });
+}
+
 /**
  * API 호출 헬퍼
  */

package/src/runtime/ssr.ts

@@ -39,6 +39,18 @@ function serializeServerData(data: Record<string, unknown>): string {
 <script>window.__MANDU_DATA__ = JSON.parse(document.getElementById('__MANDU_DATA__').textContent);</script>`;
 }
 
+/**
+ * Import map 생성 (bare specifier 해결용)
+ */
+function generateImportMap(manifest: BundleManifest): string {
+  if (!manifest.importMap || Object.keys(manifest.importMap.imports).length === 0) {
+    return "";
+  }
+
+  const importMapJson = JSON.stringify(manifest.importMap, null, 2);
+  return `<script type="importmap">${importMapJson}</script>`;
+}
+
 /**
  * Hydration 스크립트 태그 생성
  */
@@ -48,16 +60,17 @@ function generateHydrationScripts(
 ): string {
   const scripts: string[] = [];
 
+  // Import map 먼저 (반드시 module scripts 전에 위치해야 함)
+  const importMap = generateImportMap(manifest);
+  if (importMap) {
+    scripts.push(importMap);
+  }
+
   // Runtime 로드
   if (manifest.shared.runtime) {
     scripts.push(`<script type="module" src="${manifest.shared.runtime}"></script>`);
   }
 
-  // Vendor 로드
-  if (manifest.shared.vendor) {
-    scripts.push(`<script type="module" src="${manifest.shared.vendor}"></script>`);
-  }
-
   // Island 번들 로드
   const bundle = manifest.bundles[routeId];
   if (bundle) {