@mandujs/core 0.5.6 → 0.6.0

package/src/client/router.ts

@@ -0,0 +1,387 @@
+/**
+ * Mandu Client-side Router 🧭
+ * SPA 스타일 네비게이션을 위한 클라이언트 라우터
+ */
+
+import type { ReactNode } from "react";
+
+// ========== Types ==========
+
+export interface RouteInfo {
+  id: string;
+  pattern: string;
+  params: Record<string, string>;
+}
+
+export interface NavigationState {
+  state: "idle" | "loading";
+  location?: string;
+}
+
+export interface RouterState {
+  currentRoute: RouteInfo | null;
+  loaderData: unknown;
+  navigation: NavigationState;
+}
+
+export interface NavigateOptions {
+  /** history.replaceState 사용 여부 */
+  replace?: boolean;
+  /** 스크롤 위치 복원 여부 */
+  scroll?: boolean;
+}
+
+type RouterListener = (state: RouterState) => void;
+
+// ========== Router State ==========
+
+let routerState: RouterState = {
+  currentRoute: null,
+  loaderData: undefined,
+  navigation: { state: "idle" },
+};
+
+const listeners = new Set<RouterListener>();
+
+/**
+ * 초기화: 서버에서 전달된 라우트 정보로 상태 설정
+ */
+function initializeFromServer(): void {
+  if (typeof window === "undefined") return;
+
+  const route = (window as any).__MANDU_ROUTE__;
+  const data = (window as any).__MANDU_DATA__;
+
+  if (route) {
+    // URL에서 실제 params 추출
+    const params = extractParamsFromPath(route.pattern, window.location.pathname);
+
+    routerState = {
+      currentRoute: {
+        id: route.id,
+        pattern: route.pattern,
+        params,
+      },
+      loaderData: data?.[route.id]?.serverData,
+      navigation: { state: "idle" },
+    };
+  }
+}
+
+// ========== Pattern Matching ==========
+
+interface CompiledPattern {
+  regex: RegExp;
+  paramNames: string[];
+}
+
+const patternCache = new Map<string, CompiledPattern>();
+
+/**
+ * 패턴을 정규식으로 컴파일
+ */
+function compilePattern(pattern: string): CompiledPattern {
+  const cached = patternCache.get(pattern);
+  if (cached) return cached;
+
+  const paramNames: string[] = [];
+  const PARAM_PLACEHOLDER = "\x00PARAM\x00";
+  const paramMatches: string[] = [];
+
+  const withPlaceholders = pattern.replace(
+    /:([a-zA-Z_][a-zA-Z0-9_]*)/g,
+    (_, paramName) => {
+      paramMatches.push(paramName);
+      return PARAM_PLACEHOLDER;
+    }
+  );
+
+  const escaped = withPlaceholders.replace(/[.*+?^${}()|[\]\\\/]/g, "\\$&");
+
+  let paramIndex = 0;
+  const regexStr = escaped.replace(
+    new RegExp(PARAM_PLACEHOLDER.replace(/\x00/g, "\\x00"), "g"),
+    () => {
+      paramNames.push(paramMatches[paramIndex++]);
+      return "([^/]+)";
+    }
+  );
+
+  const compiled = {
+    regex: new RegExp(`^${regexStr}$`),
+    paramNames,
+  };
+
+  patternCache.set(pattern, compiled);
+  return compiled;
+}
+
+/**
+ * 패턴에서 파라미터 추출
+ */
+function extractParamsFromPath(
+  pattern: string,
+  pathname: string
+): Record<string, string> {
+  const compiled = compilePattern(pattern);
+  const match = pathname.match(compiled.regex);
+
+  if (!match) return {};
+
+  const params: Record<string, string> = {};
+  compiled.paramNames.forEach((name, index) => {
+    params[name] = match[index + 1];
+  });
+
+  return params;
+}
+
+// ========== Navigation ==========
+
+/**
+ * 페이지 네비게이션
+ */
+export async function navigate(
+  to: string,
+  options: NavigateOptions = {}
+): Promise<void> {
+  const { replace = false, scroll = true } = options;
+
+  try {
+    const url = new URL(to, window.location.origin);
+
+    // 외부 URL은 일반 네비게이션
+    if (url.origin !== window.location.origin) {
+      window.location.href = to;
+      return;
+    }
+
+    // 로딩 상태 시작
+    routerState = {
+      ...routerState,
+      navigation: { state: "loading", location: to },
+    };
+    notifyListeners();
+
+    // 데이터 fetch
+    const dataUrl = `${url.pathname}${url.search ? url.search + "&" : "?"}_data=1`;
+    const response = await fetch(dataUrl);
+
+    if (!response.ok) {
+      // 에러 시 full navigation fallback
+      window.location.href = to;
+      return;
+    }
+
+    const data = await response.json();
+
+    // History 업데이트
+    const historyState = { routeId: data.routeId, params: data.params };
+    if (replace) {
+      history.replaceState(historyState, "", to);
+    } else {
+      history.pushState(historyState, "", to);
+    }
+
+    // 상태 업데이트
+    routerState = {
+      currentRoute: {
+        id: data.routeId,
+        pattern: data.pattern,
+        params: data.params,
+      },
+      loaderData: data.loaderData,
+      navigation: { state: "idle" },
+    };
+
+    // __MANDU_DATA__ 업데이트
+    if (typeof window !== "undefined") {
+      (window as any).__MANDU_DATA__ = {
+        ...(window as any).__MANDU_DATA__,
+        [data.routeId]: { serverData: data.loaderData },
+      };
+    }
+
+    notifyListeners();
+
+    // 스크롤 복원
+    if (scroll) {
+      window.scrollTo(0, 0);
+    }
+  } catch (error) {
+    console.error("[Mandu Router] Navigation failed:", error);
+    // 에러 시 full navigation fallback
+    window.location.href = to;
+  }
+}
+
+/**
+ * 뒤로가기/앞으로가기 처리
+ */
+function handlePopState(event: PopStateEvent): void {
+  const state = event.state;
+
+  if (state?.routeId) {
+    // 이미 방문한 페이지 - 데이터 다시 fetch
+    navigate(window.location.pathname + window.location.search, {
+      replace: true,
+      scroll: false,
+    });
+  }
+}
+
+// ========== State Management ==========
+
+/**
+ * 리스너에게 상태 변경 알림
+ */
+function notifyListeners(): void {
+  for (const listener of listeners) {
+    try {
+      listener(routerState);
+    } catch (error) {
+      console.error("[Mandu Router] Listener error:", error);
+    }
+  }
+}
+
+/**
+ * 상태 변경 구독
+ */
+export function subscribe(listener: RouterListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/**
+ * 현재 라우터 상태 가져오기
+ */
+export function getRouterState(): RouterState {
+  return routerState;
+}
+
+/**
+ * 현재 라우트 정보 가져오기
+ */
+export function getCurrentRoute(): RouteInfo | null {
+  return routerState.currentRoute;
+}
+
+/**
+ * 현재 loader 데이터 가져오기
+ */
+export function getLoaderData<T = unknown>(): T | undefined {
+  return routerState.loaderData as T | undefined;
+}
+
+/**
+ * 네비게이션 상태 가져오기
+ */
+export function getNavigationState(): NavigationState {
+  return routerState.navigation;
+}
+
+// ========== Link Click Handler ==========
+
+/**
+ * 링크 클릭 이벤트 핸들러 (이벤트 위임용)
+ */
+function handleLinkClick(event: MouseEvent): void {
+  // 기본 동작 조건 체크
+  if (
+    event.defaultPrevented ||
+    event.button !== 0 ||
+    event.metaKey ||
+    event.altKey ||
+    event.ctrlKey ||
+    event.shiftKey
+  ) {
+    return;
+  }
+
+  // 가장 가까운 앵커 태그 찾기
+  const anchor = (event.target as HTMLElement).closest("a");
+  if (!anchor) return;
+
+  // data-mandu-link 속성이 있는 링크만 처리
+  if (!anchor.hasAttribute("data-mandu-link")) return;
+
+  const href = anchor.getAttribute("href");
+  if (!href) return;
+
+  // 외부 링크 체크
+  try {
+    const url = new URL(href, window.location.origin);
+    if (url.origin !== window.location.origin) return;
+  } catch {
+    return;
+  }
+
+  // 기본 동작 방지 및 Client-side 네비게이션
+  event.preventDefault();
+  navigate(href);
+}
+
+// ========== Prefetch ==========
+
+const prefetchedUrls = new Set<string>();
+
+/**
+ * 페이지 데이터 미리 로드
+ */
+export async function prefetch(url: string): Promise<void> {
+  if (prefetchedUrls.has(url)) return;
+
+  try {
+    const dataUrl = `${url}${url.includes("?") ? "&" : "?"}_data=1`;
+    await fetch(dataUrl, { priority: "low" } as RequestInit);
+    prefetchedUrls.add(url);
+  } catch {
+    // Prefetch 실패는 무시
+  }
+}
+
+// ========== Initialization ==========
+
+let initialized = false;
+
+/**
+ * 라우터 초기화
+ */
+export function initializeRouter(): void {
+  if (typeof window === "undefined" || initialized) return;
+
+  initialized = true;
+
+  // 서버 데이터로 초기화
+  initializeFromServer();
+
+  // popstate 이벤트 리스너
+  window.addEventListener("popstate", handlePopState);
+
+  // 링크 클릭 이벤트 위임
+  document.addEventListener("click", handleLinkClick);
+
+  console.log("[Mandu Router] Initialized");
+}
+
+/**
+ * 라우터 정리
+ */
+export function cleanupRouter(): void {
+  if (typeof window === "undefined" || !initialized) return;
+
+  window.removeEventListener("popstate", handlePopState);
+  document.removeEventListener("click", handleLinkClick);
+  listeners.clear();
+  initialized = false;
+}
+
+// 자동 초기화 (DOM 준비 시)
+if (typeof window !== "undefined") {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initializeRouter);
+  } else {
+    initializeRouter();
+  }
+}

package/src/generator/templates.ts

@@ -190,6 +190,13 @@ function computeSlotImportPath(slotModule: string, fromDir: string): string {
 
 export function generatePageComponent(route: RouteSpec): string {
   const pageName = toPascalCase(route.id);
+
+  // slotModule이 있으면 PageHandler 형식으로 생성 (filling 포함)
+  if (route.slotModule) {
+    return generatePageHandlerWithSlot(route);
+  }
+
+  // slotModule이 없으면 기존 방식
   return `// Generated by Mandu - DO NOT EDIT DIRECTLY
 // Route ID: ${route.id}
 // Pattern: ${route.pattern}
@@ -198,6 +205,7 @@ import React from "react";
 
 interface Props {
   params: Record<string, string>;
+  loaderData?: unknown;
 }
 
 export default function ${pageName}Page({ params }: Props): React.ReactElement {
@@ -210,6 +218,45 @@ export default function ${pageName}Page({ params }: Props): React.ReactElement {
 `;
 }
 
+/**
+ * slotModule이 있는 Page Route용 Handler 생성
+ * - component와 filling을 함께 export
+ * - server.ts에서 filling.executeLoader() 호출 가능
+ */
+export function generatePageHandlerWithSlot(route: RouteSpec): string {
+  const pageName = toPascalCase(route.id);
+  const slotImportPath = computeSlotImportPath(route.slotModule!, "apps/server/generated/routes");
+
+  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
+// Route ID: ${route.id}
+// Pattern: ${route.pattern}
+// Slot Module: ${route.slotModule}
+
+import React from "react";
+import filling from "${slotImportPath}";
+
+interface Props {
+  params: Record<string, string>;
+  loaderData?: unknown;
+}
+
+function ${pageName}Page({ params, loaderData }: Props): React.ReactElement {
+  return React.createElement("div", null,
+    React.createElement("h1", null, "${pageName} Page"),
+    React.createElement("p", null, "Route ID: ${route.id}"),
+    React.createElement("p", null, "Pattern: ${route.pattern}"),
+    loaderData ? React.createElement("pre", null, JSON.stringify(loaderData, null, 2)) : null
+  );
+}
+
+// PageRegistration 형식으로 export (server.ts의 registerPageHandler용)
+export default {
+  component: ${pageName}Page,
+  filling: filling,
+};
+`;
+}
+
 /**
  * Convert string to PascalCase (handles kebab-case, snake_case)
  * "todo-page" → "TodoPage"

package/src/runtime/server.ts

@@ -1,6 +1,8 @@
 import type { Server } from "bun";
 import type { RoutesManifest } from "../spec/schema";
 import type { BundleManifest } from "../bundler/types";
+import type { ManduFilling } from "../filling/filling";
+import { ManduContext } from "../filling/context";
 import { Router } from "./router";
 import { renderSSR } from "./ssr";
 import React from "react";
@@ -103,18 +105,36 @@ export interface ManduServer {
 export type ApiHandler = (req: Request, params: Record<string, string>) => Response | Promise<Response>;
 export type PageLoader = () => Promise<{ default: React.ComponentType<{ params: Record<string, string> }> }>;
 
+/**
+ * Page 등록 정보
+ * - component: React 컴포넌트
+ * - filling: Slot의 ManduFilling 인스턴스 (loader 포함)
+ */
+export interface PageRegistration {
+  component: React.ComponentType<{ params: Record<string, string>; loaderData?: unknown }>;
+  filling?: ManduFilling<unknown>;
+}
+
+/**
+ * Page Handler - 컴포넌트와 filling을 함께 반환
+ */
+export type PageHandler = () => Promise<PageRegistration>;
+
 export interface AppContext {
   routeId: string;
   url: string;
   params: Record<string, string>;
+  /** SSR loader에서 로드한 데이터 */
+  loaderData?: unknown;
 }
 
-type RouteComponent = (props: { params: Record<string, string> }) => React.ReactElement;
+type RouteComponent = (props: { params: Record<string, string>; loaderData?: unknown }) => React.ReactElement;
 type CreateAppFn = (context: AppContext) => React.ReactElement;
 
 // Registry
 const apiHandlers: Map<string, ApiHandler> = new Map();
 const pageLoaders: Map<string, PageLoader> = new Map();
+const pageHandlers: Map<string, PageHandler> = new Map();
 const routeComponents: Map<string, RouteComponent> = new Map();
 let createAppFn: CreateAppFn | null = null;
 
@@ -141,6 +161,14 @@ export function registerPageLoader(routeId: string, loader: PageLoader): void {
   pageLoaders.set(routeId, loader);
 }
 
+/**
+ * Page Handler 등록 (컴포넌트 + filling)
+ * filling이 있으면 loader를 실행하여 serverData 전달
+ */
+export function registerPageHandler(routeId: string, handler: PageHandler): void {
+  pageHandlers.set(routeId, handler);
+}
+
 export function registerRouteComponent(routeId: string, component: RouteComponent): void {
   routeComponents.set(routeId, component);
 }
@@ -160,7 +188,10 @@ function defaultCreateApp(context: AppContext): React.ReactElement {
     );
   }
 
-  return React.createElement(Component, { params: context.params });
+  return React.createElement(Component, {
+    params: context.params,
+    loaderData: context.loaderData,
+  });
 }
 
 // ========== Static File Serving ==========
@@ -281,11 +312,25 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
   }
 
   if (route.kind === "page") {
-    const loader = pageLoaders.get(route.id);
-    if (loader) {
+    let loaderData: unknown;
+    let component: RouteComponent | undefined;
+
+    // Client-side Routing: 데이터 요청 감지
+    const isDataRequest = url.searchParams.has("_data");
+
+    // 1. PageHandler 방식 (신규 - filling 포함)
+    const pageHandler = pageHandlers.get(route.id);
+    if (pageHandler) {
       try {
-        const module = await loader();
-        registerRouteComponent(route.id, module.default);
+        const registration = await pageHandler();
+        component = registration.component as RouteComponent;
+        registerRouteComponent(route.id, component);
+
+        // Filling의 loader 실행
+        if (registration.filling?.hasLoader()) {
+          const ctx = new ManduContext(req, params);
+          loaderData = await registration.filling.executeLoader(ctx);
+        }
       } catch (err) {
         const pageError = createPageLoadErrorResponse(
           route.id,
@@ -299,15 +344,54 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
         return Response.json(response, { status: 500 });
       }
     }
+    // 2. PageLoader 방식 (레거시 호환)
+    else {
+      const loader = pageLoaders.get(route.id);
+      if (loader) {
+        try {
+          const module = await loader();
+          registerRouteComponent(route.id, module.default);
+        } catch (err) {
+          const pageError = createPageLoadErrorResponse(
+            route.id,
+            route.pattern,
+            err instanceof Error ? err : new Error(String(err))
+          );
+          console.error(`[Mandu] ${pageError.errorType}:`, pageError.message);
+          const response = formatErrorResponse(pageError, {
+            isDev: process.env.NODE_ENV !== "production",
+          });
+          return Response.json(response, { status: 500 });
+        }
+      }
+    }
 
+    // Client-side Routing: 데이터만 반환 (JSON)
+    if (isDataRequest) {
+      return Response.json({
+        routeId: route.id,
+        pattern: route.pattern,
+        params,
+        loaderData: loaderData ?? null,
+        timestamp: Date.now(),
+      });
+    }
+
+    // SSR 렌더링 (기존 로직)
     const appCreator = createAppFn || defaultCreateApp;
     try {
       const app = appCreator({
         routeId: route.id,
         url: req.url,
         params,
+        loaderData,
       });
 
+      // serverData 구조: { [routeId]: { serverData: loaderData } }
+      const serverData = loaderData
+        ? { [route.id]: { serverData: loaderData } }
+        : undefined;
+
       return renderSSR(app, {
         title: `${route.id} - Mandu`,
         isDev: serverSettings.isDev,
@@ -315,6 +399,10 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
         routeId: route.id,
         hydration: route.hydration,
         bundleManifest: serverSettings.bundleManifest,
+        serverData,
+        // Client-side Routing 활성화 정보 전달
+        enableClientRouter: true,
+        routePattern: route.pattern,
       });
     } catch (err) {
       const ssrError = createSSRErrorResponse(
@@ -418,8 +506,9 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
 export function clearRegistry(): void {
   apiHandlers.clear();
   pageLoaders.clear();
+  pageHandlers.clear();
   routeComponents.clear();
   createAppFn = null;
 }
 
-export { apiHandlers, pageLoaders, routeComponents };
+export { apiHandlers, pageLoaders, pageHandlers, routeComponents };