huibo-ui 0.3.0 → 0.5.0

package/dist/collection/components/Cascader/Cascader.js

@@ -2,114 +2,94 @@ import { h } from "@stencil/core";
 import { createClickOutsideHandler } from "../../utils/click-outside";
 /**
  * Cascader 级联选择器组件
- * 当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择
+ * 当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择。
+ * 支持单选 / 多选（multiple）、可选任意层级（checkStrictly）、搜索（filterable）、动态加载（lazy）。
  */
 export class Cascader {
     el;
     /**
-     * 选中项绑定值
+     * 选中项绑定值。单选为一维路径数组（如 ['zhejiang','hangzhou']），
+     * 多选（multiple）为二维数组（如 [['zhejiang','ningbo'], ['jiangsu']]）。
      */
     modelValue;
-    /**
-     * 可选项数据源
-     */
+    /** 可选项数据源 */
     options = [];
-    /**
-     * 输入框占位文本
-     */
+    /** 输入框占位文本 */
     placeholder = '请选择';
-    /**
-     * 是否禁用
-     * @default false
-     */
+    /** 是否禁用 */
     disabled = false;
-    /**
-     * 输入框尺寸
-     */
+    /** 输入框尺寸 */
     size = 'default';
-    /**
-     * 是否可清空
-     * @default false
-     */
+    /** 是否可清空 */
     clearable = false;
-    /**
-     * 是否显示完整路径
-     * @default true
-     */
+    /** 是否显示完整路径（单选输入框 / 多选 tag 文本） */
     showAllLevels = true;
-    /**
-     * 输入框的原生属性
-     */
+    /** 输入框原生属性 */
     name;
-    /**
-     * 输入框的原生属性
-     */
+    /** 输入框原生属性 */
     inputId;
-    /**
-     * 分隔符
-     * @default ' / '
-     */
+    /** 路径分隔符 */
     separator = ' / ';
-    /**
-     * 是否动态加载子节点
-     * @default true
-     */
+    /** modelValue 是否输出完整路径（保留 AntD 兼容位） */
     emitPath = true;
     /**
-     * 是否可搜索（filterable）
-     * 开启后下拉顶部渲染搜索输入框，输入时按 label（含所有子级）扁平化过滤，
-     * 匹配项以完整路径展示，点击即选中其完整路径。
-     * @default false
+     * 是否可搜索（filterable）。下拉顶部渲染搜索框，输入时按 label 扁平化过滤，
+     * 匹配项以完整路径展示，点击即选中（单选）或 toggle 勾选（多选）。
      */
     filterable = false;
     /**
-     * 是否开启动态加载（lazy load）。开启后，展开含 children=undefined 的节点时，
-     * 调用 load(node) 获取其子级并填充进 options，加载中显示 loading 态。
-     * @default false
+     * 是否开启动态加载（lazy）。展开 children=undefined 的节点时调用 load(node) 填充子级。
      */
     lazy = false;
+    /** 动态加载函数（仅 lazy=true 生效） */
+    load;
     /**
-     * 动态加载子节点的函数（仅在 lazy=true 时生效）。
-     * 接收被展开的节点，返回其子节点数组（Promise）。
-     * 加载结果会以不可变方式合并进 options 树（替换该节点 children）。
+     * 是否开启多选。开启后 modelValue 为二维数组，每条为一个选中路径；
+     * 菜单项前渲染 checkbox，输入框以 tag 列表展示选中项。
      */
-    load;
-    isOpen = false;
-    inputValue = '';
-    searchValue = '';
+    multiple = false;
     /**
-     * 正在动态加载子级的节点 value 集合（用于渲染 loading 态）。
+     * 是否严格的选中行为（父子不关联）。
+     * 单选：点击任意层级（含非叶子）即选中该路径；
+     * 多选：勾选独立，不向下联动选中叶子、取消也不联动。
      */
-    loadingKeys = new Set();
+    checkStrictly = false;
     /**
-     * 扁平化搜索结果：每一项是一个从根到匹配节点的完整路径（用于点击选中）。
-     * 仅在 filterable 且 searchValue 非空时使用。
+     * 多选时输入框最多展示的 tag 数量，超出折叠为 +N（可选）。
      */
+    maxTagCount;
+    isOpen = false;
+    inputValue = '';
+    searchValue = '';
+    /** 正在动态加载子级的节点 value 集合 */
+    loadingKeys = new Set();
+    /** 扁平化搜索结果：每项为根到匹配节点的完整路径 */
     filteredPaths = [];
     activePath = [];
-    /**
-     * 值改变事件
-     */
+    /** 值改变事件：单选 emit 一维路径或 undefined；多选 emit 二维数组（可能为 []） */
     hbChange;
-    /**
-     * 展开节点发生变化时触发
-     */
+    /** 展开节点变化时触发 */
     hbExpandChange;
     clickOutside = createClickOutsideHandler({
         host: null,
         isOpen: () => this.isOpen,
-        onClose: () => { this.closeAndClearSearch(); },
+        onClose: () => {
+            this.closeAndClearSearch();
+        },
     });
+    /** P4：搜索结果上限，防止超大树一次返回上万条结果拖垮渲染（封顶替代防抖，避免定时器/测试复杂性） */
+    static MAX_FILTER_RESULTS = 200;
     componentDidLoad() {
         this.clickOutside = createClickOutsideHandler({
             host: this.el,
             isOpen: () => this.isOpen,
-            onClose: () => { this.closeAndClearSearch(); },
+            onClose: () => {
+                this.closeAndClearSearch();
+            },
         });
         this.clickOutside.connect();
         this.updateInputValue();
     }
-    /** 关闭下拉并清空搜索态（filterable 模式下避免重开时残留搜索结果） */
     closeAndClearSearch() {
         this.isOpen = false;
         this.searchValue = '';
@@ -122,19 +102,24 @@ export class Cascader {
         this.updateInputValue();
     }
     updateInputValue() {
+        if (this.multiple) {
+            this.inputValue = '';
+            return;
+        }
         if (!this.modelValue || this.modelValue.length === 0) {
             this.inputValue = '';
             return;
         }
+        const mv = this.modelValue;
         if (!this.showAllLevels) {
-            const lastValue = this.modelValue[this.modelValue.length - 1];
+            const lastValue = mv[mv.length - 1];
             const option = this.findOptionByValue(this.options, lastValue);
             this.inputValue = option ? option.label : '';
             return;
         }
         const labels = [];
         let currentOptions = this.options;
-        for (const value of this.modelValue) {
+        for (const value of mv) {
             const option = currentOptions.find(opt => opt.value === value);
             if (option) {
                 labels.push(option.label);
@@ -148,9 +133,8 @@ export class Cascader {
     }
     findOptionByValue(options, value) {
         for (const option of options) {
-            if (option.value === value) {
+            if (option.value === value)
                 return option;
-            }
             if (option.children) {
                 const found = this.findOptionByValue(option.children, value);
                 if (found)
@@ -159,59 +143,213 @@ export class Cascader {
         }
         return null;
     }
+    // ===== 多选（multiple）核心算法 =====
+    /** 取多选 modelValue 为二维数组（非多选模式或形状不符时返回 []） */
+    getMultiModel() {
+        if (!this.multiple)
+            return [];
+        const mv = this.modelValue;
+        if (Array.isArray(mv) && mv.length > 0 && Array.isArray(mv[0]))
+            return mv;
+        return [];
+    }
+    /**
+     * 多选 modelValue 的字符串键集合（P2 优化）。
+     * 缓存：仅当 modelValue 引用变化时重算。check-state 查询从 O(model×pathLen)
+     * 降为 O(1) Set.has。key 用 \u0000 连接 path 各段，避免与合法分隔符冲突。
+     */
+    _modelKeySet = null;
+    _modelKeySetRef = null;
+    getModelKeySet() {
+        if (this._modelKeySet && this._modelKeySetRef === this.modelValue) {
+            return this._modelKeySet;
+        }
+        const set = new Set();
+        for (const p of this.getMultiModel()) {
+            set.add(p.join('\u0000'));
+        }
+        this._modelKeySet = set;
+        this._modelKeySetRef = this.modelValue;
+        return set;
+    }
+    /** path 是否在当前 model 集合中（O(1)） */
+    pathInModel(path) {
+        return this.getModelKeySet().has(path.join('\u0000'));
+    }
+    /** 两条 value 路径是否完全相等 */
+    pathEquals(a, b) {
+        if (!a || a.length !== b.length)
+            return false;
+        return a.every((v, i) => v === b[i]);
+    }
+    /** 收集某节点子树下的全部叶子 value 路径（用于父子联动计算） */
+    collectLeafValuePaths(option, basePath) {
+        const currentPath = [...basePath, option.value];
+        const hasChildren = option.children && option.children.length > 0;
+        if (!hasChildren || option.leaf)
+            return [currentPath];
+        const result = [];
+        for (const child of option.children) {
+            result.push(...this.collectLeafValuePaths(child, currentPath));
+        }
+        return result;
+    }
+    /**
+     * 多选模式下某节点的勾选三态。
+     * checkStrictly：该节点路径是否在 modelValue（checked / unchecked）。
+     * 默认：按叶子计算 —— 全部叶子入选=checked，部分=indeterminate，无=unchecked。
+     */
+    getCheckState(option, path) {
+        const valuePath = [...path, option.value];
+        if (this.checkStrictly) {
+            // P2：O(1) Set 查询替代 O(model) 的 some(pathEquals)
+            return this.pathInModel(valuePath) ? 'checked' : 'unchecked';
+        }
+        const leafPaths = this.collectLeafValuePaths(option, path);
+        // P2：用 pathInModel（Set.has）替代 model.some(pathEquals)，整段从 O(leaves×model) 降为 O(leaves)
+        if (leafPaths.every(lp => this.pathInModel(lp)))
+            return 'checked';
+        if (leafPaths.some(lp => this.pathInModel(lp)))
+            return 'indeterminate';
+        return 'unchecked';
+    }
+    /** 多选：toggle 某节点勾选（按 checkStrictly 决定是否联动叶子） */
+    handleCheck(option, path) {
+        let model = this.getMultiModel().map(p => [...p]);
+        const valuePath = [...path, option.value];
+        if (this.checkStrictly) {
+            const idx = model.findIndex(p => this.pathEquals(p, valuePath));
+            if (idx >= 0)
+                model.splice(idx, 1);
+            else
+                model.push(valuePath);
+        }
+        else {
+            const leafPaths = this.collectLeafValuePaths(option, path);
+            const allIn = leafPaths.every(lp => model.some(p => this.pathEquals(p, lp)));
+            if (allIn) {
+                model = model.filter(p => !leafPaths.some(lp => this.pathEquals(lp, p)));
+            }
+            else {
+                for (const lp of leafPaths) {
+                    if (!model.some(p => this.pathEquals(p, lp)))
+                        model.push([...lp]);
+                }
+            }
+        }
+        this.modelValue = model;
+        this.hbChange.emit(model);
+    }
+    /** 多选输入框 tag 数据：每条选中路径 → 展示文本 + 路径 */
+    getDisplayTags() {
+        return this.getMultiModel().map(path => {
+            const labels = path.map(v => {
+                const opt = this.findOptionByValue(this.options, v);
+                return opt ? opt.label : String(v);
+            });
+            const label = this.showAllLevels ? labels.join(this.separator) : labels[labels.length - 1];
+            return { label, path };
+        });
+    }
+    /** 多选：删除单个 tag（移除对应路径） */
+    handleTagRemove = (path, e) => {
+        e.stopPropagation();
+        const model = this.getMultiModel().filter(p => !this.pathEquals(p, path));
+        this.modelValue = model;
+        this.hbChange.emit(model);
+    };
+    hasValue() {
+        return this.multiple ? this.getMultiModel().length > 0 : !!this.modelValue && this.modelValue.length > 0;
+    }
+    // ===== 交互 =====
     handleInputClick = () => {
         if (this.disabled)
             return;
         if (this.isOpen) {
-            // 关闭时清空搜索态
             this.closeAndClearSearch();
         }
         else {
             this.isOpen = true;
         }
     };
-    /** 搜索输入：仅更新 searchValue，过滤在 render 前的 @State 派生 */
+    /**
+     * 键盘交互（对齐 antd / WAI-ARIA combobox）：
+     * Enter/Space/ArrowDown 在关闭时打开；Escape 关闭；ArrowRight/ArrowLeft 跨级导航。
+     */
+    handleKeyDown = (e) => {
+        if (this.disabled)
+            return;
+        const key = e.key;
+        if (!this.isOpen) {
+            if (key === 'Enter' || key === ' ' || key === 'ArrowDown') {
+                e.preventDefault();
+                this.isOpen = true;
+            }
+            return;
+        }
+        if (key === 'Escape') {
+            e.preventDefault();
+            this.closeAndClearSearch();
+        }
+        else if (key === 'Enter' && this.activePath.length > 0 && !this.multiple) {
+            // 选中当前路径末端叶子（若已是叶子）
+            e.preventDefault();
+            const lastValue = this.activePath[this.activePath.length - 1];
+            const parentPath = this.activePath.slice(0, -1);
+            this.handleSelect(lastValue, parentPath);
+        }
+    };
     handleSearchInput = (e) => {
         const target = e.target;
         this.searchValue = target.value;
+        // P4：清空时立即返回空；非空时同步过滤但结果数封顶（MAX_FILTER_RESULTS），
+        // 避免超大树返回上万条结果拖垮渲染。封顶比防抖更稳妥（不引入定时器与测试复杂性）。
         this.filteredPaths = this.collectFilteredPaths(this.searchValue);
     };
-    /**
-     * 扁平化全树搜索：把 options 深度遍历，收集所有「节点 label 含关键字」的完整路径。
-     * 一个节点的完整路径 = 从根到该节点（含自身）的 CascaderOption 数组。
-     * 关键字为空时返回空数组（交由正常级联视图渲染）。
-     *
-     * 注意：这里按 label 子串匹配（大小写不敏感），匹配任意层级的节点，
-     * 并保留其祖先链以便点击时还原完整路径。
-     */
     collectFilteredPaths(keyword) {
         const trimmed = keyword.trim().toLowerCase();
         if (!trimmed)
             return [];
         const results = [];
+        const max = Cascader.MAX_FILTER_RESULTS;
         const walk = (opts, ancestors) => {
+            // P4：达到上限即停止递归，避免超大树返回过多结果
+            if (results.length >= max)
+                return;
             for (const opt of opts) {
+                if (results.length >= max)
+                    return;
                 const currentPath = [...ancestors, opt];
-                if (opt.label.toLowerCase().includes(trimmed)) {
+                if (opt.label.toLowerCase().includes(trimmed))
                     results.push(currentPath);
-                }
-                if (opt.children && opt.children.length > 0) {
+                if (opt.children && opt.children.length > 0)
                     walk(opt.children, currentPath);
-                }
             }
         };
         walk(this.options, []);
         return results;
     }
-    /** 从扁平搜索结果路径中点击叶子（或非叶子）项：直接以该路径的 value 数组作为选中值 */
+    /** 搜索结果点击：单选选中（叶子或 checkStrictly 任意层），多选 toggle 该路径 */
     handleSearchSelect = (path) => {
-        const valuePath = path.map((opt) => opt.value);
+        const valuePath = path.map(opt => opt.value);
+        if (this.multiple) {
+            let model = this.getMultiModel().map(p => [...p]);
+            const idx = model.findIndex(p => this.pathEquals(p, valuePath));
+            if (idx >= 0)
+                model.splice(idx, 1);
+            else
+                model.push(valuePath);
+            this.modelValue = model;
+            this.hbChange.emit(model);
+            this.searchValue = '';
+            this.filteredPaths = [];
+            return;
+        }
         const last = path[path.length - 1];
         const isLeaf = !last.children || last.children.length === 0 || last.leaf;
         this.searchValue = '';
         this.filteredPaths = [];
-        if (isLeaf) {
-            // 叶子：选中并关闭
+        if (isLeaf || this.checkStrictly) {
             this.modelValue = valuePath;
             this.updateInputValue();
             this.hbChange.emit(valuePath);
@@ -219,21 +357,42 @@ export class Cascader {
             this.activePath = [];
         }
         else {
-            // 非叶子：进入该路径的级联展开（便于继续选下级）
             this.activePath = valuePath;
             this.hbExpandChange.emit(valuePath);
         }
     };
     handleClear = (e) => {
         e.stopPropagation();
-        this.modelValue = undefined;
-        this.inputValue = '';
+        if (this.multiple) {
+            this.modelValue = [];
+            this.hbChange.emit([]);
+        }
+        else {
+            this.modelValue = undefined;
+            this.inputValue = '';
+            this.hbChange.emit(undefined);
+        }
         this.isOpen = false;
-        this.hbChange.emit(undefined);
     };
-    handleSelect = (value, path) => {
+    /** 菜单项点击（label 区）：多选→叶子 toggle/非叶子展开；单选→handleSelect */
+    handleItemClick = (option, path) => {
+        if (this.multiple) {
+            const isLeaf = !option.children || option.children.length === 0 || option.leaf;
+            if (isLeaf) {
+                this.handleCheck(option, path);
+            }
+            else {
+                const newPath = [...path, option.value];
+                this.activePath = newPath;
+                this.hbExpandChange.emit(newPath);
+            }
+            return;
+        }
+        this.handleSelect(option.value, path);
+    };
+    /** 单选：选中（叶子或 checkStrictly 任意层）或展开 / lazy 加载 */
+    handleSelect(value, path) {
         const newPath = [...path, value];
-        // Find the selected option
         let currentOptions = this.options;
         let selectedOption = null;
         for (const pathValue of newPath) {
@@ -242,21 +401,16 @@ export class Cascader {
                 break;
             currentOptions = selectedOption.children || [];
         }
-        // lazy + load：节点 children 尚未加载（children === undefined 且 leaf 未声明）→ 触发加载
-        if (this.lazy &&
-            this.load &&
-            selectedOption &&
-            selectedOption.children === undefined &&
-            !selectedOption.leaf) {
-            // 先展开该路径（显示 loading 态的下一级面板占位），再异步填充
+        // lazy + load：children 未加载 → 触发加载
+        if (this.lazy && this.load && selectedOption && selectedOption.children === undefined && !selectedOption.leaf) {
             this.activePath = newPath;
             this.hbExpandChange.emit(newPath);
             void this.loadChildren(selectedOption, newPath);
             return;
         }
-        // Check if it's a leaf node
-        if (!selectedOption || !selectedOption.children || selectedOption.children.length === 0 || selectedOption.leaf) {
-            // Leaf node - select and close
+        const isLeaf = !selectedOption || !selectedOption.children || selectedOption.children.length === 0 || selectedOption.leaf;
+        // checkStrictly 或叶子 → 选中并关闭
+        if (this.checkStrictly || isLeaf) {
             this.modelValue = newPath;
             this.updateInputValue();
             this.hbChange.emit(newPath);
@@ -264,29 +418,20 @@ export class Cascader {
             this.activePath = [];
         }
         else {
-            // Has children - expand to next level
+            // 非叶子 → 展开
             this.activePath = newPath;
             this.hbExpandChange.emit(newPath);
         }
-    };
-    /**
-     * 动态加载某节点的子级。不可变地合并进 options 树（替换该节点 children）。
-     * 加载中：把节点 value 加入 loadingKeys（渲染 loading 态）；
-     * 加载完成：写入 children（新数组，触发 @Watch/重渲染），移出 loadingKeys。
-     * 若 load 返回空数组，把 children 设为 [] 以标记该节点为叶子（避免重复加载）。
-     */
+    }
     async loadChildren(node, path) {
         if (!this.load)
             return;
-        // 标记 loading
         this.loadingKeys = new Set([...this.loadingKeys, node.value]);
         try {
             const children = await this.load(node);
-            // 不可变合并：重建 options 树，仅替换目标节点的 children。
             this.options = this.replaceOptionChildren(this.options, node.value, children);
         }
         catch (err) {
-            // 加载失败：回退 activePath，避免卡在 loading；保持 options 不变。
             // eslint-disable-next-line no-console
             console.error('[hb-cascader] lazy load failed:', err);
             this.activePath = this.activePath.slice(0, this.activePath.indexOf(node.value) + 1);
@@ -296,46 +441,54 @@ export class Cascader {
             next.delete(node.value);
             this.loadingKeys = next;
         }
-        // 重新校验该路径是否还能继续展开（叶子情况则收起下一级面板）
         void path;
         void node;
     }
-    /**
-     * 不可变地替换 options 树中 value===targetValue 节点的 children 字段。
-     * 返回一棵全新的 options 树（不修改原数组与原节点对象）。
-     */
     replaceOptionChildren(options, targetValue, newChildren) {
-        return options.map((opt) => {
-            if (opt.value === targetValue) {
+        return options.map(opt => {
+            if (opt.value === targetValue)
                 return { ...opt, children: newChildren };
-            }
             if (opt.children && opt.children.length > 0) {
                 return { ...opt, children: this.replaceOptionChildren(opt.children, targetValue, newChildren) };
             }
             return opt;
         });
     }
+    // ===== render =====
     render() {
-        return (h("div", { key: 'c842622737b0464fca8807b2e6e673de26e66f6c', class: {
+        // P3：getDisplayTags() 涉及全树递归，单次 render 仅算一次，避免 3 次重复递归。
+        const displayTags = this.multiple ? this.getDisplayTags() : [];
+        const visibleTags = this.maxTagCount === undefined ? displayTags : displayTags.slice(0, this.maxTagCount);
+        const overflowCount = this.maxTagCount !== undefined ? Math.max(0, displayTags.length - this.maxTagCount) : 0;
+        return (h("div", { key: 'bb73a58c2631b45200fa7e4e317660efe6683f8e', class: {
                 'hb-cascader': true,
                 'hb-cascader--open': this.isOpen,
                 'hb-cascader--disabled': this.disabled,
+                'hb-cascader--multiple': this.multiple,
                 [`hb-cascader--${this.size}`]: true,
-            } }, h("div", { key: '23279bca07ba9263b6b7daa87fcc6ecf89cfa707', class: "hb-cascader__input-wrapper", onClick: this.handleInputClick }, h("input", { key: '56253203d0684b374ee755d669ce1ef61eebb2e2', type: "text", id: this.inputId, name: this.name, class: "hb-cascader__input", placeholder: this.placeholder, value: this.inputValue, disabled: this.disabled, readonly: true, role: "combobox", "aria-haspopup": "listbox", "aria-expanded": this.isOpen ? 'true' : 'false' }), h("span", { key: '27eb1713ab7eabc760652d60d48960685dfdb0ce', class: "hb-cascader__suffix" }, this.clearable && this.modelValue && this.modelValue.length > 0 && (h("span", { key: '26c75b651d82806019f514e9dc030df394419e46', class: "hb-cascader__clear", role: "button", "aria-label": "\u6E05\u7A7A", onClick: this.handleClear }, "\u00D7")), h("span", { key: '01cc98144fa2cf70fcc7588efadd7bbeea17738b', class: "hb-cascader__arrow" }, "\u25BC"))), this.isOpen && (h("div", { key: '23a6230933ffaf0ee98c2c70a8dc9a8444be0555', class: "hb-cascader__dropdown" }, this.filterable && (h("div", { key: '628a293edf4d2f22975801e2e9155f46a5cf90fa', class: "hb-cascader__search" }, h("input", { key: 'bedac6a61a99b8a64d27eaf95880ff4891c33f04', type: "text", class: "hb-cascader__search-input", placeholder: "\u641C\u7D22", value: this.searchValue, onInput: this.handleSearchInput, "aria-label": "\u641C\u7D22\u9009\u9879" }))), this.filterable && this.searchValue.trim() !== '' ? (this.renderSearchResults()) : (h("div", { class: "hb-cascader__menus", role: "listbox", "aria-multiselectable": "false" }, this.renderCascaderMenus()))))));
+            } }, h("div", { key: '3c0dd3a737b533c32ed86fc0c3c5454e9bcc46d6', class: "hb-cascader__input-wrapper", onClick: this.handleInputClick }, this.multiple &&
+            visibleTags.map(tag => (h("span", { class: "hb-cascader__tag" }, h("span", { class: "hb-cascader__tag-label" }, tag.label), !this.disabled && (h("span", { class: "hb-cascader__tag-close", role: "button", "aria-label": "\u5220\u9664", tabindex: 0, onClick: e => this.handleTagRemove(tag.path, e), onKeyDown: e => {
+                    if (e.key === 'Enter' || e.key === ' ') {
+                        e.preventDefault();
+                        this.handleTagRemove(tag.path, e);
+                    }
+                } }, h("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": 2, "stroke-linecap": "round", "stroke-linejoin": "round", "aria-hidden": "true" }, h("path", { d: "M6 6l12 12M18 6L6 18" }))))))), this.multiple && overflowCount > 0 && h("span", { key: 'd598659ffcb4c0e1085da1476413fedc561c3017', class: "hb-cascader__tag-overflow" }, "+", overflowCount), h("input", { key: 'd171dc3467e238cfcd2de761bc5ff99d66765b1c', type: "text", id: this.inputId, name: this.name, class: "hb-cascader__input", placeholder: this.hasValue() ? '' : this.placeholder, value: this.multiple ? '' : this.inputValue, disabled: this.disabled, readonly: true, role: "combobox", "aria-haspopup": "listbox", "aria-expanded": this.isOpen ? 'true' : 'false', onKeyDown: this.handleKeyDown }), h("span", { key: '3b9492164b342fabeaa901be0f5b82079288c6eb', class: "hb-cascader__suffix" }, this.clearable && this.hasValue() && (h("span", { key: 'fad80bdcab2dc2f6cc0550fdde2626159994606d', class: "hb-cascader__clear", role: "button", "aria-label": "\u6E05\u7A7A", tabindex: 0, onClick: this.handleClear, onKeyDown: e => {
+                if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault();
+                    this.handleClear(e);
+                }
+            } }, h("svg", { key: '14104b827fc9406fb6e6fd670c3401135f786d27', viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": 2, "stroke-linecap": "round", "stroke-linejoin": "round", "aria-hidden": "true" }, h("path", { key: '8b25d28b878f237d610c430625abef6990490289', d: "M6 6l12 12M18 6L6 18" })))), h("span", { key: '5948e9fd65445aae63db23c868d3e0b773d35f8b', class: "hb-cascader__arrow", "aria-hidden": "true" }, h("svg", { key: '81c42e2f49f5ef433288e1a810a42ab2d60557dc', viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": 2, "stroke-linecap": "round", "stroke-linejoin": "round" }, h("path", { key: '0960e7b2391417d4ca98ff0b2b2e4629b4456285', d: "M6 9l6 6 6-6" }))))), this.isOpen && (h("div", { key: '98e0dbb48d9c6b4e372fdea3f1dfddc4eabf0d0f', class: "hb-cascader__dropdown" }, this.filterable && (h("div", { key: '8c8a620342182941a98222139d2d156ef81f0e30', class: "hb-cascader__search" }, h("input", { key: 'f6efd8233131cbfb4eda6beaacd4cec908f2e944', type: "text", class: "hb-cascader__search-input", placeholder: "\u641C\u7D22", value: this.searchValue, onInput: this.handleSearchInput, "aria-label": "\u641C\u7D22\u9009\u9879" }))), this.filterable && this.searchValue.trim() !== '' ? (this.renderSearchResults()) : (h("div", { class: "hb-cascader__menus", role: "listbox", "aria-multiselectable": this.multiple ? 'true' : 'false' }, this.renderCascaderMenus()))))));
     }
     renderCascaderMenus() {
         const menus = [];
         let currentOptions = this.options;
         let currentPath = [];
-        // Render first level
         menus.push(this.renderMenu(currentOptions, currentPath));
-        // Render active path levels
         for (let i = 0; i < this.activePath.length; i++) {
             const pathValue = this.activePath[i];
             const option = currentOptions.find(opt => opt.value === pathValue);
             if (!option)
                 break;
-            // lazy 加载中：节点 children 尚未填充 → 渲染 loading 面板
             if (option.children === undefined && this.loadingKeys.has(option.value)) {
                 menus.push(this.renderLoadingMenu());
                 break;
@@ -351,49 +504,56 @@ export class Cascader {
         }
         return menus;
     }
-    /** lazy 加载中渲染的面板：一个 loading 占位提示 */
     renderLoadingMenu() {
         return (h("ul", { class: "hb-cascader__menu-list hb-cascader__menu-list--loading", role: "status", "aria-live": "polite" }, h("li", { class: "hb-cascader__menu-item hb-cascader__menu-item--loading" }, h("span", { class: "hb-cascader__menu-item-label" }, "\u52A0\u8F7D\u4E2D\u2026"))));
     }
-    /**
-     * 渲染扁平化搜索结果：每一项展示完整路径（label 用 separator 连接），点击选中完整路径。
-     * 无匹配时渲染空状态。
-     */
     renderSearchResults() {
         if (this.filteredPaths.length === 0) {
             return (h("div", { class: "hb-cascader__search-empty", role: "status" }, "\u65E0\u5339\u914D\u6570\u636E"));
         }
-        return (h("div", { class: "hb-cascader__search-results", role: "listbox", "aria-label": "\u641C\u7D22\u7ED3\u679C" }, this.filteredPaths.map((path) => {
-            const labelPath = path.map((opt) => opt.label).join(this.separator);
-            const valuePath = path.map((opt) => opt.value);
+        return (h("div", { class: "hb-cascader__search-results", role: "listbox", "aria-label": "\u641C\u7D22\u7ED3\u679C" }, this.filteredPaths.map(path => {
+            const labelPath = path.map(opt => opt.label).join(this.separator);
+            const valuePath = path.map(opt => opt.value);
             const last = path[path.length - 1];
             const disabled = !!last.disabled;
-            // 当前选中判断：路径 value 与 modelValue 完全一致
-            const selected = !!this.modelValue &&
-                this.modelValue.length === valuePath.length &&
-                valuePath.every((v, idx) => this.modelValue && this.modelValue[idx] === v);
+            const selected = this.multiple
+                ? this.getMultiModel().some(p => this.pathEquals(p, valuePath))
+                : !!this.modelValue && this.pathEquals(this.modelValue, valuePath);
             return (h("div", { class: {
                     'hb-cascader__search-item': true,
                     'hb-cascader__search-item--selected': selected,
                     'hb-cascader__search-item--disabled': disabled,
-                }, role: "option", "aria-selected": selected ? 'true' : 'false', "aria-disabled": disabled ? 'true' : undefined, onClick: () => !disabled && this.handleSearchSelect(path) }, labelPath));
+                }, role: "option", "aria-selected": selected ? 'true' : 'false', "aria-disabled": disabled ? 'true' : undefined, onClick: () => !disabled && this.handleSearchSelect(path) }, this.multiple && (h("span", { class: "hb-cascader__menu-item-checkbox", "data-state": selected ? 'checked' : 'unchecked', role: "checkbox", "aria-checked": selected ? 'true' : 'false' })), labelPath));
         })));
     }
     renderMenu(options, path) {
-        if (!options || options.length === 0) {
+        if (!options || options.length === 0)
             return null;
-        }
-        return (h("ul", { class: "hb-cascader__menu-list", role: "group" }, options.map((option) => {
-            const isSelected = path.length > 0 && path[path.length - 1] === option.value;
-            const isInPath = this.modelValue && path.length > 0 &&
-                path.every((val, idx) => this.modelValue && this.modelValue[idx] === val) &&
+        return (h("ul", { class: "hb-cascader__menu-list", role: "group" }, options.map(option => {
+            const checkState = this.getCheckState(option, path);
+            // 单选高亮：路径在当前 modelValue 上
+            const isSelected = !this.multiple &&
+                path.length > 0 &&
+                !!this.modelValue &&
+                path.every((val, idx) => this.modelValue[idx] === val) &&
                 this.modelValue.length === path.length + 1 &&
                 this.modelValue[path.length] === option.value;
+            const showArrow = this.loadingKeys.has(option.value)
+                ? false
+                : (option.children && option.children.length > 0) || (this.lazy && option.children === undefined && !option.leaf);
             return (h("li", { class: {
                     'hb-cascader__menu-item': true,
-                    'hb-cascader__menu-item--selected': isSelected || isInPath,
+                    'hb-cascader__menu-item--selected': isSelected,
                     'hb-cascader__menu-item--disabled': option.disabled,
-                }, role: "option", "aria-selected": (isSelected || isInPath) ? 'true' : 'false', "aria-disabled": option.disabled ? 'true' : undefined, onClick: () => !option.disabled && this.handleSelect(option.value, path) }, h("span", { class: "hb-cascader__menu-item-label" }, option.label), this.loadingKeys.has(option.value) ? (h("span", { class: "hb-cascader__menu-item-loading", "aria-hidden": "true" }, "\u27F3")) : (option.children && option.children.length > 0) || (this.lazy && option.children === undefined && !option.leaf) ? (h("span", { class: "hb-cascader__menu-item-arrow" }, "\u25B6")) : null));
+                }, role: "option", "aria-selected": isSelected ? 'true' : 'false', "aria-disabled": option.disabled ? 'true' : undefined, onClick: () => !option.disabled && this.handleItemClick(option, path) }, this.multiple && (h("span", { class: {
+                    'hb-cascader__menu-item-checkbox': true,
+                    'hb-cascader__menu-item-checkbox--checked': checkState === 'checked',
+                    'hb-cascader__menu-item-checkbox--indeterminate': checkState === 'indeterminate',
+                }, "data-state": checkState, role: "checkbox", "aria-checked": checkState === 'indeterminate' ? 'mixed' : checkState === 'checked' ? 'true' : 'false', onClick: e => {
+                    e.stopPropagation();
+                    if (!option.disabled)
+                        this.handleCheck(option, path);
+                } })), h("span", { class: "hb-cascader__menu-item-label" }, option.label), this.loadingKeys.has(option.value) ? (h("span", { class: "hb-cascader__menu-item-loading", "aria-hidden": "true" }, h("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": 2, "stroke-linecap": "round", "stroke-linejoin": "round", class: "hb-cascader__menu-item-loading-svg" }, h("path", { d: "M12 5V2L8 6l4 4V7a5 5 0 1 1-5 5H5a7 7 0 1 0 7-7z" })))) : showArrow ? (h("span", { class: "hb-cascader__menu-item-arrow", "aria-hidden": "true" }, h("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": 2, "stroke-linecap": "round", "stroke-linejoin": "round" }, h("path", { d: "M9 6l6 6-6 6" })))) : null));
         })));
     }
     static get is() { return "hb-cascader"; }
@@ -414,15 +574,21 @@ export class Cascader {
                 "type": "unknown",
                 "mutable": true,
                 "complexType": {
-                    "original": "(string | number)[]",
-                    "resolved": "(string | number)[]",
-                    "references": {}
+                    "original": "ValuePath | ValuePath[]",
+                    "resolved": "(string | number)[] | ValuePath[]",
+                    "references": {
+                        "ValuePath": {
+                            "location": "local",
+                            "path": "/Users/vscoderwhy/Desktop/product/web-common/huibo-ui/src/components/Cascader/Cascader.tsx",
+                            "id": "src/components/Cascader/Cascader.tsx::ValuePath"
+                        }
+                    }
                 },
                 "required": false,
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "\u9009\u4E2D\u9879\u7ED1\u5B9A\u503C"
+                    "text": "\u9009\u4E2D\u9879\u7ED1\u5B9A\u503C\u3002\u5355\u9009\u4E3A\u4E00\u7EF4\u8DEF\u5F84\u6570\u7EC4\uFF08\u5982 ['zhejiang','hangzhou']\uFF09\uFF0C\n\u591A\u9009\uFF08multiple\uFF09\u4E3A\u4E8C\u7EF4\u6570\u7EC4\uFF08\u5982 [['zhejiang','ningbo'], ['jiangsu']]\uFF09\u3002"
                 },
                 "getter": false,
                 "setter": false
@@ -482,10 +648,7 @@ export class Cascader {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [{
-                            "name": "default",
-                            "text": "false"
-                        }],
+                    "tags": [],
                     "text": "\u662F\u5426\u7981\u7528"
                 },
                 "getter": false,
@@ -525,10 +688,7 @@ export class Cascader {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [{
-                            "name": "default",
-                            "text": "false"
-                        }],
+                    "tags": [],
                     "text": "\u662F\u5426\u53EF\u6E05\u7A7A"
                 },
                 "getter": false,
@@ -548,11 +708,8 @@ export class Cascader {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [{
-                            "name": "default",
-                            "text": "true"
-                        }],
-                    "text": "\u662F\u5426\u663E\u793A\u5B8C\u6574\u8DEF\u5F84"
+                    "tags": [],
+                    "text": "\u662F\u5426\u663E\u793A\u5B8C\u6574\u8DEF\u5F84\uFF08\u5355\u9009\u8F93\u5165\u6846 / \u591A\u9009 tag \u6587\u672C\uFF09"
                 },
                 "getter": false,
                 "setter": false,
@@ -572,7 +729,7 @@ export class Cascader {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "\u8F93\u5165\u6846\u7684\u539F\u751F\u5C5E\u6027"
+                    "text": "\u8F93\u5165\u6846\u539F\u751F\u5C5E\u6027"
                 },
                 "getter": false,
                 "setter": false,
@@ -591,7 +748,7 @@ export class Cascader {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "\u8F93\u5165\u6846\u7684\u539F\u751F\u5C5E\u6027"
+                    "text": "\u8F93\u5165\u6846\u539F\u751F\u5C5E\u6027"
                 },
                 "getter": false,
                 "setter": false,
@@ -609,11 +766,8 @@ export class Cascader {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [{
-                            "name": "default",
-                            "text": "' / '"
-                        }],
-                    "text": "\u5206\u9694\u7B26"
+                    "tags": [],
+                    "text": "\u8DEF\u5F84\u5206\u9694\u7B26"
                 },
                 "getter": false,
                 "setter": false,
@@ -632,11 +786,8 @@ export class Cascader {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [{
-                            "name": "default",
-                            "text": "true"
-                        }],
-                    "text": "\u662F\u5426\u52A8\u6001\u52A0\u8F7D\u5B50\u8282\u70B9"
+                    "tags": [],
+                    "text": "modelValue \u662F\u5426\u8F93\u51FA\u5B8C\u6574\u8DEF\u5F84\uFF08\u4FDD\u7559 AntD \u517C\u5BB9\u4F4D\uFF09"
                 },
                 "getter": false,
                 "setter": false,
@@ -655,11 +806,8 @@ export class Cascader {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [{
-                            "name": "default",
-                            "text": "false"
-                        }],
-                    "text": "\u662F\u5426\u53EF\u641C\u7D22\uFF08filterable\uFF09\n\u5F00\u542F\u540E\u4E0B\u62C9\u9876\u90E8\u6E32\u67D3\u641C\u7D22\u8F93\u5165\u6846\uFF0C\u8F93\u5165\u65F6\u6309 label\uFF08\u542B\u6240\u6709\u5B50\u7EA7\uFF09\u6241\u5E73\u5316\u8FC7\u6EE4\uFF0C\n\u5339\u914D\u9879\u4EE5\u5B8C\u6574\u8DEF\u5F84\u5C55\u793A\uFF0C\u70B9\u51FB\u5373\u9009\u4E2D\u5176\u5B8C\u6574\u8DEF\u5F84\u3002"
+                    "tags": [],
+                    "text": "\u662F\u5426\u53EF\u641C\u7D22\uFF08filterable\uFF09\u3002\u4E0B\u62C9\u9876\u90E8\u6E32\u67D3\u641C\u7D22\u6846\uFF0C\u8F93\u5165\u65F6\u6309 label \u6241\u5E73\u5316\u8FC7\u6EE4\uFF0C\n\u5339\u914D\u9879\u4EE5\u5B8C\u6574\u8DEF\u5F84\u5C55\u793A\uFF0C\u70B9\u51FB\u5373\u9009\u4E2D\uFF08\u5355\u9009\uFF09\u6216 toggle \u52FE\u9009\uFF08\u591A\u9009\uFF09\u3002"
                 },
                 "getter": false,
                 "setter": false,
@@ -678,11 +826,8 @@ export class Cascader {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [{
-                            "name": "default",
-                            "text": "false"
-                        }],
-                    "text": "\u662F\u5426\u5F00\u542F\u52A8\u6001\u52A0\u8F7D\uFF08lazy load\uFF09\u3002\u5F00\u542F\u540E\uFF0C\u5C55\u5F00\u542B children=undefined \u7684\u8282\u70B9\u65F6\uFF0C\n\u8C03\u7528 load(node) \u83B7\u53D6\u5176\u5B50\u7EA7\u5E76\u586B\u5145\u8FDB options\uFF0C\u52A0\u8F7D\u4E2D\u663E\u793A loading \u6001\u3002"
+                    "tags": [],
+                    "text": "\u662F\u5426\u5F00\u542F\u52A8\u6001\u52A0\u8F7D\uFF08lazy\uFF09\u3002\u5C55\u5F00 children=undefined \u7684\u8282\u70B9\u65F6\u8C03\u7528 load(node) \u586B\u5145\u5B50\u7EA7\u3002"
                 },
                 "getter": false,
                 "setter": false,
@@ -712,10 +857,69 @@ export class Cascader {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "\u52A8\u6001\u52A0\u8F7D\u5B50\u8282\u70B9\u7684\u51FD\u6570\uFF08\u4EC5\u5728 lazy=true \u65F6\u751F\u6548\uFF09\u3002\n\u63A5\u6536\u88AB\u5C55\u5F00\u7684\u8282\u70B9\uFF0C\u8FD4\u56DE\u5176\u5B50\u8282\u70B9\u6570\u7EC4\uFF08Promise\uFF09\u3002\n\u52A0\u8F7D\u7ED3\u679C\u4F1A\u4EE5\u4E0D\u53EF\u53D8\u65B9\u5F0F\u5408\u5E76\u8FDB options \u6811\uFF08\u66FF\u6362\u8BE5\u8282\u70B9 children\uFF09\u3002"
+                    "text": "\u52A8\u6001\u52A0\u8F7D\u51FD\u6570\uFF08\u4EC5 lazy=true \u751F\u6548\uFF09"
                 },
                 "getter": false,
                 "setter": false
+            },
+            "multiple": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "\u662F\u5426\u5F00\u542F\u591A\u9009\u3002\u5F00\u542F\u540E modelValue \u4E3A\u4E8C\u7EF4\u6570\u7EC4\uFF0C\u6BCF\u6761\u4E3A\u4E00\u4E2A\u9009\u4E2D\u8DEF\u5F84\uFF1B\n\u83DC\u5355\u9879\u524D\u6E32\u67D3 checkbox\uFF0C\u8F93\u5165\u6846\u4EE5 tag \u5217\u8868\u5C55\u793A\u9009\u4E2D\u9879\u3002"
+                },
+                "getter": false,
+                "setter": false,
+                "attribute": "multiple",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "checkStrictly": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "\u662F\u5426\u4E25\u683C\u7684\u9009\u4E2D\u884C\u4E3A\uFF08\u7236\u5B50\u4E0D\u5173\u8054\uFF09\u3002\n\u5355\u9009\uFF1A\u70B9\u51FB\u4EFB\u610F\u5C42\u7EA7\uFF08\u542B\u975E\u53F6\u5B50\uFF09\u5373\u9009\u4E2D\u8BE5\u8DEF\u5F84\uFF1B\n\u591A\u9009\uFF1A\u52FE\u9009\u72EC\u7ACB\uFF0C\u4E0D\u5411\u4E0B\u8054\u52A8\u9009\u4E2D\u53F6\u5B50\u3001\u53D6\u6D88\u4E5F\u4E0D\u8054\u52A8\u3002"
+                },
+                "getter": false,
+                "setter": false,
+                "attribute": "check-strictly",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "maxTagCount": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "\u591A\u9009\u65F6\u8F93\u5165\u6846\u6700\u591A\u5C55\u793A\u7684 tag \u6570\u91CF\uFF0C\u8D85\u51FA\u6298\u53E0\u4E3A +N\uFF08\u53EF\u9009\uFF09\u3002"
+                },
+                "getter": false,
+                "setter": false,
+                "attribute": "max-tag-count",
+                "reflect": false
             }
         };
     }
@@ -738,12 +942,18 @@ export class Cascader {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": "\u503C\u6539\u53D8\u4E8B\u4EF6"
+                    "text": "\u503C\u6539\u53D8\u4E8B\u4EF6\uFF1A\u5355\u9009 emit \u4E00\u7EF4\u8DEF\u5F84\u6216 undefined\uFF1B\u591A\u9009 emit \u4E8C\u7EF4\u6570\u7EC4\uFF08\u53EF\u80FD\u4E3A []\uFF09"
                 },
                 "complexType": {
-                    "original": "(string | number)[] | undefined",
-                    "resolved": "(string | number)[]",
-                    "references": {}
+                    "original": "ValuePath | ValuePath[] | undefined",
+                    "resolved": "(string | number)[] | ValuePath[]",
+                    "references": {
+                        "ValuePath": {
+                            "location": "local",
+                            "path": "/Users/vscoderwhy/Desktop/product/web-common/huibo-ui/src/components/Cascader/Cascader.tsx",
+                            "id": "src/components/Cascader/Cascader.tsx::ValuePath"
+                        }
+                    }
                 }
             }, {
                 "method": "hbExpandChange",
@@ -753,12 +963,18 @@ export class Cascader {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": "\u5C55\u5F00\u8282\u70B9\u53D1\u751F\u53D8\u5316\u65F6\u89E6\u53D1"
+                    "text": "\u5C55\u5F00\u8282\u70B9\u53D8\u5316\u65F6\u89E6\u53D1"
                 },
                 "complexType": {
-                    "original": "(string | number)[]",
+                    "original": "ValuePath",
                     "resolved": "(string | number)[]",
-                    "references": {}
+                    "references": {
+                        "ValuePath": {
+                            "location": "local",
+                            "path": "/Users/vscoderwhy/Desktop/product/web-common/huibo-ui/src/components/Cascader/Cascader.tsx",
+                            "id": "src/components/Cascader/Cascader.tsx::ValuePath"
+                        }
+                    }
                 }
             }];
     }