weifuwu 0.31.1 → 0.31.2

package/dist/react/client.d.ts

@@ -1,39 +1,76 @@
 /**
- * Client-side entry for React hydration + SPA navigation.
+ * Client-side entry for React hydration and SPA routing.
  *
- * Usage (in a client bundle):
+ * Hydration:
  * ```ts
- * import { hydrate, createClientRouter } from 'weifuwu/react/client'
- * import HomePage from './pages/HomePage.js'
+ * import { hydrate } from 'weifuwu/react/client'
+ * hydrate(HomePage, { layout: PageShell })
+ * ```
  *
- * const router = createClientRouter([
- *   { path: '/', component: HomePage },
- *   { path: '/users/:id', component: UserPage, loader: ... },
- * ])
- * hydrate(router.App)
+ * Client-side router:
+ * ```ts
+ * import { createBrowserRouter } from 'weifuwu/react/client'
+ * createBrowserRouter({
+ *   layout: PageShell,
+ *   routes: {
+ *     '/': () => import('./pages/HomePage.tsx'),
+ *     '/users/:id': () => import('./pages/UserPage.tsx'),
+ *   },
+ * })
  * ```
  */
-import { type ComponentType, type ReactElement } from 'react';
-import { type LinkProps } from './navigation.ts';
+import { type ComponentType, type ReactNode } from 'react';
 export interface HydrateOptions {
+    /** Hydration target element. Default: document.getElementById('root'). */
     container?: HTMLElement;
+    /**
+     * Layout component matching the server-side `react({ layout })` config.
+     * Must accept `{ children: ReactNode }`.
+     * When provided, wraps the page component before hydrating —
+     * producing the same tree the server rendered.
+     */
+    layout?: ComponentType<{
+        children: ReactNode;
+    }>;
 }
-export interface ClientRoute {
-    path: string;
-    component: ComponentType;
-    loader?: (params: Record<string, string>) => Promise<Record<string, unknown>>;
+/**
+ * Hydrate a page component. When `layout` is provided, the hydration tree
+ * matches the server-rendered structure: `<div id="root"><Layout><App /></Layout></div>`.
+ */
+export declare function hydrate(App: ComponentType, opts?: HydrateOptions): void;
+export interface ClientRouterOptions {
+    /** Layout component shared across all routes. */
+    layout?: ComponentType<{
+        children: ReactNode;
+    }>;
+    /**
+     * Route map: URL pattern → lazy component loader.
+     * Patterns support `:param` segments (e.g. `/users/:id`).
+     */
+    routes: Record<string, () => Promise<Record<string, unknown>>>;
+    /**
+     * Fallback component for unmatched routes.
+     * When omitted, unmatched routes do a full page navigation.
+     */
+    fallback?: () => Promise<Record<string, unknown>>;
+    /** Target element. Default: document.getElementById('root'). */
+    container?: HTMLElement;
 }
-export interface ClientRouter {
-    App: ComponentType;
-    Link: (props: LinkProps) => ReactElement;
-    useParams: () => Record<string, string>;
-    navigate: (url: string) => Promise<void>;
+interface RouterHandle {
+    navigate(url: string): Promise<void>;
+    renderPath(pathname: string, isInitial: boolean, data?: Record<string, unknown>): Promise<void>;
 }
-export { Link, useParams, useNavigate, useRevalidate, Form, useNavigation } from './navigation.ts';
-export type { LinkProps, FormProps, NavigationState } from './navigation.ts';
-export { ErrorBoundary } from './error-boundary.ts';
-export type { ErrorBoundaryProps } from './error-boundary.ts';
-export { defineRoute } from './route-utils.ts';
-export declare function createClientRouter(routes: ClientRoute[]): ClientRouter;
-export declare function hydrate(App: ComponentType, opts?: HydrateOptions): void;
+/**
+ * Initialise the client-side router.
+ *
+ * On the initial page load, it hydrates the matching route from the
+ * server-rendered HTML.  Subsequent in-app navigations fetch fresh
+ * server data and render the new page client-side.
+ */
+export declare function createBrowserRouter(opts: ClientRouterOptions): RouterHandle;
+/**
+ * Programmatic navigation (call from anywhere).
+ * Falls back to `window.location.href = url` if the router hasn't been initialised.
+ */
+export declare function navigate(url: string): void;
 export { useServerData } from './hooks.ts';

package/dist/react/client.js

@@ -1,11 +1,6 @@
 // src/react/client.ts
-import {
-  createElement as createElement2,
-  useEffect,
-  useCallback,
-  useSyncExternalStore
-} from "react";
-import { hydrateRoot } from "react-dom/client";
+import { createElement } from "react";
+import { hydrateRoot, createRoot } from "react-dom/client";
 
 // src/react/context.ts
 import { createContext } from "react";
@@ -20,132 +15,12 @@ function getServerDataContext() {
 }
 var ServerDataContext = getServerDataContext();
 
-// src/react/navigation.ts
-import {
-  createElement,
-  createContext as createContext2,
-  useContext as useContext2
-} from "react";
-
 // src/react/hooks.ts
 import { useContext } from "react";
 function useServerData() {
   return useContext(ServerDataContext);
 }
 
-// src/react/error-boundary.ts
-import { Component } from "react";
-var ErrorBoundary = class extends Component {
-  state = { error: null };
-  static getDerivedStateFromError(error) {
-    return { error };
-  }
-  componentDidCatch(error, info) {
-    this.props.onError?.(error, info);
-  }
-  render() {
-    if (this.state.error) {
-      return this.props.fallback;
-    }
-    return this.props.children;
-  }
-};
-
-// src/react/route-utils.ts
-function defineRoute(config) {
-  return config;
-}
-
-// src/react/navigation.ts
-var RouterContext = createContext2(null);
-RouterContext.displayName = "ClientRouter";
-function useParams() {
-  return useContext2(RouterContext)?.params ?? {};
-}
-function useNavigate() {
-  const ctx = useContext2(RouterContext);
-  if (!ctx) throw new Error("useNavigate() must be used within a client router");
-  return ctx.navigate;
-}
-function useNavigation() {
-  const ctx = useContext2(RouterContext);
-  return { state: ctx?.state ?? "idle" };
-}
-function Link({ href, children, ...props }) {
-  const router = useContext2(RouterContext);
-  const isExternal = href.startsWith("http://") || href.startsWith("https://") || href.startsWith("//") || href.startsWith("mailto:") || href.startsWith("tel:");
-  if (!router || isExternal || props.target !== void 0) {
-    return createElement("a", { href, ...props }, children);
-  }
-  const handleClick = (e) => {
-    if (e.ctrlKey || e.metaKey || e.altKey || e.shiftKey) return;
-    if (e.button !== 0) return;
-    e.preventDefault();
-    router.navigate(href);
-  };
-  return createElement("a", { href, onClick: handleClick, ...props }, children);
-}
-function useRevalidate() {
-  const ctx = useContext2(RouterContext);
-  if (!ctx) throw new Error("useRevalidate() must be used within a client router");
-  return ctx.revalidate;
-}
-function Form({ method = "post", action, children, ...props }) {
-  const router = useContext2(RouterContext);
-  if (!router) {
-    return createElement("form", { method, action, ...props }, children);
-  }
-  const handleSubmit = async (e) => {
-    e.preventDefault();
-    const form = e.target;
-    const formData = new FormData(form);
-    const url = action || window.location.pathname;
-    const fetchMethod = method === "get" ? "GET" : method.toUpperCase();
-    try {
-      const res = await fetch(url, {
-        method: fetchMethod,
-        body: fetchMethod === "GET" ? void 0 : formData,
-        redirect: "manual"
-      });
-      if (res.status >= 300 && res.status < 400) {
-        const loc = res.headers.get("Location");
-        if (loc) {
-          router.navigate(loc);
-          return;
-        }
-      }
-      await router.revalidate();
-    } catch (err) {
-      console.error("[weifuwu/react] Form submit failed:", err);
-    }
-  };
-  return createElement(
-    "form",
-    { method, action, ...props, onSubmit: handleSubmit },
-    children
-  );
-}
-function matchPath(pathname, pattern) {
-  const patParts = pattern.split("/").filter(Boolean);
-  const pathParts = pathname.split("/").filter(Boolean);
-  const hasWildcard = patParts[patParts.length - 1] === "*";
-  if (!hasWildcard && patParts.length !== pathParts.length) return null;
-  if (hasWildcard && pathParts.length < patParts.length - 1) return null;
-  const params = {};
-  for (let i = 0; i < patParts.length; i++) {
-    if (patParts[i] === "*") {
-      params["*"] = pathParts.slice(i).join("/");
-      break;
-    }
-    if (patParts[i].startsWith(":")) {
-      params[patParts[i].slice(1)] = decodeURIComponent(pathParts[i]);
-    } else if (patParts[i] !== pathParts[i]) {
-      return null;
-    }
-  }
-  return params;
-}
-
 // src/react/client.ts
 function readInitialData() {
   if (typeof document === "undefined") return {};
@@ -158,143 +33,150 @@ function readInitialData() {
   }
   return {};
 }
-function createClientRouter(routes) {
-  function findRoute(pathname) {
-    for (const route of routes) {
-      const params = matchPath(pathname, route.path);
-      if (params) return { route, params };
+async function fetchPageData(url) {
+  const res = await fetch(url);
+  const html = await res.text();
+  const match = html.match(/<script[^>]*id="__WEIFUWU_DATA__"[^>]*>([\s\S]*?)<\/script>/);
+  if (match) {
+    try {
+      return JSON.parse(match[1]);
+    } catch {
+    }
+  }
+  return {};
+}
+function compilePattern(pattern) {
+  const paramNames = [];
+  const regexStr = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/:([^/]+)/g, (_, name) => {
+    paramNames.push(name);
+    return "([^/]+)";
+  });
+  return { regex: new RegExp(`^${regexStr}$`), paramNames };
+}
+function matchRoute(pathname, routes) {
+  for (const route of routes) {
+    const m = pathname.match(route.regex);
+    if (m) {
+      const params = {};
+      route.paramNames.forEach((name, i) => {
+        params[name] = m[i + 1];
+      });
+      return { route, params };
     }
-    return null;
   }
-  let state = {
-    location: typeof window !== "undefined" ? window.location.pathname : "/",
-    data: readInitialData(),
-    navId: 0,
-    state: "idle"
-  };
-  const listeners = /* @__PURE__ */ new Set();
-  function getSnapshot() {
-    return state;
+  return null;
+}
+function extractComponent(mod) {
+  if (mod.default && typeof mod.default === "function") return mod.default;
+  for (const val of Object.values(mod)) {
+    if (typeof val === "function") return val;
+  }
+  throw new Error("No component export found in module");
+}
+function hydrate(App, opts) {
+  const container = opts?.container ?? document.getElementById("root");
+  const data = readInitialData();
+  let element = createElement(App);
+  if (opts?.layout) {
+    element = createElement(opts.layout, { children: element });
+  }
+  hydrateRoot(
+    container,
+    createElement(ServerDataContext.Provider, { value: data }, element)
+  );
+}
+var _root = null;
+function renderPage(container, layout, Component, data, isInitial) {
+  let element = createElement(Component);
+  if (layout) {
+    element = createElement(layout, { children: element });
   }
-  function subscribe(fn) {
-    listeners.add(fn);
-    return () => {
-      listeners.delete(fn);
-    };
+  const wrapped = createElement(ServerDataContext.Provider, { value: data }, element);
+  if (isInitial) {
+    _root = hydrateRoot(container, wrapped);
+  } else {
+    if (!_root) _root = createRoot(container);
+    _root.render(wrapped);
   }
-  function emit() {
-    listeners.forEach((fn) => fn());
+}
+var _router = null;
+function createBrowserRouter(opts) {
+  if (_router) return _router;
+  const container = opts.container ?? document.getElementById("root");
+  const layout = opts.layout;
+  const routes = Object.entries(opts.routes).map(([pattern, loader]) => {
+    const { regex, paramNames } = compilePattern(pattern);
+    return { pattern, regex, paramNames, loader };
+  });
+  let fallback = null;
+  if (opts.fallback) {
+    const { regex, paramNames } = compilePattern("*");
+    fallback = { pattern: "*", regex, paramNames, loader: opts.fallback };
   }
-  async function navigate(url, { push = true } = {}) {
-    const match = findRoute(url);
-    if (!match) {
-      window.location.href = url;
+  async function renderPath(pathname, isInitial, data) {
+    const matched = matchRoute(pathname, routes);
+    const route = matched?.route ?? fallback;
+    if (!route) {
+      window.location.href = pathname;
       return;
     }
-    const id = state.navId + 1;
-    state = { ...state, navId: id, state: match.route.loader ? "loading" : "idle" };
-    emit();
-    if (match.route.loader) {
-      try {
-        const newData = await match.route.loader(match.params);
-        if (id < state.navId) return;
-        state = { ...state, data: newData, state: "idle" };
-      } catch (err) {
-        console.error("[weifuwu/react] loader failed:", err);
-        state = { ...state, state: "idle" };
-        emit();
-        return;
-      }
-    }
-    if (push) history.pushState({ weifuwu: true }, "", url);
-    state = { ...state, location: url, state: "idle" };
-    emit();
-  }
-  function RouterApp() {
-    const { location, data, state: navState } = useSyncExternalStore(
-      subscribe,
-      getSnapshot
-    );
-    const match = findRoute(location);
-    useEffect(() => {
-      const handler = () => navigate(window.location.pathname, { push: false });
-      window.addEventListener("popstate", handler);
-      return () => window.removeEventListener("popstate", handler);
-    }, []);
-    const ctxNavigate = useCallback(
-      (url) => navigate(url, { push: true }),
-      []
-    );
-    const ctxRevalidate = useCallback(async () => {
-      const currentMatch = findRoute(window.location.pathname);
-      if (currentMatch?.route.loader) {
-        state = { ...state, state: "loading" };
-        emit();
+    try {
+      const mod = await route.loader();
+      const Component = extractComponent(mod);
+      const pageData = data ?? (isInitial ? readInitialData() : await fetchPageData(pathname));
+      renderPage(container, layout, Component, pageData, isInitial);
+    } catch (err) {
+      console.error("[weifuwu] router error:", err);
+      if (fallback && route !== fallback) {
         try {
-          const newData = await currentMatch.route.loader(currentMatch.params);
-          state = { ...state, data: newData, state: "idle" };
-          emit();
-        } catch (err) {
-          console.error("[weifuwu/react] revalidate failed:", err);
-          state = { ...state, state: "idle" };
-          emit();
+          const fallbackMod = await fallback.loader();
+          const FallbackComponent = extractComponent(fallbackMod);
+          renderPage(container, layout, FallbackComponent, { error: String(err) }, false);
+        } catch {
+          container.innerHTML = "<h1>Something went wrong</h1>";
         }
+      } else {
+        container.innerHTML = "<h1>Something went wrong</h1>";
       }
-    }, []);
-    const ctxValue = {
-      params: match?.params ?? {},
-      navigate: ctxNavigate,
-      revalidate: ctxRevalidate,
-      state: navState
-    };
-    const content = match ? createElement2(match.route.component) : createElement2("div", null, "Page not found");
-    return createElement2(
-      RouterContext.Provider,
-      { value: ctxValue },
-      createElement2(
-        ServerDataContext.Provider,
-        { value: data },
-        content
-      )
-    );
+    }
   }
-  function RouterLink(props) {
-    return createElement2(Link, props);
+  async function navigate2(url) {
+    const u = new URL(url, window.location.origin);
+    if (u.origin !== window.location.origin || u.pathname === window.location.pathname) {
+      return;
+    }
+    history.pushState({}, "", url);
+    scrollTo(0, 0);
+    await renderPath(u.pathname, false);
   }
-  return {
-    App: RouterApp,
-    Link: RouterLink,
-    useParams,
-    navigate: (url) => navigate(url, { push: true })
-  };
+  window.addEventListener("popstate", () => {
+    renderPath(window.location.pathname, false);
+  });
+  document.addEventListener("click", (e) => {
+    const target = e.target.closest("a");
+    if (!target) return;
+    const href = target.getAttribute("href");
+    if (!href) return;
+    const u = new URL(href, window.location.origin);
+    if (u.origin !== window.location.origin || target.hasAttribute("download") || target.target === "_blank" || target.getAttribute("rel") === "external") return;
+    e.preventDefault();
+    navigate2(href);
+  });
+  const initialData = readInitialData();
+  renderPath(window.location.pathname, true, initialData);
+  _router = { navigate: navigate2, renderPath };
+  return _router;
 }
-function hydrate(App, opts) {
-  const container = opts?.container ?? document.getElementById("root");
-  if (!container) {
-    throw new Error(
-      "weifuwu/react: hydrate() \u2014 no container element found."
-    );
+function navigate(url) {
+  if (_router) {
+    _router.navigate(url);
+  } else {
+    window.location.href = url;
   }
-  const serverData = readInitialData();
-  hydrateRoot(
-    container,
-    createElement2(
-      ServerDataContext.Provider,
-      { value: serverData },
-      createElement2(App)
-    )
-  );
 }
 export {
-  ErrorBoundary,
-  Form,
-  Link,
-  createClientRouter,
-  defineRoute,
+  createBrowserRouter,
   hydrate,
-  useNavigate,
-  useNavigation,
-  useParams,
-  useRevalidate,
+  navigate,
   useServerData
 };

package/dist/react/compile.d.ts

@@ -0,0 +1,17 @@
+/**
+ * On-the-fly TSX compilation for ctx.render().
+ *
+ * Compiles .tsx files with esbuild, caches by source-content hash.
+ * Externalizes react/react-dom — the framework's own instance is used.
+ * Persisted to disk for fast restarts.
+ */
+import type { ComponentType } from 'react';
+export declare function setReactCacheDir(dir: string): void;
+/**
+ * Load a .tsx/.ts module, compiling on-the-fly with esbuild.
+ * Results are:
+ *  1. Cached in memory by source-content hash
+ *  2. Persisted to disk ({cacheDir}/{sourceHash}.mjs) for instant restarts
+ */
+export declare function loadTsxModule(entryPath: string): Promise<Record<string, unknown>>;
+export declare function loadTsxComponent(entryPath: string): Promise<ComponentType>;

package/dist/react/error-boundary.d.ts

@@ -1,31 +1,30 @@
+import { Component, type ReactNode } from 'react';
+interface ErrorBoundaryProps {
+    children: ReactNode;
+    /** Fallback UI rendered when a child component throws. */
+    fallback?: ReactNode;
+    /** Called with the error (client-side only). */
+    onError?: (error: Error) => void;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
 /**
- * SSR-safe error boundary.
- *
- * Catches React render errors on both server and client:
- * - Server (SSR): renders fallback HTML instead of crashing
- * - Client (hydration): catches errors, shows fallback
+ * Catch render errors in child components.
+ * Works during SSR (renders fallback) and client-side hydration.
  *
- * Usage:
+ * @example
  * ```tsx
- * <ErrorBoundary fallback={<div>Something went wrong</div>}>
- *   <UserProfile />
+ * <ErrorBoundary fallback={<p>Something went wrong</p>}>
+ *   <RiskyComponent />
  * </ErrorBoundary>
  * ```
  */
-import { Component, type ReactNode, type ErrorInfo } from 'react';
-export interface ErrorBoundaryProps {
-    fallback: ReactNode;
-    children: ReactNode;
-    /** Called when an error is caught (both SSR and client). */
-    onError?: (error: Error, info: ErrorInfo) => void;
-}
-interface ErrorBoundaryState {
-    error: Error | null;
-}
 export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
     state: ErrorBoundaryState;
     static getDerivedStateFromError(error: Error): ErrorBoundaryState;
-    componentDidCatch(error: Error, info: ErrorInfo): void;
+    componentDidCatch(error: Error): void;
     render(): ReactNode;
 }
 export {};