@joker.front/core 1.3.76 → 1.3.81

package/types/observer/dep.d.ts

@@ -1,42 +1,46 @@
 import { Watcher } from "./watcher";
 /**
- * 作为观察者和对象代理中间的关系桥
- * 数据变更时：Ob->dep->watcher
- * 设置依赖时：watcher->dep
+ * Dependency manager acting as a bridge between watchers and proxied objects
+ * Data change flow: Ob -> dep -> watcher
+ * Dependency setup flow: watcher -> dep
  */
 export declare class Dep {
     /**
-     * 当前目标的监听者
+     * Current target watcher
      *
-     * 在更改值之前，设置该静态值，使其在值变更时收集相应的依赖关系
-     * 设置完毕后清除该值
+     * Set this static value before changing a value to collect dependencies,
+     * clear it after setup.
      *
-     * 之所以采用静态值，不采用方法的原因：
-     * 可能存在多值变更，或者读取
+     * Using a static value instead of a method allows handling
+     * multiple value changes/reads.
      */
     static target?: Watcher<any>;
     watchers: Map<string | symbol | number, Watcher<any>[]>;
     /**
-     * 设置依赖
-     * @param key
+     * Establish a dependency for a key
+     * @param key Property key to depend on
      */
     depend(key: string | symbol | number): void;
     /**
-     * 添加观察者
-     * @param key
-     * @param watcher
+     * Add a watcher for a key
+     * @param key Property key to watch
+     * @param watcher Watcher instance to add
      */
     addWatcher(key: string | symbol | number, watcher: Watcher<any>): void;
     /**
-     * 删除观察者
-     * @param key
-     * @param watcher
+     * Remove a watcher for a key
+     * @param key Property key to unwatch
+     * @param watcher Watcher instance to remove
      */
     removeWatcher(key: string | symbol | number, watcher: Watcher<any>): void;
     /**
-     * 通知key下面的观察者
-     * @param key
+     * Notify watchers of a key change
+     * @param key Property key that changed
      */
     notify(key: string | symbol | number): void;
 }
+/**
+ * Notify groups of dependencies in a batch
+ * @param list Map of Dep instances to their respective keys
+ */
 export declare function notifyGroupDeps(list: Map<Dep, Array<string | symbol | number>>): void;

package/types/observer/index.d.ts

@@ -1,27 +1,25 @@
 /**
- * 存放劫持对象的Dep的Key
+ * Symbol key for storing the Dep instance of a proxied object
  */
 export declare const OBJECTPROXY_DEPID: unique symbol;
 /**
- * 数据劫持
- * @param data 数据
- * @param clone 是否clone
- * @returns 返回可观察对象
+ * Create a reactive version of an object
+ * @param data Object to observe
+ * @param clone Whether to clone the object before observing
+ * @returns Reactive object
  */
 export declare function observer<T extends Object>(data: T, clone?: boolean): T;
 /**
- * 定义可劫持观察的属性
- *
- * 该方法会污染value深层，如想纯净数据，自行clone
- * @param target
- * @param key
- * @param value
+ * Define a reactive property on an object
+ * @param target Object to define property on
+ * @param key Property key
+ * @param value Property value
  */
 export declare function defineObserverProperty(target: any, key: string | symbol | number, value: any): void;
 declare const JOKER_SHALLOW_OBSERVER_TAG: unique symbol;
 /**
- * 浅劫持监听，不污染数据源，只对根值监听，不对属性监听
- * @returns
+ * Shallow observer that watches only the root value
+ * @returns Shallow observer instance
  */
 export declare class ShallowObserver<T> {
     private data;
@@ -29,21 +27,19 @@ export declare class ShallowObserver<T> {
     private dep;
     constructor(data: T);
     /**
-     * 是否有变更
+     * Flag indicating if the value has changed
      */
     isChanged: boolean;
     get value(): T;
     set value(newVal: T);
 }
 /**
- * 组合回复，针对大量值变更，又不想频繁更新DOM，
- * 可通过该方法实现一个作用域内的统一组合回复
- * @param func 处理方法
- * @returns
+ * Combine multiple dependency updates into a single notification
+ * @param func Function containing changes to combine
  */
 export declare function combinedReply(func: Function): void;
 /**
- * 判断一个值是否是已被数据代理劫持
+ * Check if an object is being observed
  */
 export declare function isObserverData(data: any): boolean;
 export {};

package/types/observer/watcher.d.ts

@@ -1,9 +1,10 @@
 import { Dep } from "./dep";
 export declare const BREAK_WATCH_UPDATE: unique symbol;
 /**
- * 观察者
+ * Observer
  *
- * 负责观察对象，并收集依赖关系，并在值变更时做出回调响应
+ * Manages object observation, collects dependency relationships,
+ * and triggers callback responses when values change
  */
 export declare class Watcher<T extends object = any> {
     private ob;
@@ -14,33 +15,32 @@ export declare class Watcher<T extends object = any> {
     isDestroy: boolean;
     updating: boolean;
     /**
-     * 运行时的关系收集
+     * Runtime relationship collection
      *
-     * 主要作用是：运行时做基本的重复过滤,并收集当前“有效的”Dep关系
-     * 一个Dep 肯定对应一个对象， 对象的key不会出现重复
+     * Main purpose: filter duplicates at runtime and collect "valid" Dep relationships
+     * Each Dep corresponds to an object, and object keys do not repeat
      */
     private runRelations;
     /**
-     * 实际关系
+     * Actual dependency relations
      */
     relations: Map<Dep, Array<string | symbol | number>>;
     /**
-     *
-     * @param ob 数据源
-     * @param expOrFn 表达式（string｜Function）
-     * @param updateCallBack update回调
-     * @param forceCallBack 是否强制回调， 有些值未变更时也会强制回调
+     * @param ob Data source to observe (object or getter function)
+     * @param updateCallBack Callback function for value changes
+     * @param expOrFn Expression string or value extraction function
+     * @param forceCallBack Force callback even if value appears unchanged
      */
     constructor(ob: T | (() => T), updateCallBack: Function, expOrFn?: string | ((obj: T) => any | void) | Function, forceCallBack?: boolean | undefined);
     getValue(): any;
     /**
-     * 添加Dep关系
-     * @param dep
-     * @param key
+     * Add Dep relationship
+     * @param dep Dependency instance
+     * @param key Observed property key
      */
     addDep(dep: Dep, key: string | symbol | number): void;
     /**
-     * 更新值，并对其进行响应
+     * Update observed value and trigger response
      */
     update(): void;
     destroy(): void;

package/types/parser/index.d.ts

@@ -7,56 +7,56 @@ export type ObType = Component & Record<string, any>;
 export declare class ParserTemplate {
     asts: AST.Node[];
     ob: ObType;
-    /** VNode 根 */
+    /** VNode root */
     root: VNode.Root;
-    /** VNode ref索引集 */
+    /** VNode ref index set */
     refs: Record<string, Array<VNode.Node>>;
     sleeped: boolean;
     promiseQueue: Set<Promise<any>>;
     /**
-     * node变更观察者
+     * Node change observer
      */
     nodeWatcherEvents: Record<string, Array<(node: VNode.Node, type: NodeChangeType, propertyKey?: string) => void>>;
-    /** VNode 渲染处理程序 （依赖注入） */
+    /** VNode rendering handler (dependency injection) */
     render: Render.IRender;
     constructor(asts: AST.Node[], ob: ObType, parent?: VNode.Node);
     parser(): void;
     /**
-     * VNode挂载
+     * Mount VNode
      * @param root
      */
     mount(root: any): void;
     /**
-     * 编译AST子集
+     * Compile AST subset
      * @param asts
      * @param parent
      */
     parserNodes(asts: AST.Node[], parent: VNode.Node, ob?: Component & Record<string, any>): void;
     /**
-     * 添加ref
-     * @param refName ref值
-     * @param node VNode节点
+     * Add ref
+     * @param refName ref value
+     * @param node VNode node
      */
     addRef(refKey: string, node: VNode.Node): void;
     /**
-     * 移除Node所在ref
-     * @param node VNode节点
+     * Remove ref where Node is located
+     * @param node VNode node
      */
     removeRef(node: VNode.Node): void;
     /**
-     * 添加节点变更观察者
+     * Add node change observer
      * @param ref
      * @param callBack
      */
     addNodeWatcher(ref: string, callBack: (node: VNode.Node, type: NodeChangeType) => void): void;
     /**
-     * 移除节点变更观察者
+     * Remove node change observer
      * @param ref
      * @param callBack
      */
     removeNodeWatcher(ref: string, callBack: Function): void;
     /**
-     * 响应节点变更，通知观察者
+     * Respond to node changes and notify observers
      * @param ref
      * @param node
      * @param nodeChangeType
@@ -65,10 +65,10 @@ export declare class ParserTemplate {
     sleep(node?: VNode.Node): void;
     private weakup;
     /**
-     * 销毁
+     * Destroy
      */
     destroy(keepalive?: boolean): void;
-    /** 清除所有监听，用于优化嵌套组件销毁时 自定义销毁事件再次触发watcher问题 */
+    /** Clear all watches to optimize nested component destruction when custom destroy events trigger watchers again */
     destroyWathcers(): void;
     reSetAsts(asts: AST.Node[], keepalive?: boolean): void;
     nodeTransition(node: VNode.Node | undefined, mode: "enter" | "leave", name?: string, callBack?: Function, type?: "transition" | "animation"): boolean;

package/types/parser/parser.d.ts

@@ -63,7 +63,7 @@ export declare abstract class IParser<T extends AST.Node, N extends VNode.Node>
      * @param ob 数据源
      * @returns
      */
-    protected runExpress(express: string, ob: any): any;
+    protected runExpress(express: string, ob: any, customLog: () => string | void): any;
     /**
      * 运行表达式方法，并返回运行后的值（带观察者）
      * @param express 表达式 string|function
@@ -72,7 +72,7 @@ export declare abstract class IParser<T extends AST.Node, N extends VNode.Node>
      * @param forceCallBack 是否强制回调
      * @returns
      */
-    protected runExpressWithWatcher(express: string | Function, ob: any, updateCallBack: (newVal: any, oldVal: any, isEqul: boolean, wathcer: Watcher) => void, forceCallBack?: boolean): any;
+    protected runExpressWithWatcher(express: string | Function, ob: any, updateCallBack: (newVal: any, oldVal: any, isEqul: boolean, wathcer: Watcher) => void, forceCallBack?: boolean, customLog?: () => string | void): any;
     /**
      * 添加观察者
      * @param watcher

package/types/parser/render.d.ts

@@ -2,72 +2,72 @@ import { VNode } from "./vnode";
 type TransitionType = "transition" | "animation";
 export declare namespace Render {
     /**
-     * 注入TagId
+     * Inversion of Control tag ID for rendering
      */
     const IRENDERIOCTAGID: unique symbol;
     let ROOT_CONTAINER: string;
     /**
-     * 备注：在渲染时执行appendNode，最终执行一次mount挂载
-     * 不会出现根目录append的场景，因为指令group会优先占位
-     *
-     * append 和 remove方法不会存在 parent的参数，因为一次挂载后
-     * 会存在关系，根据关系直接执行
-     * 上游调用也无需关心parent，特别是在watch周期内
+     * Note: appendNode is executed during rendering, and mount is called once at the end.
+     * There will be no scenario where the root is appended because command groups take precedence.
+     * append and remove methods do not require a parent parameter because after mounting,
+     * the relationship is established, and they are executed directly based on that relationship.
+     * Upstream calls do not need to care about the parent, especially during watch cycles.
      */
     interface IRender {
         /**
-         * 挂载
-         * @param root 挂载根
-         * 不限制root类型，为后面做多端兼容
+         * Mount the rendering to a root container
+         * @param root Root container (element or component)
+         * Root type is not restricted for multi-platform compatibility
          */
         mount(root: any): void;
         /**
-         * 添加节点
-         * @param node NodeInfo
+         * Append a node to the rendering
+         * @param node VNode to append
+         * @param index Optional index for insertion
          */
         appendNode(node: VNode.Node, index?: number): void;
         /**
-         * 更新节点
-         * @param node NodeInfo
-         * @param propertyKey 更新属性名称
+         * Update a node's properties
+         * @param node VNode to update
+         * @param propertyKey Property to update (optional)
          */
         updateNode(node: VNode.Node, propertyKey?: string): void;
         /**
-         * 删除节点
-         * @param {VNode.Node} node
-         * @param {VNode.Node} parent 如果为空则带表root跟节点下集
-         * @param {boolean} reserveOutPut 是否需要保留out产物
+         * Remove a node from the rendering
+         * @param node VNode to remove
+         * @param parent Optional parent node (root if undefined)
+         * @param reserveOutPut Whether to retain the output
          */
         removeNode(node: VNode.Node, reserveOutPut?: boolean): void;
         /**
-         * 销毁，卸载DOM并释放变量
+         * Destroy the renderer, unmount DOM and release resources
          */
         destroy(): void;
         /**
-         * element节点transition enter
+         * Handle element transition enter animation
          */
         elementToEnter(node: VNode.Element, name: string, type?: TransitionType, callBack?: Function): void;
         /**
-         * element节点transition leave
+         * Handle element transition leave animation
          */
         elementToLeave(node: VNode.Element, name: string, type?: TransitionType, callBack?: Function): void;
         /**
-         * 触发组件事件
-         * @param node
-         * @param eventName
-         * @returns false 则代表停止广播
+         * Trigger a component event
+         * @param node Component node
+         * @param eventName Event name
+         * @returns false to stop propagation
          */
         triggerEvent(node: VNode.Component, eventName: string, e: VNode.Event): void | false;
     }
     /**
-     * 默认Render，采用H5-DOM模式进行输出
+     * Default renderer using HTML DOM
      */
     class DomRender implements IRender {
         elements: DocumentFragment;
         constructor();
         mount(root: Element | VNode.Component): void;
         appendNode(node: VNode.Node, index?: number): void;
-        updateNode(node: VNode.Node, propertyKey?: string | undefined): void;
+        updateNode(node: VNode.Node, propertyKey?: string): void;
         removeNode(node: VNode.Node, reserveOutPut?: boolean): void;
         destroy(): void;
         elementToEnter(node: VNode.Element, name: string, type?: TransitionType, callBack?: Function): void;

package/types/parser/vnode.d.ts

@@ -5,20 +5,20 @@ import { SectionType } from "../component";
 import { IParser } from "./parser";
 export declare const JOKER_VNODE_TAG: unique symbol;
 /**
- * 虚拟DOM
+ * Virtual DOM (VNode)
  *
- * 该控件分类区别于AST，分类是按照实际输出类型作为划分
+ * This control classification differs from AST, as it is divided based on the actual output type.
  */
 export declare namespace VNode {
     const PARSERKEY: unique symbol;
     /**
-     * VNode 基类
+     * Base class for VNode
      */
     class Node {
         parent?: Node | undefined;
         [JOKER_VNODE_TAG]: boolean;
         /**
-         * 是否是静态节点，非动态节点。例如：element、text、comment等
+         * Whether it is a static node (non-dynamic), such as element, text, comment, etc.
          */
         static?: boolean;
         output?: any;
@@ -26,43 +26,48 @@ export declare namespace VNode {
         childrens?: Node[];
         ref?: string;
         /**
-         * 当前节点是否睡眠
+         * Whether the current node is in sleep state
          */
         sleep: boolean;
         constructor(parent?: Node | undefined);
         /**
-         * 上一个节点
+         * Previous node
          */
         get prev(): Node | undefined;
         /**
-         * 下一个节点
+         * Next node
          */
         get next(): Node | undefined;
         /**
-         * 匹配第一个符合要求的祖先元素
-         * @param filter 过滤条件 返回true 则返回当前节点
-         * @param shouldBreak 自定义停止条件，若返回true，则不再向上查询
-         * @returns
+         * Find the first ancestor element that matches the filter
+         * @param filter Filter condition: return true to select the current node
+         * @param shouldBreak Custom stop condition: return true to stop searching upwards
+         * @returns The matched ancestor node or undefined
          */
         closest<T extends VNode.Node = VNode.Element & VNode.Component>(filter: (node: VNode.Node) => true | any, shouldBreak?: (node: VNode.Node) => true | any): T | undefined;
         /**
-         * 返回所有匹配的子元素
-         * @param filter 返回true则记录
-         * @param shouldBreak 自定义停止条件，若返回true，则不再向下查询
-         * @param deepSearch 是否深度查询，默认为false，若为true 匹配成功项也会向下查询
-         * @returns
+         * Find all child elements that match the filter
+         * @param filter Return true to include the node
+         * @param shouldBreak Custom stop condition: return true to stop searching downwards
+         * @param deepSearch Whether to search deeply (default: false). If true, continue searching after matching.
+         * @returns Array of matched nodes
          */
         find<T extends VNode.Node = VNode.Element & VNode.Component>(filter: (node: VNode.Node) => true | any, shouldBreak?: (node: VNode.Node) => true | any, deepSearch?: boolean, _childrens?: Array<VNode.Node>, _out?: Array<VNode.Node>): Array<T>;
         /**
-         * 是否包含
-         * @param filter 返回true则记录，返回false则跳过该元素的子集
-         * @returns
+         * Check if any child node matches the filter
+         * @param filter Return true to include the node, return false to skip its children
+         * @returns True if any child matches, false otherwise
          */
         contains(filter: (node: VNode.Node) => true | any, childrens?: Array<VNode.Node>): boolean;
+        /**
+         * Find the first child node that matches the filter
+         * @param filter Return true to select the node
+         * @returns The first matched child node or undefined
+         */
         first<T extends VNode.Node = VNode.Element & VNode.Component>(filter: (node: VNode.Node) => true | any, childrens?: Array<VNode.Node>): T | undefined;
     }
     /**
-     * 根节点
+     * Root node
      */
     class Root<T extends IComponent = IComponent & Record<string, any>> extends Node {
         childrens: Node[];
@@ -70,7 +75,7 @@ export declare namespace VNode {
         constructor();
     }
     /**
-     * 文本类型节点
+     * Text node
      */
     class Text extends Node {
         text: string;
@@ -78,16 +83,17 @@ export declare namespace VNode {
         constructor(text: string, parent: Node);
     }
     /**
-     * Html节点
+     * HTML node
      */
     class Html extends Node {
         html: string;
         notShadow?: boolean | undefined;
         static: boolean;
+        scopedId?: string;
         constructor(html: string, parent: Node, notShadow?: boolean | undefined);
     }
     /**
-     * 注释节点
+     * Comment node
      */
     class Comment extends Node {
         text: string;
@@ -95,7 +101,7 @@ export declare namespace VNode {
         constructor(text: string, parent: Node);
     }
     /**
-     * Element节点
+     * Element node
      */
     class Element extends Node {
         tagName: string;
@@ -107,56 +113,56 @@ export declare namespace VNode {
             callBack: EventCallBack;
         }]>;
         /**
-         * 协助事件存储，用于存储辅助事件，例如outside等事件
+         * Auxiliary event storage for storing assist events like 'outside'
          */
         _assistEventCache?: Array<[string, (e: any) => void]>;
         constructor(tagName: string, parent: Node);
     }
     type Event<T = undefined, N extends VNode.Node = VNode.Element | VNode.Component | VNode.Root> = {
         /**
-         * 事件名称
+         * Event name
          */
         eventName: string;
         /**
-         * 原生event，对应运行平台
+         * Native event corresponding to the runtime platform
          */
         event?: any;
-        /** 触发事件目标元素 */
+        /** Target element that triggered the event */
         target?: N;
-        /** 阻止默认事件 */
+        /** Prevent default event behavior */
         preventDefault(): void;
-        /** 阻止事件传播 */
+        /** Stop event propagation */
         stopPropagation(): void;
-        /** 参数 */
+        /** Event parameters */
         data: T;
     };
     type EventCallBack<T = any> = (e: Event<T>) => void;
     /**
-     * 组件节点
+     * Component node
      */
     class Component<T extends ComponentClass = ComponentClass<any> & Record<string, any>> extends Node {
-        /** 组件名（template标签名） */
+        /** Component name (template tag name) */
         name?: string;
-        /** 组件实例 */
+        /** Component instance */
         component: T;
-        /** 事件 */
+        /** Events */
         events: Array<[string, {
             modifiers?: string[];
             callBack: EventCallBack;
         }]>;
-        /** 参数 */
+        /** Properties values */
         propValues: Record<string, any>;
-        /** 是否保持存活 */
+        /** Whether to keep the component alive */
         keepalive?: boolean;
         /**
-         * 当前组件第一个element vnode
+         * First element VNode of the current component
          */
         get firstElement(): Element | undefined;
-        /** 获取根element 节点 包含VNode.Html */
+        /** Get root element nodes (including VNode.Html) */
         get rootElements(): (Element | Html)[];
     }
     /**
-     * 条件节点
+     * Condition node
      */
     class Condition extends Node {
         cmdName: AST.IfCommand["kind"];
@@ -166,13 +172,13 @@ export declare namespace VNode {
         constructor(cmdName: AST.IfCommand["kind"], parent: Node);
     }
     /**
-     * 列表节点,内部包含多组列表项
+     * List node, containing multiple list items
      */
     class List extends Node {
         childrens: ListItem[];
     }
     /**
-     * 循环列表项
+     * List item for looping
      */
     class ListItem extends Node {
         ob: ObType;
@@ -180,7 +186,7 @@ export declare namespace VNode {
         constructor(ob: ObType, parent: VNode.Node);
     }
     /**
-     * 插槽节点
+     * Render section node (slot)
      */
     class RenderSection extends Node {
         id: string;

package/types/props.d.ts

@@ -6,4 +6,11 @@ export type PropTypeFullModel = {
     validate?: (val: any) => Boolean;
 };
 export type PropType = PropValueType | Array<PropValueType> | PropTypeFullModel;
+/**
+ * Get and validate a prop value based on its definition
+ * @param propsData Source props data
+ * @param key Prop key
+ * @param propsType Prop type definition
+ * @returns Validated and processed prop value
+ */
 export declare function getPropValue(propsData: Readonly<Record<string | symbol, any>>, key: string | symbol, propsType?: Record<string | symbol, any>): any;

package/types/utils/DI.d.ts

@@ -1,15 +1,26 @@
 type Constructor<T = any> = new (...args: any[]) => T;
 /**
- * IOC依赖注入容器
+ * IOC Dependency Injection Container
  *
- * IOC依赖注入适用场景：
- * 内部已规划的API、Interface，需要在外部对其进行逻辑注入的场景
- * 区分于plugin，plugin是根据整体声明周期做的切面注入
+ * Applicable scenarios for IOC dependency injection:
+ * APIs and Interfaces that are internally planned but need external logic injection.
+ * Different from plugins, which are aspect injections based on the overall lifecycle.
  */
 export declare namespace IContainer {
+    /**
+     * Bind a tag identifier to a constructor
+     * @param tagId Unique identifier for the binding
+     * @returns Object with 'to' method to specify the target constructor
+     */
     function bind<T>(tagId: symbol | string): {
         to: (target: Constructor<T>) => void;
     };
+    /**
+     * Resolve a dependency by tag identifier
+     * @param tagId Unique identifier for the binding
+     * @param params Parameters to pass to the constructor
+     * @returns New instance of the bound constructor, or undefined if not found
+     */
     function get<T>(tagId: symbol | string, ...params: any[]): T | undefined;
 }
 export {};