clxx 3.0.0 → 3.0.1

package/build/utils/createApp.d.ts

@@ -4,19 +4,33 @@ import { ContainerProps } from "../Container";
 export type RouterMode = "browser" | "hash" | "memory";
 export type AwaitValue<T> = T | Promise<T>;
 export interface CreateAppOption extends Omit<ContainerProps, "children"> {
+    /** 页面加载前触发，可 async；早于 render */
     onBefore?: (pathname: string) => AwaitValue<void>;
+    /** 页面成功渲染后触发，可 async；404 / 错误场景不触发 */
     onAfter?: (pathname: string) => AwaitValue<void>;
+    /** 返回加载中占位节点，在 render 执行期间展示 */
     loading?: (pathname: string) => AwaitValue<React.ReactNode>;
+    /** 根据路径返回页面节点；返回 null/undefined 触发 notFound */
     render?: (pathname: string) => AwaitValue<React.ReactNode>;
+    /** render 返回 null/undefined（404）时调用 */
     notFound?: (pathname: string) => AwaitValue<React.ReactNode>;
+    /** render 抛出错误时调用；未提供时降级到 notFound */
+    onError?: (pathname: string, error: unknown) => AwaitValue<React.ReactNode>;
+    /** 路由模式，默认 browser */
     mode?: RouterMode;
+    /** 路径为 / 或空时使用的默认路径，默认 /index */
     default?: string;
+    /** 路由切换时自动滚动到顶部，移动端推荐开启，默认 true */
+    scrollToTop?: boolean;
+    /** 开启 React.StrictMode，默认 false */
+    strict?: boolean;
+    /** 挂载目标（CSS 选择器或 HTMLElement） */
     target: string | HTMLElement;
 }
 export declare let history: null | History;
 export declare function getHistory(mode?: RouterMode): History;
 /**
- * 创建带路由的APP对象，全局对象，绝大部分情况下只需要调用一次
+ * 创建带路由的 App，全局单例，通常只调用一次。
  * @param option CreateAppOption
  */
-export declare function createApp(option: CreateAppOption): Promise<void>;
+export declare function createApp(option: CreateAppOption): void;

package/build/utils/createApp.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -8,140 +41,140 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.history = void 0;
 exports.getHistory = getHistory;
 exports.createApp = createApp;
 const jsx_runtime_1 = require("@emotion/react/jsx-runtime");
-const react_1 = require("react");
+const react_1 = __importStar(require("react"));
 const client_1 = require("react-dom/client");
 const history_1 = require("history");
 const Container_1 = require("../Container");
-const pick_1 = __importDefault(require("lodash/pick"));
 // 存储历史记录对象
 exports.history = null;
 // 获取历史记录对象
 function getHistory(mode = "browser") {
     if (exports.history === null) {
-        const createMap = {
+        const factories = {
             browser: history_1.createBrowserHistory,
             hash: history_1.createHashHistory,
             memory: history_1.createMemoryHistory,
         };
-        exports.history = createMap[mode]();
+        exports.history = factories[mode]();
     }
     return exports.history;
 }
+const VALID_MODES = new Set(["browser", "hash", "memory"]);
+// 模块级常量，移除路径首尾斜杠；g 标志确保首尾各自替换一次
+const PATH_TRIM_RE = /^\/*|\/*$/g;
 /**
- * 创建带路由的APP对象，全局对象，绝大部分情况下只需要调用一次
+ * 创建带路由的 App，全局单例，通常只调用一次。
  * @param option CreateAppOption
  */
 function createApp(option) {
-    return __awaiter(this, void 0, void 0, function* () {
-        // 设置默认的路由方式
-        if (!option.mode ||
-            ["browser", "hash", "memory"].indexOf(option.mode) === -1) {
-            option.mode = "browser";
-        }
-        // 设置默认路由路径
-        if (!option.default) {
-            option.default = "/index";
-        }
-        // 这里是为了确保历史记录对象在组件渲染之前一定存在
-        exports.history = getHistory(option.mode);
-        // 提取关键数据
-        const containerProps = (0, pick_1.default)(option, [
-            "designWidth",
-            "globalStyle",
-        ]);
-        const { onBefore, onAfter, loading, render, notFound } = option;
-        // 规范化路径：移除首尾斜杠
-        const PATH_TRIM_REGEX = /^\/*|\/*$/g;
-        const normalizePath = (path) => {
-            const normalized = path.replace(PATH_TRIM_REGEX, "");
-            return normalized || option.default.replace(PATH_TRIM_REGEX, "");
-        };
-        /**
-         * 全局APP组件对象
-         * @returns
-         */
-        const App = () => {
-            const [page, setPage] = (0, react_1.useState)(null);
-            /**
-             * 加载并渲染页面
-             */
-            const loadAndRenderPage = (0, react_1.useCallback)((pathname) => __awaiter(this, void 0, void 0, function* () {
-                const normalizedPath = normalizePath(pathname);
-                // 如果有 loading 占位符，先显示
-                if (typeof loading === "function") {
-                    setPage(yield loading(normalizedPath));
+    var _a;
+    // 不修改入参，用局部变量保存规范化后的值
+    const mode = option.mode && VALID_MODES.has(option.mode) ? option.mode : "browser";
+    const defaultPath = ((_a = option.default) !== null && _a !== void 0 ? _a : "/index").replace(PATH_TRIM_RE, "");
+    const scrollToTop = option.scrollToTop !== false;
+    // 确保 history 在组件渲染前已就绪
+    exports.history = getHistory(mode);
+    // 提取 ContainerProps（含 maxWidth，原 pick 遗漏此项）
+    const { designWidth, maxWidth, globalStyle } = option;
+    const containerProps = { designWidth, maxWidth, globalStyle };
+    const { onBefore, onAfter, loading, render, notFound, onError } = option;
+    // 规范化路径：移除首尾斜杠，空路径回退到 defaultPath
+    const normalizePath = (path) => {
+        const normalized = path.replace(PATH_TRIM_RE, "");
+        return normalized || defaultPath;
+    };
+    /**
+     * 全局 App 组件，仅在 createApp 内实例化一次
+     */
+    const App = () => {
+        const [page, setPage] = (0, react_1.useState)(null);
+        // 导航版本号：每次发起新导航自增；过时的异步回调检测到不匹配后静默丢弃，
+        // 防止慢请求在更新的导航完成后覆盖页面（竞态条件）
+        const navIdRef = (0, react_1.useRef)(0);
+        const loadPage = (0, react_1.useCallback)((pathname) => __awaiter(this, void 0, void 0, function* () {
+            const navId = ++navIdRef.current;
+            const path = normalizePath(pathname);
+            // 1. 展示加载占位
+            if (typeof loading === "function") {
+                const loadingNode = yield loading(path);
+                if (navId !== navIdRef.current)
+                    return;
+                setPage(loadingNode);
+            }
+            // 2. 前置钩子
+            yield (onBefore === null || onBefore === void 0 ? void 0 : onBefore(path));
+            if (navId !== navIdRef.current)
+                return;
+            // 3. 渲染页面
+            if (typeof render === "function") {
+                let content;
+                let loadError;
+                let hasError = false;
+                try {
+                    content = yield render(path);
                 }
-                // 页面加载前钩子
-                yield (onBefore === null || onBefore === void 0 ? void 0 : onBefore(normalizedPath));
-                // 加载并显示页面
-                if (typeof render === "function") {
-                    try {
-                        const pageContent = yield render(normalizedPath);
-                        // 如果返回 null/undefined，视为页面未找到
-                        if (pageContent === null || pageContent === undefined) {
-                            if (typeof notFound === "function") {
-                                setPage(yield notFound(normalizedPath));
-                            }
-                            else {
-                                // 默认 404 页面
-                                setPage((0, jsx_runtime_1.jsxs)("div", { children: ["Not Found: ", normalizedPath] }));
-                            }
-                            return;
-                        }
-                        setPage(pageContent);
-                    }
-                    catch (_a) {
-                        // 动态 import 失败等场景
-                        if (typeof notFound === "function") {
-                            setPage(yield notFound(normalizedPath));
-                        }
-                        else {
-                            setPage((0, jsx_runtime_1.jsxs)("div", { children: ["Not Found: ", normalizedPath] }));
-                        }
+                catch (err) {
+                    loadError = err;
+                    hasError = true;
+                }
+                if (navId !== navIdRef.current)
+                    return;
+                if (hasError) {
+                    // render 抛出异常：优先 onError，降级 notFound，再降级内置提示
+                    const errNode = typeof onError === "function" ? (yield onError(path, loadError)) : typeof notFound === "function" ? (yield notFound(path)) : ((0, jsx_runtime_1.jsxs)("div", { children: ["Error: ", path] }));
+                    if (navId !== navIdRef.current)
                         return;
-                    }
+                    setPage(errNode);
+                    return;
                 }
-                // 页面加载后钩子
-                yield (onAfter === null || onAfter === void 0 ? void 0 : onAfter(normalizedPath));
-            }), 
-            // 所有外部变量在闭包创建时已捕获，不会变化
-            // eslint-disable-next-line react-hooks/exhaustive-deps
-            []);
-            /**
-             * 监听路由变化
-             */
-            (0, react_1.useEffect)(() => {
-                // 监听页面变化，一旦变化渲染新页面
-                const unlisten = exports.history.listen(({ location }) => {
-                    loadAndRenderPage(location.pathname);
-                });
-                // 初始化时渲染当前路径对应的页面
-                loadAndRenderPage(exports.history.location.pathname);
-                // 卸载时，取消监听
-                return unlisten;
-            }, [loadAndRenderPage]);
-            return (0, jsx_runtime_1.jsx)(Container_1.Container, Object.assign({}, containerProps, { children: page }));
-        };
-        // 获取挂载对象
-        let mount = null;
-        if (typeof option.target === "string") {
-            mount = document.querySelector(option.target);
-        }
-        else if (option.target instanceof HTMLElement) {
-            mount = option.target;
-        }
-        if (!mount) {
-            throw new Error(`Mount target not found: ${typeof option.target === "string" ? option.target : "invalid element"}`);
-        }
-        const root = (0, client_1.createRoot)(mount);
-        root.render((0, jsx_runtime_1.jsx)(App, {}));
-    });
+                if (content == null) {
+                    // render 返回 null/undefined：404
+                    const notFoundNode = typeof notFound === "function" ? (yield notFound(path)) : ((0, jsx_runtime_1.jsxs)("div", { children: ["Not Found: ", path] }));
+                    if (navId !== navIdRef.current)
+                        return;
+                    setPage(notFoundNode);
+                    return;
+                }
+                // 成功：切换前滚回顶部，再替换页面内容
+                if (scrollToTop)
+                    window.scrollTo(0, 0);
+                setPage(content);
+            }
+            if (navId !== navIdRef.current)
+                return;
+            // 4. 后置钩子（仅成功渲染后调用）
+            yield (onAfter === null || onAfter === void 0 ? void 0 : onAfter(path));
+        }), 
+        // 所有依赖均来自 createApp 闭包，生命周期内不变
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        []);
+        (0, react_1.useEffect)(() => {
+            // 初始渲染当前路径
+            loadPage(exports.history.location.pathname);
+            // 监听后续路由变化，返回 unlisten 作为 cleanup
+            return exports.history.listen(({ location }) => loadPage(location.pathname));
+        }, [loadPage]);
+        return (0, jsx_runtime_1.jsx)(Container_1.Container, Object.assign({}, containerProps, { children: page }));
+    };
+    // 解析挂载目标
+    let mount;
+    if (typeof option.target === "string") {
+        mount = document.querySelector(option.target);
+    }
+    else if (option.target instanceof HTMLElement) {
+        mount = option.target;
+    }
+    else {
+        mount = null;
+    }
+    if (!mount) {
+        throw new Error(`createApp: mount target not found — "${typeof option.target === "string" ? option.target : "[invalid element]"}"`);
+    }
+    const root = (0, client_1.createRoot)(mount);
+    root.render(option.strict ? ((0, jsx_runtime_1.jsx)(react_1.default.StrictMode, { children: (0, jsx_runtime_1.jsx)(App, {}) })) : ((0, jsx_runtime_1.jsx)(App, {})));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clxx",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Basic JS library for mobile devices",
   "main": "./build/index.js",
   "module": "./build/index.js",