@wiajs/core 1.2.2 → 2.1.0

package/.oxfmtrc.jsonc

@@ -0,0 +1,47 @@
+{
+  // https://unpkg.com/oxfmt@0.35.0/configuration_schema.json
+  "$schema": "../../node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 120,
+  "semi": false, // 强制去除分号，保持 JS/TS 的现代感与简洁
+  "singleQuote": true, // 推荐使用单引号，视觉干扰比双引号少
+  "arrowParens": "avoid",
+  "bracketSameLine": true,
+  "bracketSpacing": false, // 去除对象字面量中的空格，保持紧凑
+  "jsxBracketSameLine": true,
+  "jsxSingleQuote": true,
+  "trailingComma": "es5", // 去除尾逗号，保持代码简洁
+  // 导入排序：极度紧凑
+  "sortImports": {
+    "newlinesBetween": false,      // 核心：去除不同组导入之间的空行，压缩垂直空间
+    "groups": ["builtin", "external", "internal", "parent", "sibling", "index"],
+    "caseSensitive": false,
+  },
+  // Package.json 排序：工程标准化
+  "sortPackageJson": {
+    "sortScripts": true, // 必须：脚本有序化，方便维护
+  },
+  // 3. Tailwind 类名排序：样式一致性
+  "sortTailwindcss": {
+    // 1. 覆盖所有类名可能出现的逻辑场景
+    "functions": ["clsx", "cn", "cva", "twMerge", "tw"],
+    // 2. 适配所有可能的属性（如某些库使用的 tw 属性）
+    "attributes": ["class", "className", "tw"],
+    // 3. 保持紧凑：自动去重，自动压缩空格
+    "preserveDuplicates": false,
+    "preserveWhitespace": false,
+    // 4. 如果是 Tailwind v4，指向你的 CSS 入口
+    // "stylesheet": "src/index.css"
+  },
+  "ignorePatterns": [
+    "apps/",
+    "assets/",
+    "dist/",
+    "docs/_layouts/",
+    "node_modules/",
+    "patches/",
+    "pnpm-lock.yaml/",
+    "Swabble/",
+    "vendor/",
+    "**/*.min.js",
+  ],
+}

package/.oxlintrc.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "../../node_modules/oxlint/configuration_schema.json",
+  "plugins": ["unicorn", "typescript", "oxc", "react"],
+  "env": {
+    "browser": true,
+    "node": true,
+    "es2022": true
+  },
+  "categories": {
+    "correctness": "error", // 代码正确性相关的规则，必须修复
+    "perf": "error", // 性能相关的规则，建议修复
+    "suspicious": "error", // 可能存在问题的代码模式，建议修复
+    "pedantic": "off", // 推荐设为 off：避免因为琐碎的规则干扰开发流程。
+    "style": "off", // 代码风格相关的规则，保持一致性，建议修复
+    "restriction": "off" // 可能限制开发者的规则，视项目需求开启
+  },
+  "extends": ["recommended"],
+  "rules": {
+    // --- 代码风格 ---
+    "curly": ["error", "multi-or-nest"], // 紧凑风格：单行不加大括号，多行嵌套才加
+    "eqeqeq": ["error", "always", {"null": "ignore"}], // 强制全等，但允许对 null 进行模糊匹配
+    "no-var": "error",
+    "prefer-const": "error",
+    "no-debugger": "off", // 开发阶段允许 debugger
+
+    /* --- 兼容旧版项目中的特殊处理 --- */
+    "no-console": "off", // 开发阶段允许 console
+    "eslint-plugin-unicorn/prefer-array-find": "off", // .filter()[0]
+    "eslint/no-shadow": "off", // 局部变量覆盖外层变量名
+    "eslint/no-await-in-loop": "off", // 循环中的 await
+    "eslint/no-new": "off",
+    "eslint/no-unmodified-loop-condition": "error", // 防止死循环
+    "typescript/no-unnecessary-boolean-literal-compare": "off", // 禁止不必要的布尔比较
+    "typescript/no-unsafe-type-assertion": "off", // as 给 TS 留一点“逃生舱”
+    "typescript/no-extraneous-class": "off", // 只包含静态成员的类
+    "typescript/no-explicit-any": "warn", // 禁止使用 any 类型
+
+    /* --- 性能与现代语法优化 (Unicorn & OXC) --- */
+    "oxc/no-accumulating-spread": "off", // 允许在迭代中使用解构（平衡性能与可读性）
+    "oxc/no-async-endpoint-handlers": "warn", // 异步后端处理函数中可能的未捕获错误
+    "oxc/no-map-spread": "off", // .map() 回调中直接返回解构的对象
+    "unicorn/consistent-function-scoping": "off", // 函数提升到最外层
+    "unicorn/prefer-module": "off", // 强制使用 ES 模块
+    "unicorn/require-post-message-target-origin": "warn", // 基本的安全防范
+    "unicorn/prefer-array-to-sorted": "off", // 数组排序时直接调用 .sort()，不需要先创建新数组
+    "unicorn/no-array-sort": "off", // 允许使用 .sort()，性能更好
+    "object-shorthand": ["warn", "always"], // 强制对象简写，保持代码紧凑
+    "arrow-body-style": ["warn", "as-needed"], // 只有必要时才写 return，缩短函数长度
+
+    /* --- React 适配 --- */
+    "react/jsx-no-undef": "error",
+    "react/react-in-jsx-scope": "off", // 现代 React (Next.js/Bun) 不需要 import React
+    "react/jsx-key": "error",
+
+    /* --- 变量管理 --- */
+    "no-unused-vars": [
+      "warn",
+      {
+        "vars": "local",
+        "args": "after-used",
+        "argsIgnorePattern": "^_", // 允许下划线开头的未用参数
+        "ignoreRestSiblings": true
+      }
+    ]
+  },
+  // 排除检查的文件/目录
+  "ignorePatterns": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/vendor/**",
+    "**/assets/**",
+    "**/*.min.js",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "package-lock.json"
+  ]
+}

package/dist/core.cjs

@@ -1,6 +1,6 @@
 /*!
-  * wia core v1.2.1
-  * (c) 2015-2025 Sibyl Yu and contributors
+  * wia core v2.1.0
+  * (c) 2015-2026 Sibyl Yu and contributors
   * Released under the MIT License.
   */
 'use strict';
@@ -2075,6 +2075,194 @@ class Event {
   }
 }
 
+/**
+ * @typedef {Object} LogOptions
+ * @property {string} m - 模块名称
+ */
+
+/**
+ * @typedef {((...args: any[]) => void) & { debug: (...args: any[])=>void, info: (...args: any[])=>void, warn: (...args: any[])=>void, error: (...args: any[])=>void, err: (...args: any[])=>void }} ScopedLogger
+ */
+
+/**
+ * @typedef {((...args: any[]) => void) & { log: (...args: any[])=>void, debug: (...args: any[])=>void, info: (...args: any[])=>void, warn: (...args: any[])=>void, error: (...args: any[])=>void, err: (...args: any[])=>void, fn: (name: string) => ScopedLogger }} LoggerFn
+ */
+
+// 1. 安全地获取开发环境状态（兼容打包工具、浏览器和 Node.js）
+// 如果 Rspack 注入了 __DEV__，就用注入的值；如果是在 Node.js 下，就回退读取 "production"
+const isDev = typeof __DEV__ !== 'undefined' ? __DEV__ : "production" !== 'production';
+
+/**
+ * 前端日志输出，封装 console 日志，简化代码
+ * 自动识别并重排提示符与对象，保持前后端一致性
+ */
+class Log {
+  /** @type {string} 模块名称 */
+  m = ''
+
+  /** @type {string} 函数名称 */
+  fnName = ''
+
+  /**
+   * @param {string} [m=''] 模块
+   * @param {string} [fnName=''] 函数
+   */
+  constructor(m = '', fnName = '') {
+    this.m = m;
+    this.fnName = fnName;
+  }
+
+  /**
+   * 格式化参数：提取提示符，构建前缀，将对象后置
+   * 格式要求：[模块名称:函数名称]提示符: {对象}
+   * @param {any[]} args
+   * @returns {any[]} 返回处理后传递给 console 的参数数组
+   */
+  formatArgs(args) {
+    let R = '';
+    const _ = this;
+    try {
+      const msgs = [];
+      const objs = [];
+
+      // 1. 将字符串(提示符)和非字符串(对象/数值等)分开
+      for (const arg of args) {
+        if (typeof arg === 'string') msgs.push(arg);
+        else objs.push(arg);
+      }
+
+      let prefix = '';
+
+      // 2. 添加模块与函数前缀
+      if (_.m) prefix = `[${_.m}${_.fnName ? ':' + _.fnName : ''}]`;
+      else if (_.fnName) prefix = `[:${_.fnName}]`;
+
+      // 3. 拼接提示符
+      const msg = msgs.join(' ');
+      if (msg) prefix += msg;
+
+      R = [];
+      if (prefix) R.push(prefix);
+      R.push(...objs);
+    } catch (e) {
+      console.error(`formatArgs exp:${e.message}`);
+    }
+
+    return R
+  }
+
+  /** @param {...any} args */
+  log(...args) {
+    // 生产环境安全剔除 (需 Rspack DefinePlugin 注入 __DEV__)
+    if (isDev) console.log(...this.formatArgs(args));
+  }
+
+  /** @param {...any} args */
+  debug(...args) {
+    if (isDev) console.debug(...this.formatArgs(args));
+  }
+
+  /** @param {...any} args */
+  info(...args) {
+    if (isDev) console.info(...this.formatArgs(args));
+  }
+
+  /** @param {...any} args */
+  warn(...args) {
+    if (isDev) console.warn(...this.formatArgs(args));
+  }
+
+  /** @param {...any} args */
+  trace(...args) {
+    if (isDev) console.trace(...this.formatArgs(args));
+  }
+
+  /** * error 会在生产环境保留
+   * @param {...any} args
+   */
+  error(...args) {
+    console.error(...this.formatArgs(args));
+  }
+
+  /**
+   * 用于 catch(e) log.err(e) 或 log.err("提示符", e) 或 log.err(e, "提示符")
+   * 自动对齐前缀 [模块:函数] 提示符: Error对象，并保留堆栈
+   * @param {...any} args
+   */
+  err(...args) {
+    // 生产环境安全输出，不会被 Tree-shaking 摇掉
+    // formatArgs 会自动分离字符串与 Error 对象，并补全冒号
+    const formattedArgs = this.formatArgs(args);
+
+    // 原生打印，保持 stack trace 可点击跳转！
+    console.error(...formattedArgs);
+  }
+
+  /**
+   * 派生函数级别日志实例 (完美对齐后端 log.fn)
+   * @param {string} name 函数名称
+   * @returns {ScopedLogger}
+   */
+  fn(name) {
+    const scopedLog = new Log(this.m, name);
+
+    /** @type {any} */
+    const R = (...args) => scopedLog.log(...args);
+
+    R.debug = scopedLog.debug.bind(scopedLog);
+    R.info = scopedLog.info.bind(scopedLog);
+    R.warn = scopedLog.warn.bind(scopedLog);
+    R.trace = scopedLog.trace.bind(scopedLog);
+    R.error = scopedLog.error.bind(scopedLog);
+    R.err = scopedLog.err.bind(scopedLog);
+
+    return /** @type {ScopedLogger} */ (R)
+  }
+}
+
+// 实例化唯一的全局日志单例
+const _log = new Log();
+
+/**
+ * 标准日志输出或构建模块日志类实例，用于模块中带[m:xxx]标记日志输出
+ * 传入 { m: '模块名' } 构建实例，或直接传入参数输出全局日志
+ * @param {...any} args - params
+ * returns {*}
+ */
+function log(...args) {
+  const last = args.at(-1);
+
+  // 1. 如果只有一个参数且带 m 属性，说明是构造 Logger 实例 (如: const log = Log({m: 'User'}))
+  if (args.length === 1 && typeof last === 'object' && last !== null && 'm' in last) {
+    const lg = new Log(last.m);
+
+    /** @type {any} */
+    const R = (...args2) => lg.log(...args2);
+
+    R.log = lg.log.bind(lg);
+    R.debug = lg.debug.bind(lg);
+    R.info = lg.info.bind(lg);
+    R.warn = lg.warn.bind(lg);
+    R.trace = lg.trace.bind(lg);
+    R.error = lg.error.bind(lg);
+    R.err = lg.err.bind(lg);
+    R.fn = lg.fn.bind(lg); // 暴露派生函数作用域方法
+
+    return /** @type {LoggerFn} */ (R)
+  }
+
+  // 2. 否则作为全局普通日志直接输出
+  _log.log(...args);
+}
+
+// 绑定全局快捷方法，方便直接调用 log.err(e) 等
+log.err = _log.err.bind(_log);
+log.error = _log.error.bind(_log);
+log.warn = _log.warn.bind(_log);
+log.info = _log.info.bind(_log);
+log.debug = _log.debug.bind(_log);
+log.trace = _log.trace.bind(_log);
+
 /**
  * 所有页面从该类继承，并必须实现 load 事件！
  * 事件
@@ -2103,7 +2291,6 @@ class Event {
  *
  */
 
-
 class Page extends Event {
   constructor(app, name, title, style) {
     super(null, [app]);
@@ -2145,16 +2332,16 @@ class Page extends Event {
    * 在已经加载就绪的视图上操作
    * @param {*} view 页面层的 Dom 对象，已经使用`$(#page-name)`，做了处理
    * @param {*} param go 函数的参数，或 网址中 url 中的参数
-   * @param {*} back 是否为回退，A->B, B->A，这种操作属于回退
+   * @param {*} lastPath 前路由的路径，go 函数的参数，或 网址中 url 中的参数
    */
-  ready(view, param, back) {
+  ready(view, param, lastPath) {
     // $.assign(this, {page, param, back});
     // $.assign(this.data, param);
     // 隐藏所有模板
     this.init();
-    this.emit('local::ready', view, param, back);
+    this.emit('local::ready', view, param, lastPath);
     // 向上触发跨页面事件，存在安全问题
-    this.emit('pageReady', this, view, param, back);
+    this.emit('pageReady', this, view, param, lastPath);
   }
 
   /**
@@ -2168,29 +2355,29 @@ class Page extends Event {
 
   // 显示已加载的页面
   // view：页面Dom层，param：参数
-  show(view, param) {
+  show(view, param, lastPath) {
     // 隐藏所有模板
     view.qus('[name$=-tp]').hide();
     // 防止空链接，刷新页面
     view.qus('a[href=""]').attr('href', 'javascript:;');
     // this.init();
     if (this.reset) this.reset();
-    this.emit('local::show', view, param);
+    this.emit('local::show', view, param, lastPath);
     // 向上触发跨页面事件，存在安全问题
-    this.emit('pageShow', this, view, param);
+    this.emit('pageShow', this, view, param, lastPath);
   }
 
   // 回退显示已加载的页面
   // view：页面Dom层，param：参数
-  back(view, param) {
+  back(view, param, lastPath) {
     // 隐藏所有模板
     view.qus('[name$=-tp]').hide();
     // 防止空链接，刷新页面
     view.qus('a[href=""]').attr('href', 'javascript:;');
 
-    this.emit('local::back', view, param);
+    this.emit('local::back', view, param, lastPath);
     // 向上触发跨页面事件，存在安全问题
-    this.emit('pageBack', this, view, param);
+    this.emit('pageBack', this, view, param, lastPath);
   }
 
   change(view, param, lastParam) {
@@ -2212,6 +2399,77 @@ class Page extends Event {
   }
 }
 
+/**
+ * 页面工厂函数
+ * 自动处理类的继承、日志注入、生命周期事件绑定
+ * @param {Object} def - 页面默认配置
+ * @param {Object} hooks - 业务钩子函数集合 { init, bind, show... }
+ */
+function page(def, hooks = {}) {
+  // 自动根据配置创建当前页面的专属日志实例
+  const _log = log({m: `${def.name}`});
+
+  return class extends Page {
+    constructor(opts = {}) {
+      const opt = {...def, ...opts};
+      super(opt.app, opt.name, opt.title);
+      this.opt = opt;
+
+      // ✨ 魔法 1：利用 page.js 内置的 Event 机制，全自动挂载无侵入日志！
+      this.on('local::load', param => _log({param}, 'load'));
+      this.on('local::ready', (v, param, lastPath) => _log({v, param, lastPath, id: this.id}, 'ready'));
+      this.on('local::show', (v, param, lastPath) => _log({v, param, lastPath, id: this.id}, 'show'));
+      this.on('local::change', (v, param, lastParam) => _log({v, param, lastParam}, 'change'));
+      this.on('local::back', (v, param, lastPath) => _log({v, param, lastPath, id: this.id}, 'back'));
+      this.on('local::hide', v => _log({v, id: this.id}, 'hide'));
+      this.on('local::unload', v => _log({v, id: this.id}, 'unload'));
+    }
+
+    // 映射其他生命周期到业务 hooks
+    load(param) {
+      super.load(param);
+      if (hooks.load) hooks.load({param, pg: this, log: _log});
+    }
+
+    // ✨ 魔法 2：统一调度业务代码的 init 和 bind，提供优雅的上下文
+    async ready(v, param, lastPath) {
+      super.ready(v, param, lastPath);
+
+      // 组装上下文对象供业务使用
+      const ctx = {v, pg: this, param, lastPath, log: _log};
+
+      // 自动按顺序执行业务层的初始化和事件绑定
+      if (hooks.init) await hooks.init(ctx);
+      if (hooks.bind) hooks.bind(ctx);
+    }
+
+    show(v, param, lastPath) {
+      super.show(v, param, lastPath);
+      if (hooks.show) hooks.show({v, pg: this, param, lastPath, log: _log});
+    }
+
+    change(v, param, lastParam) {
+      super.change(v, param, lastParam);
+      if (hooks.change) hooks.change({v, pg: this, param, lastParam, log: _log});
+    }
+
+    back(v, param, lastPath) {
+      super.back(v, param, lastPath);
+      if (hooks.back) hooks.back({v, pg: this, param, lastPath, log: _log});
+    }
+
+    hide(v, param) {
+      super.hide(v, param);
+      if (hooks.hide) hooks.hide({v, pg: this, param, log: _log});
+    }
+
+    unload(v) {
+      super.unload(v);
+      if (hooks.unload) hooks.unload({v, pg: this, log: _log});
+    }
+  }
+}
+
 /**
  * Wia app、router等继承类，通过模块化扩展类功能
  * 使用 use 装载，注解可能完成类似功能
@@ -4420,3 +4678,4 @@ exports.Support = Support;
 exports.Utils = Utils;
 exports.jsx = jsx;
 exports.loadModule = loadModule;
+exports.page = page;