@mandujs/core 0.5.7 → 0.7.0

package/package.json

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

package/src/bundler/build.ts

@@ -279,6 +279,223 @@ export default jsxDevRuntime;
 `;
 }
 
+/**
+ * Client-side Router 런타임 소스 생성
+ */
+function generateRouterRuntimeSource(): string {
+  return `
+/**
+ * Mandu Client Router Runtime (Generated)
+ * Client-side Routing을 위한 런타임
+ */
+
+// 라우트 정보
+let currentRoute = window.__MANDU_ROUTE__ || null;
+let currentLoaderData = window.__MANDU_DATA__?.[currentRoute?.id]?.serverData;
+let navigationState = { state: 'idle' };
+const listeners = new Set();
+
+// 패턴 매칭 캐시
+const patternCache = new Map();
+
+function compilePattern(pattern) {
+  if (patternCache.has(pattern)) return patternCache.get(pattern);
+
+  const paramNames = [];
+  let paramIndex = 0;
+  const paramMatches = [];
+
+  const withPlaceholders = pattern.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, name) => {
+    paramMatches.push(name);
+    return '%%PARAM%%';
+  });
+
+  const escaped = withPlaceholders.replace(/[.*+?^\${}()|[\\]\\\\]/g, '\\\\$&');
+  const regexStr = escaped.replace(/%%PARAM%%/g, () => {
+    paramNames.push(paramMatches[paramIndex++]);
+    return '([^/]+)';
+  });
+
+  const compiled = { regex: new RegExp('^' + regexStr + '$'), paramNames };
+  patternCache.set(pattern, compiled);
+  return compiled;
+}
+
+function extractParams(pattern, pathname) {
+  const compiled = compilePattern(pattern);
+  const match = pathname.match(compiled.regex);
+  if (!match) return {};
+
+  const params = {};
+  compiled.paramNames.forEach((name, i) => { params[name] = match[i + 1]; });
+  return params;
+}
+
+function notifyListeners() {
+  const state = {
+    currentRoute,
+    loaderData: currentLoaderData,
+    navigation: navigationState
+  };
+  listeners.forEach(fn => { try { fn(state); } catch(e) {} });
+}
+
+export function subscribe(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function getRouterState() {
+  return {
+    currentRoute,
+    loaderData: currentLoaderData,
+    navigation: navigationState
+  };
+}
+
+export async function navigate(to, options = {}) {
+  const { replace = false, scroll = true } = options;
+
+  try {
+    const url = new URL(to, location.origin);
+    if (url.origin !== location.origin) {
+      location.href = to;
+      return;
+    }
+
+    navigationState = { state: 'loading', location: to };
+    notifyListeners();
+
+    const dataUrl = url.pathname + (url.search ? url.search + '&' : '?') + '_data=1';
+    const res = await fetch(dataUrl);
+
+    if (!res.ok) {
+      location.href = to;
+      return;
+    }
+
+    const data = await res.json();
+
+    if (replace) {
+      history.replaceState({ routeId: data.routeId }, '', to);
+    } else {
+      history.pushState({ routeId: data.routeId }, '', to);
+    }
+
+    currentRoute = { id: data.routeId, pattern: data.pattern, params: data.params };
+    currentLoaderData = data.loaderData;
+    navigationState = { state: 'idle' };
+
+    window.__MANDU_DATA__ = window.__MANDU_DATA__ || {};
+    window.__MANDU_DATA__[data.routeId] = { serverData: data.loaderData };
+
+    notifyListeners();
+
+    if (scroll) window.scrollTo(0, 0);
+  } catch (err) {
+    console.error('[Mandu Router] Error:', err);
+    location.href = to;
+  }
+}
+
+// Link 클릭 핸들러
+function handleClick(e) {
+  if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return;
+
+  const anchor = e.target.closest('a[data-mandu-link]');
+  if (!anchor) return;
+
+  const href = anchor.getAttribute('href');
+  if (!href) return;
+
+  try {
+    const url = new URL(href, location.origin);
+    if (url.origin !== location.origin) return;
+  } catch { return; }
+
+  e.preventDefault();
+  navigate(href);
+}
+
+// Popstate 핸들러
+function handlePopState(e) {
+  if (e.state?.routeId) {
+    navigate(location.pathname + location.search, { replace: true, scroll: false });
+  }
+}
+
+// 초기화
+function init() {
+  if (currentRoute) {
+    currentRoute.params = extractParams(currentRoute.pattern, location.pathname);
+  }
+
+  window.addEventListener('popstate', handlePopState);
+  document.addEventListener('click', handleClick);
+  console.log('[Mandu Router] Initialized');
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', init);
+} else {
+  init();
+}
+
+export { currentRoute, currentLoaderData, navigationState };
+`;
+}
+
+/**
+ * Router 런타임 번들 빌드
+ */
+async function buildRouterRuntime(
+  outDir: string,
+  options: BundlerOptions
+): Promise<{ success: boolean; outputPath: string; errors: string[] }> {
+  const routerPath = path.join(outDir, "_router.src.js");
+  const outputName = "_router.js";
+
+  try {
+    await Bun.write(routerPath, generateRouterRuntimeSource());
+
+    const result = await Bun.build({
+      entrypoints: [routerPath],
+      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(routerPath).catch(() => {});
+
+    if (!result.success) {
+      return {
+        success: false,
+        outputPath: "",
+        errors: result.logs.map((l) => l.message),
+      };
+    }
+
+    return {
+      success: true,
+      outputPath: `/.mandu/client/${outputName}`,
+      errors: [],
+    };
+  } catch (error) {
+    await fs.unlink(routerPath).catch(() => {});
+    return {
+      success: false,
+      outputPath: "",
+      errors: [String(error)],
+    };
+  }
+}
+
 /**
  * Island 엔트리 래퍼 생성
  */
@@ -503,6 +720,7 @@ function createBundleManifest(
   routes: RouteSpec[],
   runtimePath: string,
   vendorResult: VendorBuildResult,
+  routerPath: string,
   env: "development" | "production"
 ): BundleManifest {
   const bundles: BundleManifest["bundles"] = {};
@@ -526,6 +744,7 @@ function createBundleManifest(
     shared: {
       runtime: runtimePath,
       vendor: vendorResult.react, // primary vendor for backwards compatibility
+      router: routerPath, // Client-side Router
     },
     importMap: {
       imports: {
@@ -623,6 +842,12 @@ export async function buildClientBundles(
     errors.push(...runtimeResult.errors.map((e) => `[Runtime] ${e}`));
   }
 
+  // 3.5. Client-side Router 런타임 빌드
+  const routerResult = await buildRouterRuntime(outDir, options);
+  if (!routerResult.success) {
+    errors.push(...routerResult.errors.map((e) => `[Router] ${e}`));
+  }
+
   // 4. Vendor shim 번들 빌드 (React, ReactDOM, ReactDOMClient)
   const vendorResult = await buildVendorShims(outDir, options);
   if (!vendorResult.success) {
@@ -645,6 +870,7 @@ export async function buildClientBundles(
     hydratedRoutes,
     runtimeResult.outputPath,
     vendorResult,
+    routerResult.outputPath,
     env
   );
 

package/src/bundler/types.ts

@@ -59,6 +59,8 @@ export interface BundleManifest {
     runtime: string;
     /** React 번들 경로 */
     vendor: string;
+    /** Client-side Router 런타임 */
+    router?: string;
   };
   /** Import map for bare specifiers (react, react-dom, etc.) */
   importMap?: {

package/src/client/Link.tsx

@@ -0,0 +1,209 @@
+/**
+ * Mandu Link Component 🔗
+ * Client-side 네비게이션을 위한 Link 컴포넌트
+ */
+
+import React, {
+  type AnchorHTMLAttributes,
+  type MouseEvent,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useRef,
+} from "react";
+import { navigate, prefetch } from "./router";
+
+export interface LinkProps
+  extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  /** 이동할 URL */
+  href: string;
+  /** history.replaceState 사용 여부 */
+  replace?: boolean;
+  /** 마우스 hover 시 prefetch 여부 */
+  prefetch?: boolean;
+  /** 스크롤 위치 복원 여부 (기본: true) */
+  scroll?: boolean;
+  /** 자식 요소 */
+  children?: ReactNode;
+}
+
+/**
+ * Client-side 네비게이션 Link 컴포넌트
+ *
+ * @example
+ * ```tsx
+ * import { Link } from "@mandujs/core/client";
+ *
+ * // 기본 사용
+ * <Link href="/about">About</Link>
+ *
+ * // Prefetch 활성화
+ * <Link href="/users" prefetch>Users</Link>
+ *
+ * // Replace 모드 (뒤로가기 히스토리 없음)
+ * <Link href="/login" replace>Login</Link>
+ * ```
+ */
+export function Link({
+  href,
+  replace = false,
+  prefetch: shouldPrefetch = false,
+  scroll = true,
+  children,
+  onClick,
+  onMouseEnter,
+  onFocus,
+  ...rest
+}: LinkProps): React.ReactElement {
+  const prefetchedRef = useRef(false);
+
+  // 클릭 핸들러
+  const handleClick = useCallback(
+    (event: MouseEvent<HTMLAnchorElement>) => {
+      // 사용자 정의 onClick 먼저 실행
+      onClick?.(event);
+
+      // 기본 동작 방지 조건
+      if (
+        event.defaultPrevented ||
+        event.button !== 0 ||
+        event.metaKey ||
+        event.altKey ||
+        event.ctrlKey ||
+        event.shiftKey
+      ) {
+        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, { replace, scroll });
+    },
+    [href, replace, scroll, onClick]
+  );
+
+  // Prefetch 실행
+  const doPrefetch = useCallback(() => {
+    if (!shouldPrefetch || prefetchedRef.current) return;
+
+    try {
+      const url = new URL(href, window.location.origin);
+      if (url.origin === window.location.origin) {
+        prefetch(href);
+        prefetchedRef.current = true;
+      }
+    } catch {
+      // 무시
+    }
+  }, [href, shouldPrefetch]);
+
+  // 마우스 hover 핸들러
+  const handleMouseEnter = useCallback(
+    (event: MouseEvent<HTMLAnchorElement>) => {
+      onMouseEnter?.(event);
+      doPrefetch();
+    },
+    [onMouseEnter, doPrefetch]
+  );
+
+  // 포커스 핸들러 (키보드 네비게이션)
+  const handleFocus = useCallback(
+    (event: React.FocusEvent<HTMLAnchorElement>) => {
+      onFocus?.(event);
+      doPrefetch();
+    },
+    [onFocus, doPrefetch]
+  );
+
+  // Viewport 진입 시 prefetch (IntersectionObserver)
+  useEffect(() => {
+    if (!shouldPrefetch || typeof IntersectionObserver === "undefined") {
+      return;
+    }
+
+    // ref가 없으면 무시 (SSR)
+    return;
+  }, [shouldPrefetch]);
+
+  return (
+    <a
+      href={href}
+      onClick={handleClick}
+      onMouseEnter={handleMouseEnter}
+      onFocus={handleFocus}
+      data-mandu-link=""
+      {...rest}
+    >
+      {children}
+    </a>
+  );
+}
+
+/**
+ * NavLink - 현재 경로와 일치할 때 활성 스타일 적용
+ *
+ * @example
+ * ```tsx
+ * import { NavLink } from "@mandujs/core/client";
+ *
+ * <NavLink
+ *   href="/about"
+ *   className={({ isActive }) => isActive ? "active" : ""}
+ * >
+ *   About
+ * </NavLink>
+ * ```
+ */
+export interface NavLinkProps extends Omit<LinkProps, "className" | "style"> {
+  /** 활성 상태에 따른 className */
+  className?: string | ((props: { isActive: boolean }) => string);
+  /** 활성 상태에 따른 style */
+  style?:
+    | React.CSSProperties
+    | ((props: { isActive: boolean }) => React.CSSProperties);
+  /** 정확히 일치해야 활성화 (기본: false) */
+  exact?: boolean;
+}
+
+export function NavLink({
+  href,
+  className,
+  style,
+  exact = false,
+  ...rest
+}: NavLinkProps): React.ReactElement {
+  // 현재 경로와 비교
+  const isActive =
+    typeof window !== "undefined"
+      ? exact
+        ? window.location.pathname === href
+        : window.location.pathname.startsWith(href)
+      : false;
+
+  const resolvedClassName =
+    typeof className === "function" ? className({ isActive }) : className;
+
+  const resolvedStyle =
+    typeof style === "function" ? style({ isActive }) : style;
+
+  return (
+    <Link
+      href={href}
+      className={resolvedClassName}
+      style={resolvedStyle}
+      {...rest}
+    />
+  );
+}
+
+export default Link;