nv-basic-bw 1.0.18 → 1.0.20

package/README/calc.d.ts

@@ -0,0 +1,97 @@
+/**
+ * calc.js - UI 几何布局计算与层叠上下文分析工具库
+ */
+declare module "calc" {
+    /** 矩形区域描述对象 */
+    export interface RectDesc {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    }
+
+    /** 带有元素引用的位置结果 */
+    export interface ElementRectResult {
+        el: HTMLElement;
+        rect: RectDesc;
+    }
+
+    /** 层叠上下文节点信息 */
+    export interface StackingContextNode {
+        el: HTMLElement;
+        z: number;
+        index: number;
+    }
+
+    /** 创建一个初始化的矩形描述对象 (全 0) */
+    export function creat_rect_desc(): RectDesc;
+
+    /** * 获取元素在移除 transform 后的原始布局位置 
+     * 会临时操作 DOM style 并触发重排
+     */
+    export function get_rect_desc_bfr_transfrom(el: HTMLElement): Promise<RectDesc>;
+
+    /** * 遍历子树，获取所有匹配元素在 transform 之前的原始位置 
+     */
+    export function get_all_positions_bfr_transform(
+        el: HTMLElement,
+        filter?: (el: HTMLElement) => boolean
+    ): Promise<ElementRectResult[]>;
+
+    /** * 遍历子树，获取所有匹配元素在 transform 之后的最终渲染位置 
+     */
+    export function get_all_positions_aft_transform(
+        el: HTMLElement,
+        filter?: (el: HTMLElement) => boolean
+    ): Promise<ElementRectResult[]>;
+
+    /** * 计算并返回 transform 前后产生位移或形变的元素及其差异值 
+     */
+    export function get_all_positions_transform_diff(
+        el: HTMLElement,
+        filter?: (el: HTMLElement) => boolean
+    ): Promise<ElementRectResult[]>;
+
+    /** * 判断两个矩形区域在二维平面上是否重叠 
+     */
+    export function is_rect_overlapping(rect1: RectDesc, rect2: RectDesc): boolean;
+
+    /** * 检查目标元素是否与给定元素列表中的任何一个发生重叠 
+     */
+    export function is_ele_overlapping_with_eles(checkEle: HTMLElement, eleList: HTMLElement[]): boolean;
+
+    /** * 获取元素在当前层叠上下文中的权重信息 (z-index 数值与 DOM 索引) 
+     */
+    export function get_z_stacking_info(el: HTMLElement): { zValue: number; domIndex: number };
+
+    /** * 溯源获取元素向上直到根节点的层叠上下文链条 
+     */
+    export function get_z_stacking_context_chain(el: HTMLElement): StackingContextNode[];
+
+    /** * 物理层面上比较两个元素在 Z 轴上的高低
+     * @returns 1: el0 在上, -1: el1 在上, 0: 相同
+     */
+    export function compare_z_physically(el0: HTMLElement, el1: HTMLElement): number;
+
+    /** * 判断 el0 是否在 el1 的下方
+     * @param phisically 是否考虑层叠上下文的真实物理覆盖关系。默认 true。
+     */
+    export function is_below_at_z(el0: HTMLElement, el1: HTMLElement, phisically?: boolean): boolean;
+
+    /** * 判断 el0 是否与 el1 在同一层叠层级
+     */
+    export function is_same_at_z(el0: HTMLElement, el1: HTMLElement, phisically?: boolean): boolean;
+
+    /** * 判断 el0 是否在 el1 的上方
+     */
+    export function is_upper_at_z(el0: HTMLElement, el1: HTMLElement, phisically?: boolean): boolean;
+    /** * 深度穿透探测指定坐标下的所有元素（含 Shadow DOM 内部元素）
+     */
+    export function get_deep_elements_from_point(x:Number, y:Number): Array<HTMLElement>;
+}
+
+

package/README/code.d.ts

@@ -0,0 +1,113 @@
+/**
+ * code.js - 资源采集与 CSS 变量深度探测工具库
+ */
+declare module "code" {
+    /**
+     * 获取页面中所有的脚本代码（包括外链 fetch 的内容和内联内容）
+     * 返回包裹在 <script> 标签中的合并字符串
+     */
+    export function get_all_scripts(): Promise<string>;
+
+    /**
+     * 获取页面中所有的 CSS 内容（包括外链 link 和内联 style 标签）
+     */
+    export function get_all_csses(): Promise<string>;
+
+    /**
+     * 从指定根节点搜集所有类似图片的资源 URL
+     * 涵盖 img[src], img[srcset], svg 转换出的 Blob URL, 以及 CSS 背景图
+     * @param root 起始节点，默认为 document
+     * @param fltr 过滤器，返回 false 的元素将被跳过
+     */
+    export function collect_img_like_urls(
+        root?: Document | HTMLElement, 
+        fltr?: (el: HTMLElement | SVGElement) => boolean
+    ): string[];
+
+    /**
+     * 从单个 CSSRule 中递归提取 CSS 自定义属性（变量）
+     * @param rule 样式规则
+     * @param target 存储结果的对象
+     */
+    export function extract_css_varnms_from_rule(rule: CSSRule, target: Record<string, string>): void;
+
+    /**
+     * 获取页面中所有 CSS 自定义属性（变量）及其声明值
+     * 返回格式: { [样式表来源]: { [变量名]: 变量值 } }
+     */
+    export function get_all_css_vars(): Record<string, Record<string, string>>;
+
+    /**
+     * 从样式规则中提取变量名并存入 Set
+     */
+    export function extract_css_varnms_from_rule_to_set(rule: CSSRule, name_set: Set<string>): void;
+
+    /**
+     * 获取页面所有样式表中定义的唯一 CSS 变量名数组
+     */
+    export function get_all_uniq_css_varnms(): string[];
+
+    /**
+     * 寻找定义或重定义指定 CSS 变量的最近源头节点（支持 Shadow DOM）
+     * @param varnm 变量名
+     * @param target_el 探测起始元素
+     */
+    export function find_css_var_scope_ele(varnm: string, target_el: HTMLElement): HTMLElement | null;
+
+    /**
+     * 检查变量是否是在指定元素自身上显式定义或覆盖的（而非纯继承）
+     */
+    export function is_css_var_defined_on_self(varnm: string, target_el: HTMLElement): boolean;
+
+    /**
+     * 获取变量名到其所有定义源元素的映射
+     * 返回: { "--varnm": [el, el...] }
+     */
+    export function get_css_var_scope_ele_mp(rt?: HTMLElement): Promise<Record<string, HTMLElement[]>>;
+
+    /**
+     * 获取元素到其上定义的变量名列表的映射
+     * 返回: Map { el => ["--a", "--b"] }
+     */
+    export function get_scope_ele_css_var_mp(rt?: HTMLElement): Promise<Map<HTMLElement, string[]>>;
+
+    /**
+     * 检查变量是否定义。
+     * 如果带 target_el 则查继承链；否则全局查样式表。
+     */
+    export function is_css_var_defined(varnm: string, target_el?: HTMLElement): boolean;
+
+    /**
+     * 在指定元素上定义 CSS 变量值
+     */
+    export function def_css_var(name: string, val: string | number, el?: HTMLElement): void;
+
+    /**
+     * 获取 @property 注册的元数据（类型语法、继承性、初始值）
+     */
+    export function get_css_prop_var(varnm: string): {
+        name: string;
+        syntax: string;
+        inherits: boolean;
+        initialValue?: string;
+    } | null;
+
+    /**
+     * 探测变量是否因为 @property 规则（inherits: false）而处于隔离状态
+     */
+    export function is_css_var_isolated(varnm: string, target_el: HTMLElement): boolean;
+
+    /**
+     * 运行时注册 CSS 变量规则（JS 版 @property）
+     * @param name 变量名
+     * @param options 配置项
+     */
+    export function def_css_prop_var(
+        name: string, 
+        options: {
+            syntax?: string;
+            inherits?: boolean;
+            initialValue?: string;
+        }
+    ): boolean;
+}

package/calc.js

@@ -1,4 +1,4 @@
-const {wait_for_layout_ready} = require("./wait");
+const {wait_for_layout_ready}  = require("./wait");
 
 const creat_rect_desc = () => ({
     "x": 0,
@@ -132,6 +132,186 @@ const is_ele_overlapping_with_eles = (checkEle, eleList) => {
 }
 
 
+/**
+ * 获取元素在层叠上下文中的“真实层叠权重”
+ * 返回 [zIndex(数值), DOM索引(数值)]
+ */
+const get_z_stacking_info = (el) => {
+    const style = window.getComputedStyle(el);
+    const zIndex = style.zIndex;
+    // 如果 z-index 是 auto，在层叠上下文计算中视为 0
+    // 但 auto 和 0 在某些情况下有细微区别，这里统一转为数字处理
+    const zValue = zIndex === 'auto' ? 0 : parseInt(zIndex, 10);
+    // 获取它在父元素中的位置索引，用于 z-index 相同时的“后来居上”原则
+    const domIndex = Array.from(el.parentNode?.children || []).indexOf(el);
+    return { zValue, domIndex };
+};
+
+/**
+ * 寻找元素向上直到根节点的“层叠上下文链”
+ */
+const get_z_stacking_context_chain = (el) => {
+    const chain = [];
+    let curr = el;
+    while (curr && curr !== document.documentElement) {
+        const style = window.getComputedStyle(curr);
+        // 只有创建了层叠上下文的元素才具有“统治力”
+        // 简单的判定：zIndex 不是 auto 且 position 不是 static，或者有 opacity, transform 等
+        const isStacking = style.zIndex !== 'auto' || 
+                           style.opacity < 1 || 
+                           style.transform !== 'none' || 
+                           style.flex !== 'none'; // 简化版判定
+        if (isStacking || curr === el) {
+            chain.unshift({
+                el: curr,
+                z: style.zIndex === 'auto' ? 0 : parseInt(style.zIndex, 10),
+                index: Array.from(curr.parentNode?.children || []).indexOf(curr)
+            });
+        }
+        curr = curr.parentElement;
+    }
+    return chain;
+};
+
+//取实时值，，不要取配置值
+/**
+ * 比较两个元素在 Z 轴上的高低
+ * @returns {number} 1: el0 在上, -1: el1 在上, 0: 相同
+ */
+const compare_z_physically = (el0, el1) => {
+    if (el0 === el1) return 0;
+    const chain0 = get_z_stacking_context_chain(el0);
+    const chain1 = get_z_stacking_context_chain(el1);
+    // 找到两个链条开始分叉的地方
+    let i = 0;
+    while (i < chain0.length && i < chain1.length && chain0[i].el === chain1[i].el) {
+        i++;
+    }
+    // 如果在一个链条内（一个是另一个的祖先）
+    if (i === chain0.length) return -1; // el0 是 el1 的祖先，通常在下
+    if (i === chain1.length) return 1;  // el1 是 el0 的祖先，通常在上
+    // 在分叉点对比两者的层叠属性
+    const node0 = chain0[i];
+    const node1 = chain1[i];
+    if (node0.z !== node1.z) {
+        return node0.z > node1.z ? 1 : -1;
+    }
+    // z-index 相同，靠后的胜出
+    return node0.index > node1.index ? 1 : -1;
+};
+
+const is_below_at_z = (el0, el1, phisically = true) => {
+    if (phisically) return compare_z_physically(el0, el1) === -1;
+    const s0 = get_z_stacking_info(el0);
+    const s1 = get_z_stacking_info(el1);
+    return s0.zValue < s1.zValue || (s0.zValue === s1.zValue && s0.domIndex < s1.domIndex);
+};
+
+const is_same_at_z = (el0, el1, phisically = true) => {
+    if (phisically) return compare_z_physically(el0, el1) === 0;
+    const s0 = get_z_stacking_info(el0);
+    const s1 = get_z_stacking_info(el1);
+    return s0.zValue === s1.zValue && s0.domIndex === s1.domIndex;
+};
+
+const is_upper_at_z = (el0, el1, phisically = true) => {
+    if (phisically) return compare_z_physically(el0, el1) === 1;
+    const s0 = get_z_stacking_info(el0);
+    const s1 = get_z_stacking_info(el1);
+    return s0.zValue > s1.zValue || (s0.zValue === s1.zValue && s0.domIndex > s1.domIndex);
+};
+
+/**
+ * 深度穿透探测指定坐标下的所有元素（含 Shadow DOM 内部元素）
+ * @param {number} x - ClientX
+ * @param {number} y - ClientY
+ * @returns {Element[]} 按从上到下顺序排列的元素数组
+ */
+const get_deep_elements_from_point = (x, y) => {
+    const elements = new Set(); // 使用 Set 去重
+
+    const get_deep_at = (root) => {
+        // 1. 获取当前根节点下该坐标的所有元素
+        const targets = root.elementsFromPoint ?
+                        root.elementsFromPoint(x, y) :
+                        [];
+
+        for (const el of targets) {
+            // 如果已经处理过（避免死循环），跳过
+            if (elements.has(el)) continue;
+            elements.add(el);
+
+            // 2. 核心：如果该元素拥有 ShadowRoot，递归进去
+            if (el.shadowRoot) {
+                get_deep_at(el.shadowRoot);
+            }
+        }
+    };
+
+    get_deep_at(document);
+
+    // 转换为数组，并按照它们在 DOM 树中的视觉层级（从上到下）排序
+    // elementsFromPoint 默认就是从上到下的，递归合并后大部分情况下顺序是正确的
+    return Array.from(elements);
+};
+
+/**
+ * 根据索引获取具备高辨识度的状态样式 (Indexed Distinct Style)
+ * 采用黄金角算法确保色相跨度最大，并结合背景材质进行分组细化。
+ */
+function get_indexed_distinct_style(idx, total) {
+    if (idx === 0) return { 
+        backgroundColor: '#ffffff', 
+        backgroundImage: 'none',
+        color: '#000'
+    };
+
+    const goldenAngle = 137.508;
+    const hue = (idx * goldenAngle) % 360;
+    
+    // 分组逻辑：将 360 度分为 6 个主色相组
+    const group = Math.floor(hue / 60);
+    
+    let style = {
+        backgroundColor: `hsl(${hue}, 75%, 82%)`, // 统一亮度
+        backgroundImage: 'none',
+        color: '#000',
+        fontWeight: 'bold',
+        border: 'none'
+    };
+
+    const dark_mask = 'rgba(0,0,0,0.12)';
+    const light_mask = 'rgba(255,255,255,0.4)';
+
+    // 基于 group 的背景材质编码 (Visual Fingerprinting)
+    if (group === 0) { // 红色系 - 纯平材质
+        style.backgroundImage = 'none';
+    } 
+    else if (group === 1) { // 黄色系 - 经典波点
+        style.backgroundImage = `radial-gradient(${dark_mask} 15%, transparent 16%)`;
+        style.backgroundSize = '6px 6px';
+    } 
+    else if (group === 2) { // 绿色系 - 微型格纹
+        style.backgroundImage = `linear-gradient(45deg, ${dark_mask} 25%, transparent 25%, transparent 75%, ${dark_mask} 75%, ${dark_mask}), linear-gradient(45deg, ${dark_mask} 25%, transparent 25%, transparent 75%, ${dark_mask} 75%, ${dark_mask})`;
+        style.backgroundSize = '10px 10px';
+        style.backgroundPosition = '0 0, 5px 5px';
+    } 
+    else if (group === 3) { // 青色系 - 散斑材质
+        style.backgroundImage = `radial-gradient(${dark_mask} 15%, transparent 16%), radial-gradient(${light_mask} 15%, transparent 16%)`;
+        style.backgroundSize = '8px 8px';
+        style.backgroundPosition = '0 0, 4px 4px';
+    } 
+    else if (group === 4) { // 蓝色系 - 垂直栅栏纹
+        style.backgroundImage = `linear-gradient(90deg, ${dark_mask} 1px, transparent 1px)`;
+        style.backgroundSize = '4px 100%';
+    } 
+    else { // 紫色系 - 柔光渐变
+        style.backgroundImage = `radial-gradient(circle at center, ${light_mask} 0%, transparent 75%)`;
+    }
+
+    return style;
+}
+
 module.exports = {
     creat_rect_desc,
     get_rect_desc_bfr_transfrom,
@@ -140,5 +320,10 @@ module.exports = {
     get_all_positions_transform_diff,
     is_rect_overlapping,
     is_ele_overlapping_with_eles,
-    
+    get_z_stacking_info,
+    get_z_stacking_context_chain,
+    compare_z_physically,
+    is_below_at_z,is_same_at_z,is_upper_at_z,
+    get_deep_elements_from_point,
+    get_indexed_distinct_style
 }