@mandujs/core 0.3.4 → 0.4.0

package/src/bundler/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Mandu Bundler Types
+ */
+
+/**
+ * 번들 빌드 결과
+ */
+export interface BundleResult {
+  success: boolean;
+  outputs: BundleOutput[];
+  errors: string[];
+  manifest: BundleManifest;
+  stats: BundleStats;
+}
+
+/**
+ * 개별 번들 출력
+ */
+export interface BundleOutput {
+  /** 라우트 ID */
+  routeId: string;
+  /** 원본 엔트리포인트 */
+  entrypoint: string;
+  /** 출력 경로 (서버 기준) */
+  outputPath: string;
+  /** 파일 크기 (bytes) */
+  size: number;
+  /** gzip 압축 크기 (bytes) */
+  gzipSize: number;
+}
+
+/**
+ * 번들 매니페스트
+ */
+export interface BundleManifest {
+  /** 매니페스트 버전 */
+  version: number;
+  /** 빌드 시간 */
+  buildTime: string;
+  /** 환경 */
+  env: "development" | "production";
+  /** 라우트별 번들 정보 */
+  bundles: Record<
+    string,
+    {
+      /** JavaScript 번들 경로 */
+      js: string;
+      /** CSS 번들 경로 (있는 경우) */
+      css?: string;
+      /** 의존하는 공유 청크 */
+      dependencies: string[];
+      /** Hydration 우선순위 */
+      priority: "immediate" | "visible" | "idle" | "interaction";
+    }
+  >;
+  /** 공유 청크 */
+  shared: {
+    /** Hydration 런타임 */
+    runtime: string;
+    /** 벤더 번들 (React 등) */
+    vendor: string;
+  };
+}
+
+/**
+ * 번들 통계
+ */
+export interface BundleStats {
+  /** 전체 크기 */
+  totalSize: number;
+  /** 전체 gzip 크기 */
+  totalGzipSize: number;
+  /** 가장 큰 번들 */
+  largestBundle: {
+    routeId: string;
+    size: number;
+  };
+  /** 빌드 시간 (ms) */
+  buildTime: number;
+  /** 번들 수 */
+  bundleCount: number;
+}
+
+/**
+ * 번들러 옵션
+ */
+export interface BundlerOptions {
+  /** 코드 압축 여부 (기본: production에서 true) */
+  minify?: boolean;
+  /** 소스맵 생성 여부 */
+  sourcemap?: boolean;
+  /** 파일 감시 모드 */
+  watch?: boolean;
+  /** 출력 디렉토리 (기본: .mandu/client) */
+  outDir?: string;
+  /** 외부 모듈 (번들에서 제외) */
+  external?: string[];
+  /** 환경 변수 주입 */
+  define?: Record<string, string>;
+}

package/src/client/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Mandu Client Module 🏝️
+ * 클라이언트 사이드 hydration을 위한 API
+ *
+ * @example
+ * ```typescript
+ * // spec/slots/todos.client.ts
+ * import { Mandu } from "@mandujs/core/client";
+ *
+ * export default Mandu.island<TodosData>({
+ *   setup: (data) => { ... },
+ *   render: (props) => <TodoList {...props} />
+ * });
+ * ```
+ */
+
+// Island API
+export {
+  island,
+  useServerData,
+  useHydrated,
+  useIslandEvent,
+  fetchApi,
+  type IslandDefinition,
+  type IslandMetadata,
+  type CompiledIsland,
+  type FetchOptions,
+} from "./island";
+
+// Runtime API
+export {
+  registerIsland,
+  getRegisteredIslands,
+  getServerData,
+  hydrateIslands,
+  getHydrationState,
+  unmountIsland,
+  unmountAllIslands,
+  initializeRuntime,
+  type IslandLoader,
+} from "./runtime";
+
+// Re-export as Mandu namespace for consistent API
+import { island } from "./island";
+import { hydrateIslands, initializeRuntime } from "./runtime";
+
+/**
+ * Mandu Client namespace
+ */
+export const Mandu = {
+  /**
+   * Create an island component
+   * @see island
+   */
+  island,
+
+  /**
+   * Hydrate all islands on the page
+   * @see hydrateIslands
+   */
+  hydrate: hydrateIslands,
+
+  /**
+   * Initialize the hydration runtime
+   * @see initializeRuntime
+   */
+  init: initializeRuntime,
+};

package/src/client/island.ts

@@ -0,0 +1,197 @@
+/**
+ * Mandu Island - Client Slot API 🏝️
+ * Hydration을 위한 클라이언트 사이드 컴포넌트 정의
+ */
+
+import type { ReactNode } from "react";
+
+/**
+ * Island 정의 타입
+ * @template TServerData - SSR에서 전달받는 서버 데이터 타입
+ * @template TSetupResult - setup 함수가 반환하는 결과 타입
+ */
+export interface IslandDefinition<TServerData, TSetupResult> {
+  /**
+   * Setup Phase
+   * - 서버 데이터를 받아 클라이언트 상태 초기화
+   * - React hooks 사용 가능
+   * - 반환값이 render 함수에 전달됨
+   */
+  setup: (serverData: TServerData) => TSetupResult;
+
+  /**
+   * Render Phase
+   * - setup에서 반환된 값을 props로 받음
+   * - 순수 렌더링 로직만 포함
+   */
+  render: (props: TSetupResult) => ReactNode;
+
+  /**
+   * Optional: 에러 발생 시 표시할 fallback UI
+   */
+  errorBoundary?: (error: Error, reset: () => void) => ReactNode;
+
+  /**
+   * Optional: 로딩 중 표시할 UI (progressive hydration용)
+   */
+  loading?: () => ReactNode;
+}
+
+/**
+ * Island 컴포넌트의 메타데이터
+ */
+export interface IslandMetadata {
+  /** Island 고유 식별자 */
+  id: string;
+  /** SSR 데이터 키 */
+  dataKey: string;
+  /** Hydration 우선순위 */
+  priority: "immediate" | "visible" | "idle" | "interaction";
+}
+
+/**
+ * 컴파일된 Island 컴포넌트 타입
+ */
+export interface CompiledIsland<TServerData, TSetupResult> {
+  /** Island 정의 */
+  definition: IslandDefinition<TServerData, TSetupResult>;
+  /** Island 메타데이터 (빌드 시 주입) */
+  __mandu_island: true;
+  /** Island ID (빌드 시 주입) */
+  __mandu_island_id?: string;
+}
+
+/**
+ * Island 컴포넌트 생성
+ *
+ * @example
+ * ```typescript
+ * // spec/slots/todos.client.ts
+ * import { Mandu } from "@mandujs/core/client";
+ * import { useState, useCallback } from "react";
+ *
+ * interface TodosData {
+ *   todos: Todo[];
+ *   user: User | null;
+ * }
+ *
+ * export default Mandu.island<TodosData>({
+ *   setup: (serverData) => {
+ *     const [todos, setTodos] = useState(serverData.todos);
+ *     const addTodo = useCallback(async (text: string) => {
+ *       // ...
+ *     }, []);
+ *     return { todos, addTodo, user: serverData.user };
+ *   },
+ *   render: ({ todos, addTodo, user }) => (
+ *     <div>
+ *       {user && <span>Hello, {user.name}!</span>}
+ *       <TodoList todos={todos} onAdd={addTodo} />
+ *     </div>
+ *   )
+ * });
+ * ```
+ */
+export function island<TServerData, TSetupResult = TServerData>(
+  definition: IslandDefinition<TServerData, TSetupResult>
+): CompiledIsland<TServerData, TSetupResult> {
+  // Validate definition
+  if (typeof definition.setup !== "function") {
+    throw new Error("[Mandu Island] setup must be a function");
+  }
+  if (typeof definition.render !== "function") {
+    throw new Error("[Mandu Island] render must be a function");
+  }
+
+  return {
+    definition,
+    __mandu_island: true,
+  };
+}
+
+/**
+ * Island에서 사용할 수 있는 헬퍼 훅들
+ */
+
+/**
+ * SSR 데이터에 안전하게 접근하는 훅
+ * 서버 데이터가 없는 경우 fallback 반환
+ */
+export function useServerData<T>(key: string, fallback: T): T {
+  if (typeof window === "undefined") {
+    return fallback;
+  }
+
+  const manduData = (window as any).__MANDU_DATA__;
+  if (!manduData || !(key in manduData)) {
+    return fallback;
+  }
+
+  return manduData[key] as T;
+}
+
+/**
+ * Hydration 상태를 추적하는 훅
+ */
+export function useHydrated(): boolean {
+  if (typeof window === "undefined") {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Island 간 통신을 위한 이벤트 훅
+ */
+export function useIslandEvent<T = unknown>(
+  eventName: string,
+  handler: (data: T) => void
+): (data: T) => void {
+  if (typeof window === "undefined") {
+    return () => {};
+  }
+
+  // 이벤트 리스너 등록
+  const customEventName = `mandu:island:${eventName}`;
+
+  const listener = (event: CustomEvent<T>) => {
+    handler(event.detail);
+  };
+
+  window.addEventListener(customEventName, listener as EventListener);
+
+  // 이벤트 발송 함수 반환
+  return (data: T) => {
+    window.dispatchEvent(new CustomEvent(customEventName, { detail: data }));
+  };
+}
+
+/**
+ * API 호출 헬퍼
+ */
+export interface FetchOptions extends Omit<RequestInit, "body"> {
+  body?: unknown;
+}
+
+export async function fetchApi<T>(
+  url: string,
+  options: FetchOptions = {}
+): Promise<T> {
+  const { body, headers = {}, ...rest } = options;
+
+  const response = await fetch(url, {
+    headers: {
+      "Content-Type": "application/json",
+      ...headers,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+    ...rest,
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ message: response.statusText }));
+    throw new Error(error.message || `API Error: ${response.status}`);
+  }
+
+  return response.json();
+}

package/src/client/runtime.ts

@@ -0,0 +1,335 @@
+/**
+ * Mandu Hydration Runtime 🌊
+ * 브라우저에서 Island를 hydrate하는 런타임
+ */
+
+import { hydrateRoot } from "react-dom/client";
+import type { Root } from "react-dom/client";
+import type { CompiledIsland } from "./island";
+import type { ReactNode } from "react";
+import React from "react";
+
+/**
+ * Island 로더 타입
+ */
+export type IslandLoader = () => Promise<CompiledIsland<any, any>> | CompiledIsland<any, any>;
+
+/**
+ * Island 레지스트리
+ */
+const islandRegistry = new Map<string, IslandLoader>();
+
+/**
+ * Hydrated roots 추적
+ */
+const hydratedRoots = new Map<string, Root>();
+
+/**
+ * Hydration 상태 추적
+ */
+interface HydrationState {
+  total: number;
+  hydrated: number;
+  failed: number;
+  pending: Set<string>;
+}
+
+const hydrationState: HydrationState = {
+  total: 0,
+  hydrated: 0,
+  failed: 0,
+  pending: new Set(),
+};
+
+/**
+ * Island 등록
+ */
+export function registerIsland(id: string, loader: IslandLoader): void {
+  islandRegistry.set(id, loader);
+}
+
+/**
+ * 등록된 모든 Island 가져오기
+ */
+export function getRegisteredIslands(): string[] {
+  return Array.from(islandRegistry.keys());
+}
+
+/**
+ * 서버 데이터 가져오기
+ */
+export function getServerData<T = unknown>(islandId: string): T | undefined {
+  if (typeof window === "undefined") {
+    return undefined;
+  }
+
+  const manduData = (window as any).__MANDU_DATA__;
+  if (!manduData) {
+    return undefined;
+  }
+
+  return manduData[islandId]?.serverData as T;
+}
+
+/**
+ * Priority-based hydration 스케줄러
+ */
+type HydrationPriority = "immediate" | "visible" | "idle" | "interaction";
+
+function scheduleHydration(
+  element: HTMLElement,
+  id: string,
+  priority: HydrationPriority,
+  serverData: unknown
+): void {
+  switch (priority) {
+    case "immediate":
+      hydrateIsland(element, id, serverData);
+      break;
+
+    case "visible":
+      if ("IntersectionObserver" in window) {
+        const observer = new IntersectionObserver(
+          (entries) => {
+            if (entries[0].isIntersecting) {
+              observer.disconnect();
+              hydrateIsland(element, id, serverData);
+            }
+          },
+          { rootMargin: "50px" }
+        );
+        observer.observe(element);
+      } else {
+        // Fallback for older browsers
+        hydrateIsland(element, id, serverData);
+      }
+      break;
+
+    case "idle":
+      if ("requestIdleCallback" in window) {
+        (window as any).requestIdleCallback(() => {
+          hydrateIsland(element, id, serverData);
+        });
+      } else {
+        // Fallback
+        setTimeout(() => hydrateIsland(element, id, serverData), 200);
+      }
+      break;
+
+    case "interaction": {
+      const hydrate = () => {
+        element.removeEventListener("mouseenter", hydrate);
+        element.removeEventListener("focusin", hydrate);
+        element.removeEventListener("touchstart", hydrate);
+        hydrateIsland(element, id, serverData);
+      };
+      element.addEventListener("mouseenter", hydrate, { once: true, passive: true });
+      element.addEventListener("focusin", hydrate, { once: true });
+      element.addEventListener("touchstart", hydrate, { once: true, passive: true });
+      break;
+    }
+  }
+}
+
+/**
+ * 단일 Island hydrate
+ */
+async function hydrateIsland(
+  element: HTMLElement,
+  id: string,
+  serverData: unknown
+): Promise<void> {
+  const loader = islandRegistry.get(id);
+  if (!loader) {
+    console.warn(`[Mandu] Island not registered: ${id}`);
+    hydrationState.failed++;
+    hydrationState.pending.delete(id);
+    return;
+  }
+
+  try {
+    // 로더 실행 (dynamic import 또는 직접 참조)
+    const island = await Promise.resolve(loader());
+
+    if (!island.__mandu_island) {
+      throw new Error(`[Mandu] Invalid island: ${id}`);
+    }
+
+    const { definition } = island;
+
+    // Island 컴포넌트 생성
+    function IslandComponent(): ReactNode {
+      const setupResult = definition.setup(serverData);
+      return definition.render(setupResult);
+    }
+
+    // ErrorBoundary가 있으면 감싸기
+    let content: ReactNode;
+    if (definition.errorBoundary) {
+      content = React.createElement(
+        ManduErrorBoundary,
+        {
+          fallback: (error: Error, reset: () => void) => definition.errorBoundary!(error, reset),
+        },
+        React.createElement(IslandComponent)
+      );
+    } else {
+      content = React.createElement(IslandComponent);
+    }
+
+    // Hydrate
+    const root = hydrateRoot(element, content);
+    hydratedRoots.set(id, root);
+
+    // 상태 업데이트
+    element.setAttribute("data-mandu-hydrated", "true");
+    hydrationState.hydrated++;
+    hydrationState.pending.delete(id);
+
+    // 성능 마커
+    if (typeof performance !== "undefined" && performance.mark) {
+      performance.mark(`mandu-hydrated-${id}`);
+    }
+
+    // Hydration 완료 이벤트
+    element.dispatchEvent(
+      new CustomEvent("mandu:hydrated", {
+        bubbles: true,
+        detail: { id, serverData },
+      })
+    );
+  } catch (error) {
+    console.error(`[Mandu] Hydration failed for island ${id}:`, error);
+    hydrationState.failed++;
+    hydrationState.pending.delete(id);
+
+    // 에러 상태 표시
+    element.setAttribute("data-mandu-error", "true");
+
+    // 에러 이벤트
+    element.dispatchEvent(
+      new CustomEvent("mandu:hydration-error", {
+        bubbles: true,
+        detail: { id, error },
+      })
+    );
+  }
+}
+
+/**
+ * 모든 Island hydrate 시작
+ */
+export async function hydrateIslands(): Promise<void> {
+  if (typeof document === "undefined") {
+    return;
+  }
+
+  const islands = document.querySelectorAll<HTMLElement>("[data-mandu-island]");
+  const manduData = (window as any).__MANDU_DATA__ || {};
+
+  hydrationState.total = islands.length;
+
+  for (const element of islands) {
+    const id = element.getAttribute("data-mandu-island");
+    if (!id) continue;
+
+    const priority = (element.getAttribute("data-mandu-priority") || "visible") as HydrationPriority;
+    const data = manduData[id]?.serverData || {};
+
+    hydrationState.pending.add(id);
+    scheduleHydration(element, id, priority, data);
+  }
+}
+
+/**
+ * Hydration 상태 조회
+ */
+export function getHydrationState(): Readonly<HydrationState> {
+  return { ...hydrationState };
+}
+
+/**
+ * 특정 Island unmount
+ */
+export function unmountIsland(id: string): boolean {
+  const root = hydratedRoots.get(id);
+  if (!root) {
+    return false;
+  }
+
+  root.unmount();
+  hydratedRoots.delete(id);
+  return true;
+}
+
+/**
+ * 모든 Island unmount
+ */
+export function unmountAllIslands(): void {
+  for (const [id, root] of hydratedRoots) {
+    root.unmount();
+    hydratedRoots.delete(id);
+  }
+}
+
+/**
+ * 간단한 ErrorBoundary 컴포넌트
+ */
+interface ErrorBoundaryProps {
+  children: ReactNode;
+  fallback: (error: Error, reset: () => void) => ReactNode;
+}
+
+interface ErrorBoundaryState {
+  error: Error | null;
+}
+
+class ManduErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
+    console.error("[Mandu] Island error:", error, errorInfo);
+  }
+
+  reset = (): void => {
+    this.setState({ error: null });
+  };
+
+  render(): ReactNode {
+    if (this.state.error) {
+      return this.props.fallback(this.state.error, this.reset);
+    }
+    return this.props.children;
+  }
+}
+
+/**
+ * 자동 초기화 (스크립트 로드 시)
+ */
+export function initializeRuntime(): void {
+  if (typeof document === "undefined") {
+    return;
+  }
+
+  // DOM이 준비되면 hydration 시작
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", () => {
+      hydrateIslands();
+    });
+  } else {
+    // 이미 DOM이 준비된 경우
+    hydrateIslands();
+  }
+}
+
+// 자동 초기화 여부 (번들 시 설정)
+if (typeof window !== "undefined" && (window as any).__MANDU_AUTO_INIT__ !== false) {
+  initializeRuntime();
+}