nv-basic-bw 1.0.15 → 1.0.16

package/README/dnld.d.ts

@@ -0,0 +1,63 @@
+/**
+ * UI/UX 测试工具库 - 下载与批量拍照模块
+ * ---- 给元素拍摄的照片数量巨大 需要和后端的 照片比对 服务配合工作
+ *
+ */
+
+/** * 下载任务的结果接收器 
+ */
+export interface DownloadReceiver {
+    succs: string[];
+    /** 错误列表：[url, 错误堆栈/原因] */
+    fails: [string, string][];
+}
+
+/**
+ * 将 Blob 数据保存到指定文件目录
+ * @param blob 图像或文件数据
+ * @param name 文件名
+ * @param dir 目录句柄（FileSystemDirectoryHandle），若不传则触发弹窗让用户选择
+ * @returns [是否成功, 错误原因/堆栈]
+ */
+export function save_blob(
+    blob: Blob,
+    name: string,
+    dir?: FileSystemDirectoryHandle
+): Promise<[boolean, string | null]>;
+
+/**
+ * 下载指定 URL 并保存到本地目录
+ * @param url 下载地址，支持 string 或 [url, ext_name]
+ * @param dirHandle 目录句柄
+ * @param name 自定义文件名，若不传则自动生成前缀名
+ * @param recv 结果接收器
+ */
+export function fetch_save(
+    url: string | [string, string],
+    dirHandle?: FileSystemDirectoryHandle,
+    name?: string,
+    recv?: DownloadReceiver
+): Promise<void>;
+
+/**
+ * 批量下载页面中类似图片的资源（通过 CSS、IMG 标签等搜集）
+ * @param fltr 元素过滤器
+ */
+export function dnld_img_like(
+    fltr?: (el: HTMLElement) => boolean
+): Promise<DownloadReceiver>;
+
+/**
+ * 【UI/UX 测试核心】批量扫描元素并拍摄像素级照片
+ * 自动滚动并捕获指定范围内的元素，静默保存到指定文件夹
+ * * @param rt 扫描的根节点，默认为 document.body
+ * @param min_width 宽度阈值，小于此宽度的元素将被忽略
+ * @param min_height 高度阈值，小于此高度的元素将被忽略
+ * @param fltr 自定义过滤函数
+ */
+export function take_photo_for_all_eles(
+    rt?: Node | HTMLElement,
+    min_width?: number,
+    min_height?: number,
+    fltr?: (el: HTMLElement) => boolean
+): Promise<void>;

package/README/ele.d.ts

@@ -0,0 +1,71 @@
+/**
+ * ⚠️ 性能警告 (PERFORMANCE WARNING):
+ * 本模块使用深度遍历 (DFS) 算法，执行效率较低。
+ * 仅设计用于 UI/UX 自动化测试、爬虫脚本或低频交互场景。
+ * 严禁在高性能生产环境、高频渲染循环或大规模 DOM 树中作为常规选择器使用。
+ */
+
+/** DOM 树摘要信息接口 */
+export interface DOMSummary {
+    tags: string[];
+    keys: string[];
+    vals: string[];
+    txts: string[];
+    cmts: string[];
+}
+
+/** 筛选器函数类型，支持同步和异步 */
+export type ElementFilterFn = (el: Node | HTMLElement, depth: number) => boolean | Promise<boolean>;
+
+/**
+ * 路径精确匹配获取（层级子节点）
+ * @param root 根节点
+ * @param tags 标签名数组，如 ['div', 'span', 'a']
+ */
+export function plget(root: HTMLElement, tags: string[]): HTMLElement[];
+
+/**
+ * 路径模糊匹配获取（深度后代节点）
+ * @param root 根节点
+ * @param tags 标签名数组序列
+ */
+export function plinget(root: HTMLElement | Document, tags: string[]): HTMLElement[];
+
+/**
+ * 核心筛选函数：根据特殊 DSL 语法或正则表达式筛选元素
+ * * 语法糖说明:
+ * - `#id`: 匹配 ID
+ * - `.class`: 匹配 Class
+ * - `!tag`: 匹配可点击的元素（排除 meta/style 等）
+ * - `@match`: 匹配属性值中包含 URL 且 URL 包含 match 的元素
+ * - `-data`: 匹配 data- 属性名包含 data 的值集合 (返回对象)
+ * - `?:attr`: 匹配包含指定属性名的元素
+ * - `:?val`: 匹配属性值包含指定字符串的元素
+ * - `*`: 返回 DOM 摘要 (summary)
+ * - `&match`: 匹配并返回绝对路径 URL 列表
+ * - `//comment`: 匹配注释内容
+ * - `tag/tag`: 路径筛选
+ */
+export function filter(
+    rt: HTMLElement | Document,
+    o: string | RegExp | ElementFilterFn,
+    is_leaf?: (el: Node) => boolean
+): Promise<HTMLElement[] | DOMSummary | Record<string, any[]> | string[]>;
+
+/**
+ * 基于正则表达式匹配标签名或属性名的元素
+ */
+export function filter_on_tag_or_attr_key_with_rgx(
+    rt: HTMLElement | Document,
+    o: RegExp,
+    is_leaf?: (el: Node) => boolean
+): Promise<HTMLElement[]>;
+
+/**
+ * 增强型 document 代理对象 ($)
+ * 支持通过属性直接调用 DSL 筛选，例如：
+ * await $.div;          // 获取所有 div
+ * await $['.btn-save']; // 获取所有 class 包含 btn-save 的元素
+ * await $['#main'];     // 获取 ID 为 main 的元素
+ */
+export const $: any;

package/README/ison.d.ts

@@ -0,0 +1,77 @@
+/**
+ * nvison (ison) - 极致宽松的 JSON-like 解析器
+ * * 🛠 核心定位：
+ * 1. 专门处理“非标准”、“格式错误”的类 JSON 文本。
+ * 2. 支持注释、引用、大数、多种进制及自定义分隔符。
+ * 3. 容错率极高，会自动丢弃无法解析的残缺部分，而非抛出异常。
+ * * ⚠️ 性能提示：
+ * 逐字符解析，速度慢。适合 <1M 的配置文件，不建议处理超大规模数据。
+ * UI 测试脚本 极其重要，因为测试脚本往往是由非开发人员维护的，手误率极高。 
+*/
+
+/** * 解析配置选项 
+ */
+export interface IsonOptions {
+    /** 启用哈希(#)定义与引用(&)功能。性能开销较大，但在处理复杂拓扑配置时非常有用。 */
+    enable_ref?: boolean;
+    /** 字符编码，默认 'utf8' */
+    encoding?: string;
+}
+
+/** * 后序遍历(Post-DFS)产生的项 
+ * [键名, 对应的值] - 若为数组元素，键名通常为 Symbol(empty)
+ */
+export type IsonEntry = [string | symbol, any];
+
+/**
+ * 将 Ison 字符串直接解析为 JS 对象
+ * @example ison.parse_from_str("[1 2 3, abc:def]") -> [1, 2, 3, {abc: 'def'}]
+ */
+export function parse_from_str(s: string, opt?: IsonOptions): any;
+
+/**
+ * 从文件读取并解析
+ */
+export function parse_from_file(fn: string, opt?: IsonOptions): any;
+
+/**
+ * 以后序 DFS 顺序生成数据流（同步）
+ * 适合在内存中逐步构建或过滤大型配置项
+ */
+export function* gen_from_str(s: string, opt?: IsonOptions): Generator<IsonEntry>;
+export function* gen_from_file(fn: string, opt?: IsonOptions): Generator<IsonEntry>;
+
+/**
+ * 异步生成器
+ * 配合 V15+ 的流式特性，支持异步处理
+ */
+export function agen_from_file(fn: string, opt?: IsonOptions): AsyncGenerator<IsonEntry>;
+
+/** * 全局配置对象 - 允许运行时动态扩展 DSL 语法
+ * @example 
+ * ison.CFG.commas.add("。"); // 支持中文句号作为分隔符
+ * ison.CFG.array_blks.add("【", "】"); // 支持中文方括号
+ */
+export const CFG: {
+    readonly fixed: {
+        hash: '#';
+        ref: '&';
+        tmpl_quote: '`';
+        slash: '/';
+        asterisk: '*';
+        line_comment: '//';
+        blk_comments: [string, string];
+    };
+    obj_blks: Map<string, string>;
+    array_blks: Map<string, string>;
+    quotes: Set<string>;
+    commas: Set<string>;
+    colons: Set<string>;
+    readonly reserved: string[];
+};
+
+/** 内部使用的占位符，用于标识无 key 的数组项 */
+export const EMPTY: unique symbol;
+
+/** 默认配置字典 */
+export const OPT_DICT: IsonOptions;

package/README/nd.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 节点遍历工具库类型定义
+ * ---- its SLOW, just for test massive ui-elements generated by AI
+ * ---- for production , should use c++ version graph-tree, do NOT use DOM
+ *
+ */
+
+/** 遍历回调函数定义：返回 true 可终止遍历 */
+export type VisitorCallback = (node: Node, rel_depth: number) => void | boolean | Promise<void | boolean>;
+
+/** 叶子节点判定函数定义 */
+export type LeafPredicate = (node: Node) => boolean;
+
+/**
+ * 获取节点的绝对深度
+ */
+export function get_depth(node: Node | null): number;
+
+/**
+ * 获取指定层级的祖先节点
+ * @param node 当前节点
+ * @param which 向上查找的层数 (which > 0)
+ */
+export function get_ance(node: Node, which: number): Node | null;
+
+/**
+ * 获取根节点 (最顶层的父节点)
+ */
+export function get_rt(node: Node): Node;
+
+/**
+ * 默认的叶子节点判定逻辑 (无子节点即为叶子)
+ */
+export const is_topo_leaf: LeafPredicate;
+
+/**
+ * 获取最右下方的后代节点
+ * @returns [最右节点, 相对深度]
+ */
+export function get_drmost(node: Node, is_leaf?: LeafPredicate): [Node, number];
+
+/**
+ * 获取最左下方的后代节点
+ * @returns [最左节点, 相对深度]
+ */
+export function get_dlmost(node: Node, is_leaf?: LeafPredicate): [Node, number];
+
+/**
+ * 查找第一个拥有右兄弟节点的祖先的右兄弟
+ */
+export function find_rb_of_fst_ance_has_rb(node: Node, rel_depth: number): [Node | null, number];
+
+/**
+ * 查找第一个拥有左兄弟节点的祖先的左兄弟
+ */
+export function find_lb_of_fst_ance_has_lb(node: Node, rel_depth: number): [Node | null, number];
+
+/**
+ * 深度优先遍历 (SDFS)
+ */
+export function editonly_sdfs_for_each(rt: Node, cb?: VisitorCallback, is_leaf?: LeafPredicate): Promise<void>;
+
+/**
+ * 逆序深度优先遍历 (RSDFS)
+ */
+export function editonly_rsdfs_for_each(rt: Node, cb?: VisitorCallback, is_leaf?: LeafPredicate): Promise<void>;
+
+/**
+ * 结尾深度优先遍历 (EDFS)
+ */
+export function editonly_edfs_for_each(rt: Node, cb?: VisitorCallback, is_leaf?: LeafPredicate): Promise<void>;
+
+/**
+ * 逆向结尾深度优先遍历 (REDFS)
+ */
+export function editonly_redfs_for_each(rt: Node, cb?: VisitorCallback, is_leaf?: LeafPredicate): Promise<void>;
+
+/**
+ * 标准双向访问器遍历 (进入和离开皆有回调)
+ * @param rt 根节点
+ * @param exit_cb 离开节点时的回调 (clos 状态)
+ * @param enter_cb 进入节点时的回调 (open 状态)
+ * @param is_leaf 叶子判定
+ */
+export function visit(
+    rt: Node,
+    exit_cb?: VisitorCallback,
+    enter_cb?: VisitorCallback,
+    is_leaf?: LeafPredicate
+): Promise<void>;
+
+/**
+ * 逆向双向访问器遍历
+ * @param rt 根节点
+ * @param exit_cb 离开节点时的回调 (clos 状态)
+ * @param enter_cb 进入节点时的回调 (open 状态)
+ * @param is_leaf 叶子判定
+ */
+export function rvisit(
+    rt: Node,
+    exit_cb?: VisitorCallback,
+    enter_cb?: VisitorCallback,
+    is_leaf?: LeafPredicate
+): Promise<void>;

package/README/ui.d.ts

@@ -0,0 +1,92 @@
+/**
+ * UI 工具库类型定义 - 提供消息通知、对话框、图片处理及元素截图功能
+ * ---- UGLY simple ui tool for DEBUG and TEST
+ */
+
+/** 消息通知类型 */
+export type AlertType = 'success' | 'error' | 'warning' | 'loading' | 'info';
+
+/** 画布转换目标格式 */
+export type CanvasConvertFormat = 'b64' | 'url' | 'u8a' | 'ab' | 'img' | 'blob';
+
+/**
+ * 消息通知管理类
+ */
+export class SimpleAlert {
+    /** 存储当前活跃的任务及其定时器 */
+    private tasks: Record<string, {
+        init_timer?: number;
+        duration_timer?: number;
+        ele?: HTMLDivElement;
+    }>;
+
+    /** 删除指定标识的通知 */
+    del(src: string): void;
+
+    /** 添加或更新通知 */
+    add(
+        src: string,
+        message: string,
+        type?: AlertType,
+        duration?: number,
+        init_delay?: number
+    ): void;
+}
+
+/** 创建一个新的 SimpleAlert 实例 */
+export function creat_simple_alert(): SimpleAlert;
+
+/** 全局便捷调用：显示简单通知 */
+export function simple_alert(
+    src: string,
+    message: string,
+    type?: AlertType,
+    duration?: number,
+    init_delay?: number
+): void;
+
+/** 全局便捷调用：取消简单通知 */
+export function cancel_simple_alert(src: string): void;
+
+/**
+ * 弹出确认/取消对话框
+ * @param title 对话框标题
+ * @param cb 回调函数 (type 为 true 代表点击确认，false 为取消)
+ * @param zindex 悬浮层级
+ * @returns 返回对话框的 HTMLElement 引用
+ */
+export function simple_confirm_cancel(
+    title: string,
+    cb?: (type: boolean, el: HTMLDivElement) => void | Promise<void>,
+    zindex?: number
+): Promise<HTMLDivElement>;
+
+/**
+ * 显示图片预览遮罩弹窗
+ * 支持拖拽、保存截图和关闭
+ * @param imgData 图片数据，支持 Promise、URL 字符串或 HTMLImageElement
+ */
+export function show_img_modal(
+    imgData: Promise<any> | string | HTMLImageElement
+): Promise<void>;
+
+/**
+ * 将 Canvas 转换为指定格式
+ * @param canvas 画布元素
+ * @param format 目标格式类型
+ */
+export function convert_canvas<T extends CanvasConvertFormat>(
+    canvas: HTMLCanvasElement,
+    format: T
+): Promise<T extends 'b64' | 'url' ? string : (T extends 'img' ? HTMLImageElement : (T extends 'u8a' ? Uint8Array : (T extends 'ab' ? ArrayBuffer : Blob)))>;
+
+/**
+ * 【核心功能】将指定的 HTMLElement 捕获为图片
+ * 包含高亮反馈动画，完成后自动弹出预览（若未指定 format）或返回指定格式数据
+ * @param element 要截图的元素
+ * @param format 返回格式，若不传则直接弹出预览模态框
+ */
+export function ele2img(
+    element: HTMLElement,
+    format?: CanvasConvertFormat
+): Promise<any | void>;

package/README.md

@@ -0,0 +1,52 @@
+
+nv-basic-bw
+=======================
+- this pkg is for ui/ux debug, NOT for production
+ 
+
+
+install
+=======
+- npm install nv-basic-bw
+
+splitted
+--------
+
+- [npm install xxx](https://www.npmjs.com/package/xxx)
+
+usage
+=====
+    
+      const { }   = require("nv-basic-bw");
+ 
+
+example
+-------
+
+### 0
+
+
+#### 0_0
+
+#### 0_1
+
+
+### 1 
+
+#### 1_0
+
+#### 1_1
+
+
+METHODS
+========
+
+
+APIS
+=======
+
+
+LICENSE
+=======
+- ISC 
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nv-basic-bw",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"