@chenzy-design/svelte 0.3.0 → 0.4.1

package/dist/tree-select/TreeSelect.svelte

@@ -1,19 +1,17 @@
 <!--
-  TreeSelect — see specs/components/input/TreeSelect.spec.md
+  TreeSelect — 严格对齐 Semi Design treeSelect。
   基础子集: 单选、可展开/收起的单面板树、叶子或任意节点选中 (leafOnly 控制)。
   multiple: checkbox 多选 + 父子联动 (复用 core conduct/toggleCheck)，trigger 多 tag 回显可单独移除。
   filterable: 面板顶部搜索框过滤节点（复用 core computeFilteredKeys），命中 + 祖先链可见、命中文本高亮。
   Token-driven, a11y-correct, 受控/非受控。
-  fieldNames：自定义节点字段名（key/label/children）映射任意后端数据；派生只读标准化，默认字段名时零开销。
-  icon：自定义节点图标 snippet（showIcon 为真时渲染在 label 前），API 与 Tree 的 icon 对齐
-  （参数 { node, expanded, level }）。渲染层特性，不改 treeData（红线 #1）。
+  keyMaps：自定义节点字段名（key/label/value）映射任意后端数据；派生只读标准化，默认字段名时零开销。
   loadData：展开未加载的非叶子节点时异步取子节点，结果缓存进本地 SvelteMap 并派生合并树喂给
   所有 core 函数（不写回受控 treeData，红线 #1）；加载中显示 spinner，竞态由 loadedKeys/loadingKeys 去重。
-  virtualized：大数据树虚拟滚动。复用 Tree 范式——直接用 core fixedRange 纯函数自建轻量 fixed 定高
-  虚拟化（非复用 VirtualList 组件，其 role=list/listitem 会破坏 role=tree→treeitem 语义），保持
-  role=tree 容器 + 行 role=treeitem 不变；只渲染视口内切片（flattenVisible 派生扁平节点 + 区间纯派生，
-  红线 #2）。滚动监听命令式 + rAF 节流 + cleanup（红线 #3）。virtualized 时与搜索 filterable 互斥
-  （搜索强制展开命中链与定高虚拟化叠加复杂，故 virtualized 优先静态/异步大树场景）。
+  virtualize（对象形式，对齐 Semi）：大数据树虚拟滚动。复用 Tree 范式——直接用 core fixedRange 纯函数
+  自建轻量 fixed 定高虚拟化（非复用 VirtualList 组件，其 role=list/listitem 会破坏 role=tree→treeitem
+  语义），保持 role=tree 容器 + 行 role=treeitem 不变；只渲染视口内切片（flattenVisible 派生扁平节点 +
+  区间纯派生，红线 #2）。滚动监听命令式 + rAF 节流 + cleanup（红线 #3）。虚拟化时与搜索 filterable 互斥
+  （搜索强制展开命中链与定高虚拟化叠加复杂，故虚拟化优先静态/异步大树场景）。
 -->
 <script lang="ts">
   import type { Snippet } from 'svelte';
@@ -33,92 +31,112 @@
     type CheckedStrategy,
   } from '@chenzy-design/core';
   import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+  import {
+    IconTreeTriangleDown,
+    IconCheckboxTick,
+    IconCheckboxIndeterminate,
+    IconSearch,
+    IconClear,
+    IconChevronDown,
+  } from '@chenzy-design/icons';
   import { useLocale } from '../locale-provider/index.js';
   import { getGlobalPopupContainer } from '../config-provider/index.js';
   import { floating } from '../_floating/use-floating.js';
+  import type { Placement } from '@chenzy-design/core';
   import Tag from '../tag/Tag.svelte';
+  import Popover from '../popover/Popover.svelte';
   import type { TreeNode, TreeKey } from './types.js';
+  import { getInputGroupContext } from '../input/context.js';
 
   type Size = 'small' | 'default' | 'large';
   type Status = 'default' | 'warning' | 'error';
 
-  /** 自定义节点字段名映射（适配任意后端数据结构）。默认 key/label/children。 */
-  type FieldNames = { key?: string; label?: string; children?: string };
-
   interface Props {
     value?: TreeKey | TreeKey[] | null;
     defaultValue?: TreeKey | TreeKey[] | null;
     /**
      * 树数据源。默认节点字段为 key/label/children；
-     * 用 fieldNames 自定义字段名时可传任意后端结构（如 { id, name, sub }）。
+     * 用 keyMaps 自定义字段名时可传任意后端结构（如 { id, name }）。
      */
     treeData?: TreeNode[];
-    /** 自定义节点字段名映射，如 { key:'id', label:'name', children:'sub' }。默认全部为标准名。 */
-    fieldNames?: FieldNames;
-    open?: boolean;
     defaultOpen?: boolean;
     /** 多选：面板节点显示 checkbox + 父子联动，trigger 多 tag 回显 */
     multiple?: boolean;
-    /** 多选时父子勾选互不影响（无半选） */
-    checkStrictly?: boolean;
     /**
-     * 多选父子是否级联联动（对齐 Tree）。'related'（默认）父子联动；
-     * 'unRelated' 互不影响（等价 checkStrictly）。checkStrictly=true 强制 unRelated（向后兼容）。
+     * 多选父子是否级联联动（对齐 Semi/Tree）。'related'（默认）父子联动；
+     * 'unRelated' 互不影响（勾选无半选）。
      */
     checkRelation?: 'related' | 'unRelated';
-    /**
-     * 多选回填值 / Tag 的收敛策略：'all'（默认，全部勾选节点）、
-     * 'parent'（完全勾选父级折叠为父）、'child'（仅叶子）。仅 related 级联时生效。
-     */
-    showCheckedStrategy?: CheckedStrategy;
     /** 多选回填 Tag 最大展示数，超出折叠为 +N（仅影响显示，不改 value）。 */
     maxTagCount?: number;
     placeholder?: string;
     size?: Size;
     status?: Status;
     disabled?: boolean;
-    clearable?: boolean;
+    /** 值不为空时 trigger 展示清除按钮（对齐 Semi showClear）。 */
+    showClear?: boolean;
     leafOnly?: boolean;
     defaultExpandAll?: boolean;
-    /** 默认展开的节点 key（非受控初始展开集，与 defaultExpandAll 取并集）。 */
-    treeDefaultExpandedKeys?: TreeKey[];
+    /** 默认展开的节点 key（非受控初始展开集，与 defaultExpandAll 取并集；对齐 Semi defaultExpandedKeys）。 */
+    defaultExpandedKeys?: TreeKey[];
     /** 面板顶部搜索框过滤节点（命中 + 祖先链可见、高亮命中文本） */
     filterable?: boolean;
+    /**
+     * 是否按输入筛选节点（对齐 Semi filterTreeNode）：
+     * true 开启搜索框，默认对 treeNodeFilterProp（默认 'label'）做大小写不敏感包含匹配；
+     * 传函数则用作自定义匹配谓词 (inputValue, treeNodeString, data?) => boolean，
+     * treeNodeString 为按 treeNodeFilterProp 取到的节点文本，data 为节点原始数据。
+     * 与 filterable 二者其一为真即显示搜索框。
+     */
+    filterTreeNode?: boolean | ((inputValue: string, treeNodeString: string, data?: TreeNode) => boolean);
     /**
      * 远程搜索：输入仅触发 onSearch（防抖后），不本地过滤（由外部更新 treeData）。
      * 隐含 filterable 行为（显示搜索框）。默认 false。
      */
     remote?: boolean;
-    /** onSearch 防抖毫秒（remote 时生效，默认 300）。 */
-    searchDebounce?: number;
-    /** 远程搜索输入回调（防抖后）。 */
-    onSearch?: (query: string) => void;
-    /** 是否预留节点图标位（icon 提供时渲染在 label 前）。默认 true，与 Tree 对齐。 */
-    showIcon?: boolean;
+    /**
+     * 搜索输入回调（对齐 Semi onSearch）：入参为当前输入、过滤后应展开的节点 keys、命中节点数组。
+     * remote 时用于外部更新 treeData；本地过滤时可配合 expandedKeys 受控搜索展开。
+     */
+    onSearch?: (input: string, filteredExpandedKeys: TreeKey[], filteredNodes: TreeNode[]) => void;
     /** 异步加载子节点：展开未加载的非叶子节点时调用，返回该节点的子节点数组。与 Tree 的 loadData 对齐。 */
     loadData?: (node: TreeNode) => Promise<TreeNode[]>;
-    /** 虚拟滚动：仅渲染视口内的可见节点行，适合大数据树（1000+ 节点）。默认 false（行为不变）。 */
-    virtualized?: boolean;
     /**
-     * 自动启用虚拟化的可见节点数阈值：可见扁平行数 ≥ 此值时自动开启虚拟化。
-     * 默认 100。virtualized 显式为 true 时强制开启（不看阈值）。
+     * 列表虚拟化（对齐 Semi）：仅渲染视口内可见节点行，适合大数据树（1000+ 节点）。
+     * 传入对象即显式开启；height 视口高度（默认 224）、itemSize 行高（默认 32）、width 宽度。
      */
-    virtualizeThreshold?: number;
+    virtualize?: { height?: number; width?: number | string; itemSize?: number };
+    /** 浮层弹出位置（对齐 Semi，参考 Tooltip position）。默认 bottomLeft。 */
+    position?: string;
     /** 浮层宽度对齐触发器（min-inline-size = 触发器宽）。默认 true。 */
     dropdownMatchSelectWidth?: boolean;
     /** 浮层挂载容器，缺省 ConfigProvider 全局值再回退 document.body。 */
     getPopupContainer?: () => HTMLElement | null | undefined;
-    /** 关闭即从 DOM 卸载浮层（重开重建）。默认 false：首开后保留 DOM 仅隐藏。 */
-    destroyOnClose?: boolean;
-    /** 虚拟滚动视口高度（px）。virtualized 时生效，默认 224（与默认面板 max-height 一致）。 */
-    height?: number;
-    /** 虚拟滚动行高（px）。virtualized 时生效，默认取 token 行高 32。 */
-    itemHeight?: number;
     onChange?: (value: TreeKey | TreeKey[] | null) => void;
-    onOpenChange?: (open: boolean) => void;
     ariaLabel?: string;
-    /** 自定义节点图标（showIcon 为真时渲染在 label 前）；参数含节点与展开态，与 Tree 的 icon 对齐。 */
-    icon?: Snippet<[{ node: TreeNode; expanded: boolean; level: number }]>;
+    /** aria-labelledby：关联外部 label 元素（Form.Field 透传 labelId，对齐 Semi）。 */
+    ariaLabelledby?: string;
+    /** aria-describedby：关联 helpText / extraText（Form.Field 透传）。 */
+    ariaDescribedby?: string;
+    /** aria-errormessage：error 态关联错误信息容器（Form.Field 透传）。 */
+    ariaErrormessage?: string;
+    /** aria-required：必填语义（Form.Field required 透传）。 */
+    ariaRequired?: boolean;
+    /** 触发器点击是否阻止事件冒泡（对齐 Semi stopPropagation）。默认 true。 */
+    stopPropagation?: boolean;
+    /**
+     * 完全自定义触发器渲染（替换默认选择框）。与 Cascader.triggerRender 对齐：
+     * 参数含当前 value / placeholder / isOpen / disabled，由使用方决定如何呈现。
+     */
+    triggerRender?: Snippet<[{ value: TreeKey | TreeKey[] | null | undefined; placeholder: string; isOpen: boolean; disabled: boolean }]>;
+    /** 触发器内嵌标签：渲染在回填值/占位符之前（Snippet 或字符串）。对齐 Semi insetLabel。 */
+    insetLabel?: Snippet | string;
+    /** 内嵌标签的 id（a11y 关联用），对齐 Semi insetLabelId。 */
+    insetLabelId?: string;
+    /** 下拉浮层开合动画（淡入）。默认 true。与 Cascader/Dropdown 的 motion 对齐。 */
+    motion?: boolean;
+    // 注：Semi 的 mouseEnterDelay/mouseLeaveDelay 属 hover 触发浮层的进入/离开延迟；
+    // TreeSelect 为 click 触发（点击 trigger 开合），无 hover 触发路径，故此两项不适用，不提供。
 
     // --- Appearance ---
     /** 无边框模式：trigger 边框透明。默认 false。 */
@@ -172,6 +190,18 @@
     showSearchClear?: boolean;
     /** 搜索激活时仅显示命中节点，不显示祖先链。默认 false。 */
     showFilteredOnly?: boolean;
+    /**
+     * 无匹配/无数据时的占位内容（对齐 Semi emptyContent）：字符串或 Snippet。
+     * 未传时回退 i18n TreeSelect.emptyText。空 Snippet 场景可传 () => {} 自绘。
+     */
+    emptyContent?: string | Snippet;
+    /**
+     * 自定义搜索框渲染（渲染层扩展，非 Semi 原生 TreeSelect prop）：
+     * false 隐藏搜索框（即使 filterable/filterTreeNode 开启，也不显示内置搜索输入）；
+     * 传 Snippet 则完全接管搜索框渲染，参数含当前值与命令式回调，
+     * 使用方需自行把输入回填给 onInput（其余过滤/高亮/roving 逻辑不变）。
+     */
+    searchRender?: boolean | Snippet<[{ value: string; onInput: (v: string) => void; onKeydown: (e: KeyboardEvent) => void; placeholder: string }]>;
 
     // --- Expand control ---
     /** 受控展开的节点 keys */
@@ -189,15 +219,15 @@
 
     // --- Multi-select enhancements ---
     /**
-     * 自动合并值：父节点全选时 value 不再包含其后代（等价 showCheckedStrategy='parent'）。
-     * 默认 true。autoMergeValue=false 时 showCheckedStrategy 原始生效。
+     * 自动合并值：父节点全选时 value 不再包含其后代（收敛为父，对齐 Semi autoMergeValue）。
+     * 默认 true。false 时 value 含全部勾选叶子与父（'all' 策略）。leafOnly 时改为仅叶子（'child'）。
      */
     autoMergeValue?: boolean;
     /** onChange 回调携带完整节点对象而非仅 key。默认 false。 */
     onChangeWithObject?: boolean;
-    /** 超出 maxTagCount 折叠的 tag 以 popover 形式展示剩余项。默认 false。 */
+    /** 多选 maxTagCount 折叠出 +N 时，hover +N 用本库 Popover 浮层展示折叠掉的剩余全部 Tag。默认 false（静态 +N）。 */
     showRestTagsPopover?: boolean;
-    /** 传给剩余 tags popover 的额外 props。 */
+    /** 透传给剩余 Tag Popover 浮层的额外 props（在默认 trigger=hover/position=top 之后展开，可覆盖）。 */
     restTagsPopoverProps?: Record<string, unknown>;
     /** trigger 多选 tags 换行显示（默认单行截断折叠）。默认 false。 */
     triggerTagWrap?: boolean;
@@ -211,8 +241,8 @@
     renderSelectedItem?: Snippet<[{ node: TreeNode; onRemove: () => void }]>;
     /** 节点数据中用作显示 label 的字段名（默认 'label'）。 */
     treeNodeLabelProp?: string;
-    /** 自定义 key/label/value 字段映射（优先级高于 fieldNames 的 key/label 部分）。 */
-    keyMaps?: { key?: string; label?: string; value?: string };
+    /** 自定义节点字段名映射（对齐 Semi keyMaps）：适配任意后端数据结构，如 { key:'id', label:'name', children:'sub' }。 */
+    keyMaps?: { key?: string; label?: string; value?: string; children?: string };
     /** 选项列表容器的内联 style（字符串或对象形式）。 */
     optionListStyle?: string | Record<string, string>;
     /** 受控已加载的节点 keys */
@@ -228,8 +258,14 @@
      * 默认 false（父禁用 conduct 不检查子）。
      */
     disableStrictly?: boolean;
-    /** 浮层与 trigger 的额外间距（px），数字或四方向对象。 */
+    /** 浮层与 trigger 的额外间距（px），数字或四方向对象。数字映射到浮层 offset；对象形态仅取 marginTop（其余方向暂未接入定位）。 */
     dropdownMargin?: number | { marginTop?: number; marginBottom?: number; marginLeft?: number; marginRight?: number };
+    /** 追加到浮层根节点的自定义类名（与内置类名并存）。 */
+    dropdownClassName?: string;
+    /** 合并进浮层根节点的内联样式（与内置定位样式拼接，不覆盖 use:floating 写入的 transform/position）。 */
+    dropdownStyle?: string | Record<string, string>;
+    /** 浮层层级（z-index）。未传时由 CSS 层级控制。 */
+    zIndex?: number;
 
     // --- Events ---
     /** 点击清除按钮回调。 */
@@ -238,7 +274,7 @@
     onSelect?: (selectedKey: TreeKey, selected: boolean, node: unknown) => void;
     /** 异步加载完成回调（含已加载 key 集合与当前节点）。 */
     onLoad?: (loadedKeys: TreeKey[], treeNode: TreeNode) => void;
-    /** 面板可见性变化回调（与 onOpenChange 语义相同，Semi 风格别名）。 */
+    /** 面板可见性变化回调（对齐 Semi onVisibleChange）。 */
     onVisibleChange?: (isVisible: boolean) => void;
   }
 
@@ -246,39 +282,38 @@
     value,
     defaultValue = null,
     treeData = [],
-    fieldNames,
-    open,
     defaultOpen = false,
     multiple = false,
-    checkStrictly = false,
     checkRelation = 'related',
-    showCheckedStrategy = 'all',
     maxTagCount,
     placeholder = '请选择',
-    size = 'default',
+    size: sizeProp,
     status = 'default',
-    disabled = false,
-    clearable = false,
+    disabled: disabledProp,
+    showClear = false,
     leafOnly = false,
     defaultExpandAll = false,
-    treeDefaultExpandedKeys,
+    defaultExpandedKeys,
     filterable = false,
+    filterTreeNode,
     remote = false,
-    searchDebounce = 300,
     onSearch,
-    showIcon = true,
     loadData,
-    virtualized = false,
-    virtualizeThreshold = 100,
+    virtualize,
+    position = 'bottomLeft',
     dropdownMatchSelectWidth = true,
     getPopupContainer,
-    destroyOnClose = false,
-    height = 224,
-    itemHeight = 32,
     onChange,
-    onOpenChange,
     ariaLabel,
-    icon,
+    ariaLabelledby,
+    ariaDescribedby,
+    ariaErrormessage,
+    ariaRequired,
+    stopPropagation = true,
+    triggerRender,
+    insetLabel,
+    insetLabelId,
+    motion = true,
     borderless = false,
     prefix,
     suffix,
@@ -301,6 +336,8 @@
     treeNodeFilterProp = 'label',
     showSearchClear = true,
     showFilteredOnly = false,
+    emptyContent,
+    searchRender,
     expandedKeys: expandedKeysProp,
     expandAll = false,
     expandAction = false,
@@ -323,39 +360,66 @@
     clickTriggerToHide = true,
     disableStrictly = false,
     dropdownMargin,
+    dropdownClassName,
+    dropdownStyle,
+    zIndex,
     onClear,
     onSelect,
     onLoad,
     onVisibleChange,
   }: Props = $props();
 
+  // InputGroup 组级默认（size/disabled）：显式 prop 始终优先，否则回退组级，再回退组件默认。
+  const group = getInputGroupContext();
+  const size = $derived<Size>(sizeProp ?? group?.size ?? 'default');
+  const disabled = $derived<boolean>(disabledProp ?? group?.disabled ?? false);
+
   const loc = useLocale();
   // ConfigProvider 全局浮层容器默认；自身 getPopupContainer prop 优先，未传时回退此值（再回退 body）。
   const globalPopupContainer = getGlobalPopupContainer();
   const resolvePopupContainer = $derived(getPopupContainer ?? globalPopupContainer);
 
-  // remote 隐含可搜索（显示搜索框）；checkRelation 归一：checkStrictly=true 强制 unRelated（向后兼容）。
-  const isFilterable = $derived(filterable || remote);
-  const isUnRelated = $derived(checkStrictly || checkRelation === 'unRelated');
+  // remote 隐含可搜索（显示搜索框）；filterTreeNode（bool 或函数）亦开启搜索。
+  const isFilterable = $derived(filterable || remote || filterTreeNode === true || typeof filterTreeNode === 'function');
+  const isUnRelated = $derived(checkRelation === 'unRelated');
 
   // validateStatus 是 status 别名；效值以 validateStatus 优先（未传时回退 status）。
   const effStatus = $derived(validateStatus ?? status ?? 'default');
 
   const treeId = useId('cd-tree-select-panel');
+
+  // 浮层与触发器间距：dropdownMargin 数字直接作 offset；对象形态取 marginTop（其余方向暂未接入）；未传回退默认 4。
+  const dropdownOffset = $derived.by(() => {
+    if (dropdownMargin == null) return 4;
+    if (typeof dropdownMargin === 'number') return dropdownMargin;
+    return dropdownMargin.marginTop ?? 4;
+  });
+
+  // 浮层自定义样式：合并 dropdownStyle（字符串或对象）与 zIndex，供拼接到浮层 inline style。
+  const dropdownStyleStr = $derived.by(() => {
+    const parts: string[] = [];
+    if (dropdownStyle) {
+      if (typeof dropdownStyle === 'string') parts.push(dropdownStyle);
+      else parts.push(Object.entries(dropdownStyle).map(([k, v]) => `${k}: ${v}`).join('; '));
+    }
+    if (zIndex != null) parts.push(`z-index: ${zIndex}`);
+    return parts.filter(Boolean).join('; ');
+  });
+
   // treeitem 行 id 基（aria-activedescendant 指向当前高亮行）。
   const itemBaseId = useId('cd-tree-select-item');
   function itemId(key: TreeKey): string {
     return `${itemBaseId}-${String(key)}`;
   }
 
-  // --- fieldNames 字段映射：把用户自定义字段名的数据派生为标准 {key,label,children} 结构 ---
+  // --- keyMaps 字段映射：把用户自定义字段名的数据派生为标准 {key,label,children} 结构（对齐 Semi keyMaps）---
   // 默认（全标准名）时直接返回原 treeData 引用，零额外开销；映射为纯 $derived（红线 #2），不写回（红线 #1）。
   // 节点 key 取自原始 key 字段，故 onChange 回传的 value（key）即用户原始 id，无需额外映射回原节点。
-  // keyMaps 优先级高于 fieldNames（key/label 部分）；keyMaps.value 作为 key 字段别名。
-  const keyField = $derived(keyMaps?.key ?? keyMaps?.value ?? fieldNames?.key ?? 'key');
-  const labelField = $derived(keyMaps?.label ?? fieldNames?.label ?? 'label');
-  const childrenField = $derived(fieldNames?.children ?? 'children');
-  const fieldNamesDefault = $derived(
+  // keyMaps.value 作为 key 字段别名（对齐 Semi）。
+  const keyField = $derived(keyMaps?.key ?? keyMaps?.value ?? 'key');
+  const labelField = $derived(keyMaps?.label ?? 'label');
+  const childrenField = $derived(keyMaps?.children ?? 'children');
+  const keyMapsDefault = $derived(
     keyField === 'key' && labelField === 'label' && childrenField === 'children',
   );
 
@@ -384,7 +448,7 @@
 
   // 标准化后的树：默认时即 treeData 原引用（零开销），否则递归映射字段名。
   const normalizedTree = $derived<TreeNode[]>(
-    fieldNamesDefault ? treeData : normalizeNodes(treeData),
+    keyMapsDefault ? treeData : normalizeNodes(treeData),
   );
 
   // --- 异步加载（对齐 Tree）：本地缓存子节点 + loading/loaded 标记（不写回受控 treeData，红线 #1）---
@@ -413,7 +477,7 @@
     loadingKeys.add(node.key);
     try {
       const kids = await loadData(node);
-      loadedChildren.set(node.key, fieldNamesDefault ? kids : normalizeNodes(kids));
+      loadedChildren.set(node.key, keyMapsDefault ? kids : normalizeNodes(kids));
     } finally {
       loadingKeys.delete(node.key);
       loadedKeys.add(node.key);
@@ -460,11 +524,11 @@
     return defaultOpen;
   }
   function getInitialExpanded(): Set<TreeKey> {
-    // treeDefaultExpandedKeys 与 defaultExpandAll 取并集（非受控初始展开集）。
-    const set = new Set<TreeKey>(treeDefaultExpandedKeys ?? []);
+    // defaultExpandedKeys 与 defaultExpandAll 取并集（非受控初始展开集）。
+    const set = new Set<TreeKey>(defaultExpandedKeys ?? []);
     if (defaultExpandAll) {
-      // defaultExpandAll 需用标准化后的 key（fieldNames 自定义时才能识别 children）。
-      const base = fieldNamesDefault ? treeData : normalizeNodes(treeData);
+      // defaultExpandAll 需用标准化后的 key（keyMaps 自定义时才能识别 children）。
+      const base = keyMapsDefault ? treeData : normalizeNodes(treeData);
       for (const k of collectExpandable(base, [])) set.add(k);
     }
     return set;
@@ -491,13 +555,10 @@
     if (isUnRelated) return { checked: new Set(currentCheckedBase), half: new Set<TreeKey>() };
     return conduct(mergedTree as unknown as TreeNodeData[], currentCheckedBase);
   });
-  // autoMergeValue=true 时把 showCheckedStrategy='all' 升级为 'parent'（父选不含后代）。
+  // 回填值/Tag 收敛策略（对齐 Semi，由 leafOnly + autoMergeValue 组合表达，无独立 showCheckedStrategy）：
+  // leafOnly → 'child'（仅叶子）；否则 autoMergeValue=true → 'parent'（父全选折叠为父，value 不含后代）；否则 'all'。
   const effectiveStrategy = $derived<CheckedStrategy>(
-    !autoMergeValue
-      ? showCheckedStrategy
-      : showCheckedStrategy === 'all'
-        ? 'parent'
-        : showCheckedStrategy,
+    leafOnly ? 'child' : autoMergeValue ? 'parent' : 'all',
   );
 
   // 回填值/Tag 收敛集（effectiveStrategy）：unRelated 无父子关系故策略不生效（取全 checked）。
@@ -535,19 +596,24 @@
       ? Math.max(0, checkedNodes.length - maxTagCount)
       : 0,
   );
+  // showRestTagsPopover：+N hover 时浮层展示的隐藏剩余节点（折叠掉的那部分）。
+  const hiddenTagNodes = $derived(
+    maxTagCount !== undefined && maxTagCount >= 0
+      ? checkedNodes.slice(maxTagCount)
+      : [],
+  );
 
-  // --- 受控 open (红线 #1): 不无条件回写 open，仅 onOpenChange ---
-  const isOpenControlled = $derived(open !== undefined);
+  // --- 非受控 open（对齐 Semi：仅 defaultOpen 初始 + onVisibleChange 回调，无受控 open prop）---
   let innerOpen = $state(getInitialOpen());
-  const isOpen = $derived(isOpenControlled ? !!open : innerOpen);
-
-  // onVisibleChange 是 onOpenChange 别名：isOpen 变化时同步触发。
-  $effect(() => {
-    onVisibleChange?.(isOpen);
-  });
-
-  // --- 本地展开状态 (红线 #2): expandedKeys 本地 $state Set，不依赖挂载 registry ---
-  let expandedKeys = $state<Set<TreeKey>>(getInitialExpanded());
+  const isOpen = $derived(innerOpen);
+
+  // --- 展开状态：受控（传入 expandedKeys）时只读派生 + onExpand 回调（红线 #1 不回写）；
+  //     非受控时本地 $state Set（红线 #2，不依赖挂载 registry）。 ---
+  const isExpandControlled = $derived(expandedKeysProp !== undefined);
+  let innerExpanded = $state<Set<TreeKey>>(getInitialExpanded());
+  const expandedKeys = $derived<Set<TreeKey>>(
+    isExpandControlled ? new Set(expandedKeysProp) : innerExpanded,
+  );
 
   const selectedNode = $derived(
     currentValue === null ? undefined : findNode(mergedTree, currentValue),
@@ -556,7 +622,22 @@
   const hasSelection = $derived(
     multiple ? checkedNodes.length > 0 : selectedNode !== undefined,
   );
-  const showClear = $derived(clearable && !disabled && hasSelection);
+  const showClearBtn = $derived(showClear && !disabled && hasSelection);
+
+  // position → use:floating 的 Placement（对齐 Semi，映射表照 DatePicker），缺省 bottomStart。
+  const POSITION_TO_PLACEMENT: Record<string, Placement> = {
+    bottomLeft: 'bottomStart',
+    bottomRight: 'bottomEnd',
+    bottom: 'bottom',
+    topLeft: 'topStart',
+    topRight: 'topEnd',
+    top: 'top',
+    leftTop: 'leftStart',
+    leftBottom: 'leftEnd',
+    rightTop: 'rightStart',
+    rightBottom: 'rightEnd',
+  };
+  const dropdownPlacement = $derived<Placement>(POSITION_TO_PLACEMENT[position] ?? 'bottomStart');
 
   function setValue(next: TreeKey | null) {
     if (!isValueControlled) innerValue = next;
@@ -588,7 +669,7 @@
       if (nextBase.has(node.key)) nextBase.delete(node.key);
       else nextBase.add(node.key);
     } else {
-      nextBase = toggleCheck(mergedTree as unknown as TreeNodeData[], currentCheckedBase, node.key);
+      nextBase = toggleCheck(mergedTree as unknown as TreeNodeData[], currentCheckedBase, node.key, disableStrictly);
     }
     setChecked(nextBase);
   }
@@ -603,7 +684,7 @@
       setChecked(next);
     } else if (isChecked) {
       // 复用 toggleCheck：已选 → 取消（含子树联动）
-      setChecked(toggleCheck(mergedTree as unknown as TreeNodeData[], currentCheckedBase, node.key));
+      setChecked(toggleCheck(mergedTree as unknown as TreeNodeData[], currentCheckedBase, node.key, disableStrictly));
     }
   }
 
@@ -617,12 +698,13 @@
   function setOpen(next: boolean) {
     if (next === isOpen) return;
     if (!next) searchValue = '';
-    if (!isOpenControlled) innerOpen = next;
-    onOpenChange?.(next);
+    innerOpen = next;
     onVisibleChange?.(next);
   }
 
-  function toggleOpen() {
+  function toggleOpen(e: MouseEvent) {
+    // stopPropagation（对齐 Semi，默认 true）：阻止 trigger 点击冒泡到外层。
+    if (stopPropagation) e.stopPropagation();
     if (disabled) return;
     if (isOpen && !clickTriggerToHide) return;
     setOpen(!isOpen);
@@ -646,13 +728,27 @@
   const trimmedSearch = $derived(searchValue.trim());
   // remote 模式不本地过滤（外部更新 treeData），仅本地 filterable 时高亮/收敛命中链。
   const searchActive = $derived(!remote && isFilterable && trimmedSearch.length > 0);
+  // 按 treeNodeFilterProp 取节点用于匹配的文本（默认 label；自定义字段回退 label）。
+  function nodeFilterText(node: TreeNodeData): string {
+    const raw = (node as unknown as Record<string, unknown>)[treeNodeFilterProp];
+    const v = raw ?? node.label;
+    return v == null ? '' : String(v);
+  }
   const filterResult = $derived.by(() => {
     if (!searchActive) return { matched: new Set<TreeKey>(), expand: new Set<TreeKey>() };
     const lower = trimmedSearch.toLowerCase();
-    return computeFilteredKeys(
-      mergedTree as unknown as TreeNodeData[],
-      (node) => node.label.toLowerCase().includes(lower),
-    );
+    // filterTreeNode 为函数时用作自定义匹配谓词（inputValue, treeNodeString, data?）；
+    // 否则默认对 treeNodeFilterProp 文本做大小写不敏感包含匹配。
+    const predicate =
+      typeof filterTreeNode === 'function'
+        ? (node: TreeNodeData) =>
+            (filterTreeNode as (i: string, s: string, d?: TreeNode) => boolean)(
+              trimmedSearch,
+              nodeFilterText(node),
+              node as unknown as TreeNode,
+            )
+        : (node: TreeNodeData) => nodeFilterText(node).toLowerCase().includes(lower);
+    return computeFilteredKeys(mergedTree as unknown as TreeNodeData[], predicate);
   });
   // 节点在搜索结果可见：命中本身、或在祖先链/含命中后代（expand 集）。
   // showFilteredOnly=true 时只显示精确命中节点，不显示祖先链。
@@ -663,8 +759,8 @@
   }
 
   function isExpanded(key: TreeKey): boolean {
-    // 搜索激活时强制展开命中链
-    if (searchActive && filterResult.expand.has(key)) return true;
+    // 搜索激活时强制展开命中链（对齐 Semi：展开受控时不再自动展开，完全由 expandedKeys 控制）。
+    if (!isExpandControlled && searchActive && filterResult.expand.has(key)) return true;
     return expandedKeys.has(key);
   }
 
@@ -683,28 +779,20 @@
         }
       };
       walk(mergedTree);
-      // 同时并入搜索展开链。
-      if (searchActive) for (const k of filterResult.expand) set.add(k);
+      // 同时并入搜索展开链（受控展开时不自动展开）。
+      if (!isExpandControlled && searchActive) for (const k of filterResult.expand) set.add(k);
       return set;
     }
-    if (!searchActive) return expandedKeys;
+    // 受控展开时不并入搜索展开链（对齐 Semi），完全由 expandedKeys 控制。
+    if (!searchActive || isExpandControlled) return expandedKeys;
     const merged = new Set(expandedKeys);
     for (const k of filterResult.expand) merged.add(k);
     return merged;
   });
-  // virtualizeThreshold：节点总数 ≥ 阈值时自动启用虚拟化（virtualized=true 时强制启用）。
-  const totalNodeCount = $derived.by(() => {
-    let n = 0;
-    const walk = (nodes: TreeNode[]) => {
-      for (const node of nodes) {
-        n++;
-        if (node.children) walk(node.children);
-      }
-    };
-    walk(mergedTree);
-    return n;
-  });
-  const useVirtual = $derived(virtualized || totalNodeCount >= virtualizeThreshold);
+  // virtualize 对象归一（对齐 Semi）：传入对象即显式开启（无自动阈值）；height 视口高度、itemSize 行高。
+  const height = $derived(virtualize?.height ?? 224);
+  const itemHeight = $derived(virtualize?.itemSize ?? 32);
+  const useVirtual = $derived(virtualize !== undefined);
   // 可见扁平节点：虚拟化用于视口切片，非虚拟化也用于键盘 roving 导航（红线 #2 纯派生）。
   const flat = $derived(
     flattenVisible(mergedTree as unknown as TreeNodeData[], effectiveExpanded),
@@ -794,7 +882,8 @@
   function toggleExpand(node: TreeNode) {
     const key = node.key;
     const next = new Set(expandedKeys);
-    if (next.has(key)) {
+    const willExpand = !next.has(key);
+    if (!willExpand) {
       next.delete(key);
     } else {
       next.add(key);
@@ -816,7 +905,9 @@
       // 展开未加载的异步节点：先取数据（数据到位后合并树派生即显示子节点）。
       if (!hasChildren(node) && loadData && !loadedKeys.has(key)) void loadChildren(node);
     }
-    expandedKeys = next;
+    // 受控展开（红线 #1）：只回调 onExpand，不回写本地态；非受控写本地态。
+    if (!isExpandControlled) innerExpanded = next;
+    onExpand?.([...next], { expanded: willExpand, node });
   }
 
   function selectNode(node: TreeNode) {
@@ -980,34 +1071,80 @@
     scrollActiveIntoView();
   }
 
-  // --- remote 搜索防抖（命令式定时器 + cleanup，红线 #3）---
-  let searchTimer: ReturnType<typeof setTimeout> | undefined;
-  function scheduleSearch(q: string) {
-    if (searchTimer !== undefined) clearTimeout(searchTimer);
-    searchTimer = setTimeout(() => {
-      searchTimer = undefined;
-      onSearch?.(q);
-    }, Math.max(0, searchDebounce));
+  // --- onSearch（对齐 Semi 三入参签名 (input, filteredExpandedKeys, filteredNodes)）---
+  // 无内置防抖：Semi 也不做防抖，remote 场景由使用方在 onSearch 内自行节流。
+  // 对任意输入即时计算过滤结果（不受 remote/searchActive gate 限制），供回调的后两参。
+  function emitSearch(input: string) {
+    if (!onSearch) return;
+    const q = input.trim();
+    if (q.length === 0) {
+      onSearch(input, [], []);
+      return;
+    }
+    const lower = q.toLowerCase();
+    const predicate =
+      typeof filterTreeNode === 'function'
+        ? (node: TreeNodeData) =>
+            (filterTreeNode as (i: string, s: string, d?: TreeNode) => boolean)(
+              q,
+              nodeFilterText(node),
+              node as unknown as TreeNode,
+            )
+        : (node: TreeNodeData) => nodeFilterText(node).toLowerCase().includes(lower);
+    const res = computeFilteredKeys(mergedTree as unknown as TreeNodeData[], predicate);
+    // filteredExpandedKeys：命中链上应展开的祖先节点 keys（对齐 Semi filteredExpandedKeys）。
+    const filteredExpandedKeys = [...res.expand];
+    // filteredNodes：命中节点原始数据数组（树序）。
+    const filteredNodes: TreeNode[] = [];
+    const walk = (nodes: TreeNode[]) => {
+      for (const n of nodes) {
+        if (res.matched.has(n.key)) filteredNodes.push(n);
+        if (n.children) walk(n.children);
+      }
+    };
+    walk(mergedTree);
+    onSearch(input, filteredExpandedKeys, filteredNodes);
   }
-  // 卸载兜底清理。
-  $effect(() => () => {
-    if (searchTimer !== undefined) clearTimeout(searchTimer);
-  });
   function onSearchInput(e: Event & { currentTarget: HTMLInputElement }) {
     searchValue = e.currentTarget.value;
-    if (remote) scheduleSearch(searchValue.trim());
+    emitSearch(searchValue);
+  }
+  // searchRender 自定义搜索框用的命令式回调（把外部输入回填给内部搜索态）。
+  function setSearchValue(v: string) {
+    searchValue = v;
+    emitSearch(v);
+  }
+
+  /** 命令式搜索：把值置给内部搜索态并触发过滤（对齐 Semi search(sugInput)，用于外部自定义搜索框）。 */
+  export function search(sugInput: string): void {
+    setSearchValue(sugInput);
+  }
+  // 内置搜索框键盘处理（Escape 关闭，其余交给树 roving）。
+  function onSearchKeydown(e: KeyboardEvent) {
+    if (e.key === 'Escape') {
+      setOpen(false);
+      return;
+    }
+    onTreeKeydown(e);
   }
+  // searchRender=false 时隐藏内置搜索框（即使 filterable/filterTreeNode 开启）。
+  const showBuiltinSearch = $derived(isFilterable && searchRender !== false);
+  // searchPosition：'dropdown'（默认）搜索框在浮层顶部；'trigger' 搜索框内嵌触发器（对齐 Semi）。
+  const searchInDropdown = $derived(showBuiltinSearch && searchPosition !== 'trigger');
+  const searchInTrigger = $derived(showBuiltinSearch && searchPosition === 'trigger');
+  // 搜索框占位文案：searchPlaceholder prop 优先，回退 i18n。
+  const resolvedSearchPlaceholder = $derived(searchPlaceholder ?? loc().t('TreeSelect.searchPlaceholder'));
 
   // --- DOM 引用：触发根 + portal 面板（定位由 use:floating action 接管）---
   let rootEl = $state<HTMLDivElement | null>(null);
   let panelEl = $state<HTMLDivElement | null>(null);
 
-  // --- destroyOnClose：默认 false 时首开后保留浮层 DOM（仅隐藏），true 时关闭即卸载，重开重建。 ---
+  // --- 浮层 DOM：首开后保留（仅隐藏），对齐 Semi（不销毁重建）。 ---
   let hasBeenOpened = $state(false);
   $effect(() => {
     if (isOpen) hasBeenOpened = true;
   });
-  const shouldRender = $derived(destroyOnClose ? isOpen : isOpen || hasBeenOpened);
+  const shouldRender = $derived(isOpen || hasBeenOpened);
 
   // --- useDismiss (红线 #3): panel portal 出 root 子树后列入 extraTargets ---
   $effect(() => {
@@ -1036,6 +1173,11 @@
       .join(' '),
   );
 
+  // triggerRender 的 value 参数：多选给收敛后的 key 数组，单选给单 key（对齐 onChange 语义）。
+  const triggerValue = $derived<TreeKey | TreeKey[] | null>(
+    multiple ? strategyKeys : currentValue,
+  );
+
   // optionListStyle 规范化为 style 字符串。
   const optionListStyleStr = $derived(
     typeof optionListStyle === 'string'
@@ -1048,6 +1190,16 @@
   );
 </script>
 
+{#snippet emptyBlock()}
+  <div class="cd-tree-select__empty">
+    {#if emptyContent !== undefined}
+      {#if typeof emptyContent === 'string'}{emptyContent}{:else}{@render emptyContent()}{/if}
+    {:else}
+      {loc().t('TreeSelect.emptyText')}
+    {/if}
+  </div>
+{/snippet}
+
 {#snippet nodeRow(
   node: TreeNode,
   level: number,
@@ -1076,7 +1228,7 @@
     aria-checked={multiple ? (cs.checked ? true : cs.half ? 'mixed' : false) : undefined}
     aria-expanded={expandable ? nodeOpen : undefined}
     aria-disabled={node.disabled || undefined}
-    style={[posStyle, `padding-inline-start: calc(${level} * var(--cd-tree-indent))`]
+    style={[posStyle, `padding-inline-start: calc(${level} * var(--cd-spacing-tree-option-level-padding-left))`]
       .filter(Boolean)
       .join('; ')}
     onclick={() => selectNode(node)}
@@ -1105,9 +1257,7 @@
           }
         }}
       >
-        <svg viewBox="0 0 16 16" width="10" height="10" aria-hidden="true" focusable="false">
-          <path fill="currentColor" d="M6 4l4 4-4 4V4Z" />
-        </svg>
+        <IconTreeTriangleDown size="small" aria-hidden="true" />
       </span>
     {:else}
       <span class="cd-tree-select__expand cd-tree-select__expand--placeholder" aria-hidden="true"></span>
@@ -1120,20 +1270,14 @@
         aria-hidden="true"
       >
         {#if cs.checked}
-          <svg viewBox="0 0 16 16" width="12" height="12" aria-hidden="true" focusable="false">
-            <path fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" d="M3.5 8.5l3 3 6-6.5" />
-          </svg>
+          <IconCheckboxTick aria-hidden="true" />
         {:else if cs.half}
-          <svg viewBox="0 0 16 16" width="12" height="12" aria-hidden="true" focusable="false">
-            <path fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" d="M4 8h8" />
-          </svg>
+          <IconCheckboxIndeterminate aria-hidden="true" />
         {/if}
       </span>
     {/if}
-    {#if showIcon}
-      <span class="cd-tree-select__icon" aria-hidden="true">
-        {#if icon}{@render icon({ node, expanded: nodeOpen, level })}{/if}
-      </span>
+    {#if node.icon != null}
+      <span class="cd-tree-select__icon" aria-hidden="true">{node.icon}</span>
     {/if}
     <span class="cd-tree-select__node-label">
       {#if searchActive}
@@ -1147,6 +1291,63 @@
   </div>
 {/snippet}
 
+{#snippet restTagsTrigger()}
+  <!-- +N 折叠触发器：aria-label 走 i18n restTagsCount（「还有 {count} 项」/「{count} more」）供屏幕阅读器朗读折叠数 -->
+  <span
+    class="cd-tree-select__rest-trigger"
+    aria-label={loc().t('TreeSelect.restTagsCount', { count: hiddenTagCount })}
+  >
+    <Tag size={size === 'large' ? 'default' : 'small'}>+{hiddenTagCount}</Tag>
+  </span>
+{/snippet}
+
+<!--
+  内置搜索框：dropdown / trigger 两处位置复用。
+  - dropdown（默认）：带灰底 + 放大镜的 field，与列表分隔清晰（对齐 Semi）。
+  - trigger（bare=true）：朴素透明 input，与触发器融为一体，无额外灰底框（避免臃肿）。
+-->
+{#snippet builtinSearchInput(bare = false)}
+  {#if typeof searchRender === 'function'}
+    {@render searchRender({
+      value: searchValue,
+      onInput: setSearchValue,
+      onKeydown: onSearchKeydown,
+      placeholder: resolvedSearchPlaceholder,
+    })}
+  {:else if bare}
+    <input
+      class="cd-tree-select__search-input cd-tree-select__search-input--bare"
+      type="text"
+      role="combobox"
+      aria-expanded={isOpen}
+      aria-controls={treeId}
+      aria-activedescendant={activeDescId}
+      placeholder={resolvedSearchPlaceholder}
+      aria-label={resolvedSearchPlaceholder}
+      value={searchValue}
+      oninput={onSearchInput}
+      onkeydown={onSearchKeydown}
+    />
+  {:else}
+    <span class="cd-tree-select__search-field">
+      <IconSearch class="cd-tree-select__search-icon" aria-hidden="true" />
+      <input
+        class="cd-tree-select__search-input"
+        type="text"
+        role="combobox"
+        aria-expanded={isOpen}
+        aria-controls={treeId}
+        aria-activedescendant={activeDescId}
+        placeholder={resolvedSearchPlaceholder}
+        aria-label={resolvedSearchPlaceholder}
+        value={searchValue}
+        oninput={onSearchInput}
+        onkeydown={onSearchKeydown}
+      />
+    </span>
+  {/if}
+{/snippet}
+
 {#snippet treeNodes(nodes: TreeNode[], level: number)}
   {@const setSize = nodes.length}
   {#each nodes as node, i (node.key)}
@@ -1162,6 +1363,9 @@
 
 <div class={cls} bind:this={rootEl} {style}>
   <!-- combobox 容器用 div 以合法承载多选 tags / clear 等内部交互元素 -->
+  {#if triggerRender}
+    {@render triggerRender({ value: triggerValue, placeholder, isOpen, disabled })}
+  {:else}
   <div
     class="cd-tree-select__trigger"
     role="combobox"
@@ -1170,6 +1374,10 @@
     aria-controls={treeId}
     aria-activedescendant={isOpen && !searchActive ? activeDescId : undefined}
     aria-label={ariaLabel}
+    aria-labelledby={ariaLabelledby}
+    aria-describedby={ariaDescribedby}
+    aria-errormessage={ariaErrormessage}
+    aria-required={ariaRequired || undefined}
     aria-invalid={effStatus === 'error' || undefined}
     aria-disabled={disabled || undefined}
     tabindex={disabled ? -1 : 0}
@@ -1199,34 +1407,71 @@
         {#if typeof prefix === 'string'}{prefix}{:else}{@render prefix()}{/if}
       </span>
     {/if}
-    <span class="cd-tree-select__content">
+    {#if insetLabel}
+      <span class="cd-tree-select__inset-label" id={insetLabelId}>
+        {#if typeof insetLabel === 'string'}{insetLabel}{:else}{@render insetLabel()}{/if}
+      </span>
+    {/if}
+    <span class="cd-tree-select__content" class:cd-tree-select__content--search-trigger={searchInTrigger}>
+      {#if searchInTrigger}
+        <!-- searchPosition='trigger'：朴素 input 内嵌触发器，与触发器融为一体（bare 模式，无灰底框）。 -->
+        <span class="cd-tree-select__trigger-search">{@render builtinSearchInput(true)}</span>
+      {/if}
       {#if multiple}
         {#if checkedNodes.length > 0}
           <span class="cd-tree-select__tags">
             {#each visibleTagNodes as node (node.key)}
-              <Tag
-                size={size === 'large' ? 'default' : 'small'}
-                closable={!disabled}
-                onClose={() => removeChecked(node)}
-              >
-                {node.label}
-              </Tag>
+              {#if renderSelectedItem}
+                {@render renderSelectedItem({ node, onRemove: () => removeChecked(node) })}
+              {:else}
+                <Tag
+                  size={size === 'large' ? 'default' : 'small'}
+                  closable={!disabled}
+                  onClose={() => removeChecked(node)}
+                >
+                  {node.label}
+                </Tag>
+              {/if}
             {/each}
             {#if hiddenTagCount > 0}
-              <Tag size={size === 'large' ? 'default' : 'small'}>+{hiddenTagCount}</Tag>
+              {#if showRestTagsPopover}
+                <!-- showRestTagsPopover：hover +N 用本库 Popover 展示折叠掉的剩余 Tag（restTagsPopoverProps 可覆盖默认 props） -->
+                <Popover trigger="hover" position="top" {...(restTagsPopoverProps ?? {})}>
+                  {@render restTagsTrigger()}
+                  {#snippet content()}
+                    <span class="cd-tree-select__rest-tags">
+                      {#each hiddenTagNodes as node (node.key)}
+                        <Tag
+                          size={size === 'large' ? 'default' : 'small'}
+                          closable={!disabled}
+                          onClose={() => removeChecked(node)}
+                        >
+                          {node.label}
+                        </Tag>
+                      {/each}
+                    </span>
+                  {/snippet}
+                </Popover>
+              {:else}
+                {@render restTagsTrigger()}
+              {/if}
             {/if}
           </span>
         {:else}
           <span class="cd-tree-select__placeholder">{placeholder}</span>
         {/if}
       {:else if hasSelection}
-        <span class="cd-tree-select__value">{displayLabel}</span>
+        {#if renderSelectedItem && selectedNode}
+          {@render renderSelectedItem({ node: selectedNode, onRemove: () => setValue(null) })}
+        {:else}
+          <span class="cd-tree-select__value">{displayLabel}</span>
+        {/if}
       {:else}
         <span class="cd-tree-select__placeholder">{placeholder}</span>
       {/if}
     </span>
 
-    {#if showClear}
+    {#if showClearBtn}
       <span
         class="cd-tree-select__clear"
         role="button"
@@ -1241,12 +1486,7 @@
           }
         }}
       >
-        <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true" focusable="false">
-          <path
-            fill="currentColor"
-            d="M8 1a7 7 0 1 0 0 14A7 7 0 0 0 8 1Zm2.5 9.1-1.4 1.4L8 9.4 6.5 11l-1.4-1.4L6.6 8 5.1 6.5 6.5 5.1 8 6.6 9.5 5.1l1.4 1.4L9.4 8l1.1 1.1Z"
-          />
-        </svg>
+        <IconClear aria-hidden="true" />
       </span>
     {/if}
 
@@ -1259,56 +1499,38 @@
       {#if arrowIcon}
         {@render arrowIcon()}
       {:else}
-        <svg viewBox="0 0 16 16" width="12" height="12" focusable="false">
-          <path fill="currentColor" d="M3.5 6 8 10.5 12.5 6l-1-1L8 8.5 4.5 5l-1 1Z" />
-        </svg>
+        <IconChevronDown aria-hidden="true" />
       {/if}
     </span>
   </div>
+  {/if}
 
   {#if shouldRender}
     <div
-      class="cd-tree-select__panel"
+      class={['cd-tree-select__panel', dropdownClassName].filter(Boolean).join(' ')}
       class:cd-tree-select__panel--hidden={!isOpen}
+      class:cd-tree-select__panel--motion={motion && isOpen}
       bind:this={panelEl}
       use:floating={{
         trigger: rootEl,
-        placement: 'bottomStart',
+        placement: dropdownPlacement,
         autoAdjust: true,
-        offset: 4,
+        offset: dropdownOffset,
         matchWidth: dropdownMatchSelectWidth,
         getContainer: resolvePopupContainer,
         open: isOpen,
       }}
       id={treeId}
+      style={dropdownStyleStr}
     >
-      {#if isFilterable}
+      {#if searchInDropdown}
         <div class="cd-tree-select__search">
-          <input
-            class="cd-tree-select__search-input"
-            type="text"
-            role="combobox"
-            aria-expanded={isOpen}
-            aria-controls={treeId}
-            aria-activedescendant={activeDescId}
-            placeholder={loc().t('TreeSelect.searchPlaceholder')}
-            aria-label={loc().t('TreeSelect.searchPlaceholder')}
-            value={searchValue}
-            oninput={onSearchInput}
-            onkeydown={(e) => {
-              if (e.key === 'Escape') {
-                setOpen(false);
-                return;
-              }
-              // 搜索框聚焦时方向键/Home/End/Enter 在过滤后的可见树上 roving。
-              onTreeKeydown(e);
-            }}
-          />
+          {@render builtinSearchInput()}
         </div>
       {/if}
       {#if mergedTree.length === 0}
         <div class="cd-tree-select__tree" role="tree">
-          <div class="cd-tree-select__empty">{loc().t('TreeSelect.emptyText')}</div>
+          {@render emptyBlock()}
         </div>
       {:else if useVirtual}
         <!-- 虚拟滚动（复用 Tree 范式）：role=tree 容器自身滚动，spacer 撑总高，行绝对定位按索引偏移。
@@ -1325,7 +1547,7 @@
           onkeydown={onTreeKeydown}
         >
           {#if visibleFlat.length === 0}
-            <div class="cd-tree-select__empty">{loc().t('TreeSelect.emptyText')}</div>
+            {@render emptyBlock()}
           {:else}
             <div class="cd-tree-select__spacer" style={`block-size:${totalHeight}px`}>
               {#each renderFlat as f, i (f.node.key)}
@@ -1352,7 +1574,7 @@
         >
           {@render treeNodes(mergedTree, 0)}
           {#if searchActive && filterResult.matched.size === 0}
-            <div class="cd-tree-select__empty">{loc().t('TreeSelect.emptyText')}</div>
+            {@render emptyBlock()}
           {/if}
         </div>
       {/if}
@@ -1405,12 +1627,47 @@
     background: var(--cd-select-bg);
     border-color: var(--cd-select-border-active);
   }
+  /* warning 校验态：light-bg + 分态 border（对齐 Semi treeSelect warning，same as Input）。 */
+  .cd-tree-select--warning .cd-tree-select__trigger {
+    background: var(--cd-color-tree-select-warning-bg-default);
+    border-color: var(--cd-color-tree-select-warning-border-default);
+  }
+  .cd-tree-select--warning:not(.cd-tree-select--open):not(.cd-tree-select--disabled)
+    .cd-tree-select__trigger:hover {
+    background: var(--cd-color-tree-select-warning-bg-hover);
+    border-color: var(--cd-color-tree-select-warning-border-hover);
+  }
+  .cd-tree-select--warning .cd-tree-select__trigger:focus-visible,
+  .cd-tree-select--warning.cd-tree-select--open .cd-tree-select__trigger {
+    background: var(--cd-color-tree-select-warning-bg-focus);
+    border-color: var(--cd-color-tree-select-warning-border-focus);
+  }
+  .cd-tree-select--warning .cd-tree-select__trigger:active {
+    background: var(--cd-color-tree-select-warning-bg-active);
+    border-color: var(--cd-color-tree-select-warning-border-active);
+  }
+  /* error 校验态：light-bg + 分态 border（对齐 Semi treeSelect danger，same as Input）。 */
   .cd-tree-select--error .cd-tree-select__trigger {
-    border-color: var(--cd-select-border-error);
+    background: var(--cd-color-tree-select-danger-bg-default);
+    border-color: var(--cd-color-tree-select-danger-border-default);
+  }
+  .cd-tree-select--error:not(.cd-tree-select--open):not(.cd-tree-select--disabled)
+    .cd-tree-select__trigger:hover {
+    background: var(--cd-color-tree-select-danger-bg-hover);
+    border-color: var(--cd-color-tree-select-danger-border-hover);
+  }
+  .cd-tree-select--error .cd-tree-select__trigger:focus-visible,
+  .cd-tree-select--error.cd-tree-select--open .cd-tree-select__trigger {
+    background: var(--cd-color-tree-select-danger-bg-focus);
+    border-color: var(--cd-color-tree-select-danger-border-focus);
+  }
+  .cd-tree-select--error .cd-tree-select__trigger:active {
+    background: var(--cd-color-tree-select-danger-bg-active);
+    border-color: var(--cd-color-tree-select-danger-border-active);
   }
   .cd-tree-select__trigger[aria-disabled='true'] {
-    background: var(--cd-color-disabled-fill, var(--cd-color-fill-0));
-    color: var(--cd-color-text-3);
+    background: var(--cd-color-tree-select-input-disabled-bg-default, var(--cd-color-fill-0));
+    color: var(--cd-color-tree-select-input-disabled-text-default);
     cursor: not-allowed;
   }
   .cd-tree-select__content {
@@ -1419,14 +1676,35 @@
     align-items: center;
     min-inline-size: 0;
   }
+  /* searchPosition='trigger'：搜索输入占据触发器主区，与已选值/占位并存。 */
+  .cd-tree-select__trigger-search {
+    display: flex;
+    flex: 1 1 auto;
+    min-inline-size: 0;
+  }
+  /* bare 搜索 input：透明、无边框，与触发器融为一体（避免臃肿的灰底框）。 */
+  .cd-tree-select__search-input--bare {
+    inline-size: 100%;
+    min-inline-size: 0;
+    block-size: auto;
+    padding: 0;
+    background: transparent;
+    border: none;
+    color: inherit;
+    font: inherit;
+    outline: none;
+  }
+  .cd-tree-select__search-input--bare::placeholder {
+    color: var(--cd-color-text-2);
+  }
   .cd-tree-select__value {
     overflow: hidden;
     white-space: nowrap;
     text-overflow: ellipsis;
   }
   .cd-tree-select__placeholder {
-    /* 对齐 Semi treeSelect 占位符 text-2（原共享 input-placeholder = text-3） */
-    color: var(--cd-color-text-2);
+    /* 对齐 Semi treeSelect 占位符 input-placeholder-text-default = text-2 */
+    color: var(--cd-color-tree-select-input-placeholder-text-default);
   }
   .cd-tree-select__clear,
   .cd-tree-select__arrow {
@@ -1434,13 +1712,14 @@
     align-items: center;
     justify-content: center;
     flex: 0 0 auto;
-    color: var(--cd-color-text-2);
+    /* 对齐 Semi treeSelect default-icon-default = text-2 */
+    color: var(--cd-color-tree-select-default-icon-default);
   }
   .cd-tree-select__clear {
     cursor: pointer;
   }
   .cd-tree-select__clear:hover {
-    color: var(--cd-color-text-0);
+    color: var(--cd-color-tree-select-default-icon-hover);
   }
   .cd-tree-select__arrow {
     transition: transform var(--cd-motion-duration-fast) var(--cd-motion-ease-standard);
@@ -1456,29 +1735,83 @@
     border-radius: var(--cd-select-dropdown-radius);
     box-shadow: var(--cd-select-dropdown-shadow);
   }
-  /* destroyOnClose=false 关闭后保留 DOM 但不可见、不可交互、不占位 */
+  /* 关闭后保留 DOM 但不可见、不可交互、不占位（对齐 Semi，不销毁重建） */
   .cd-tree-select__panel--hidden {
     display: none;
   }
+  /* motion：下拉浮层开合进场淡入；reduced-motion 退化。
+     注意：定位 transform 由 use:floating 写入 inline style，动画 keyframe
+     绝不能设 transform（CSS animation 优先级高于 inline style，会把 floating 的
+     translate(x,y) 覆盖成 0，浮层飘到容器左上角）。故仅动 opacity（与 Dropdown 一致）。 */
+  .cd-tree-select__panel--motion {
+    animation: cd-tree-select-in var(--cd-dropdown-motion-duration, 120ms)
+      var(--cd-dropdown-motion-easing, ease) both;
+  }
+  @keyframes cd-tree-select-in {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
+  }
+  /* insetLabel 内嵌标签：回填值前的标签文本，消费 tree-select label token */
+  .cd-tree-select__inset-label {
+    display: inline-flex;
+    align-items: center;
+    flex: 0 0 auto;
+    margin-inline-end: var(--cd-spacing-tight);
+    color: var(--cd-color-tree-select-label);
+    font-weight: var(--cd-font-tree-select-label);
+    white-space: nowrap;
+    user-select: none;
+  }
   .cd-tree-select__search {
+    padding: var(--cd-spacing-tight);
     padding-block-end: var(--cd-spacing-extra-tight);
-    padding-inline: var(--cd-spacing-tight);
+  }
+  /* 搜索字段：灰底圆角 + 左侧放大镜图标（对齐 Semi 的和谐观感，与列表分隔清晰）。 */
+  .cd-tree-select__search-field {
+    display: flex;
+    align-items: center;
+    gap: var(--cd-spacing-extra-tight);
+    inline-size: 100%;
+    block-size: var(--cd-height-input-default);
+    padding-inline: var(--cd-spacing-input-paddingleft);
+    background: var(--cd-color-fill-0);
+    border: 1px solid transparent;
+    border-radius: var(--cd-radius-input-wrapper);
+    transition:
+      background-color var(--cd-motion-duration-fast) var(--cd-motion-ease-standard),
+      border-color var(--cd-motion-duration-fast) var(--cd-motion-ease-standard);
+  }
+  .cd-tree-select__search-field:hover {
+    background: var(--cd-color-fill-1);
+  }
+  .cd-tree-select__search-field:focus-within {
+    background: var(--cd-color-bg-0);
+    border-color: var(--cd-color-input-default-border-focus);
+    box-shadow: var(--cd-focus-ring);
+  }
+  .cd-tree-select__search-icon {
+    flex: 0 0 auto;
+    color: var(--cd-color-text-2);
   }
   .cd-tree-select__search-input {
+    flex: 1 1 auto;
     inline-size: 100%;
-    block-size: var(--cd-input-height-small);
-    padding-inline: var(--cd-input-padding-x);
-    background: var(--cd-input-bg, transparent);
+    min-inline-size: 0;
+    block-size: 100%;
+    padding: 0;
+    background: transparent;
     color: inherit;
-    border: 1px solid var(--cd-input-border);
-    border-radius: var(--cd-input-radius);
+    border: none;
     font: inherit;
     font-size: var(--cd-font-size-small);
-  }
-  .cd-tree-select__search-input:focus-visible {
     outline: none;
-    border-color: var(--cd-input-border-active);
-    box-shadow: var(--cd-focus-ring);
+  }
+  .cd-tree-select__search-input::placeholder {
+    color: var(--cd-color-text-2);
   }
   .cd-tree-select__tree {
     max-block-size: 14rem;
@@ -1496,8 +1829,8 @@
   }
   .cd-tree-select__highlight {
     padding: 0;
-    color: var(--cd-tree-search-highlight-color);
-    background: var(--cd-tree-search-highlight-bg);
+    color: var(--cd-color-tree-option-highlight-text);
+    background: inherit;
   }
   .cd-tree-select__node {
     display: flex;
@@ -1508,11 +1841,11 @@
     cursor: pointer;
   }
   .cd-tree-select__node:hover {
-    background: var(--cd-tree-node-bg-hover);
+    background: var(--cd-color-tree-option-bg-hover);
   }
   .cd-tree-select__node--selected {
-    color: var(--cd-tree-node-color-selected);
-    background: var(--cd-tree-node-bg-active);
+    color: var(--cd-color-tree-option-text-default);
+    background: var(--cd-color-tree-option-bg-active);
   }
   /* 键盘 roving 高亮（aria-activedescendant 当前项），焦点环不依赖真实 DOM 焦点 */
   .cd-tree-select__node--active {
@@ -1533,19 +1866,23 @@
     flex: 0 0 auto;
     inline-size: 1rem;
     block-size: 1rem;
-    color: var(--cd-tree-expand-icon-color);
+    color: var(--cd-color-tree-option-icon-default);
     cursor: pointer;
     transition: transform var(--cd-motion-duration-fast) var(--cd-motion-ease-standard);
+    /* IconTreeTriangleDown 默认朝下（展开态）；折叠态旋转 -90deg 朝右，对齐 Semi。 */
+    transform: rotate(-90deg);
   }
   .cd-tree-select__expand--open {
-    transform: rotate(90deg);
+    transform: rotate(0deg);
   }
   .cd-tree-select__expand--placeholder {
     cursor: default;
+    transform: none;
   }
   .cd-tree-select__expand--loading {
     cursor: default;
     transition: none;
+    transform: none;
   }
   .cd-tree-select__spinner {
     inline-size: 0.75rem;
@@ -1567,7 +1904,7 @@
     flex: 0 0 auto;
     inline-size: 0;
     block-size: 1rem;
-    color: var(--cd-tree-node-color);
+    color: var(--cd-color-tree-option-text-default);
   }
   /* 有自定义图标内容时撑开尺寸（对齐 Tree 的 .cd-tree__icon） */
   .cd-tree-select__icon:not(:empty) {
@@ -1585,10 +1922,10 @@
     flex: 0 0 auto;
     inline-size: 1rem;
     block-size: 1rem;
-    color: #fff;
+    color: var(--cd-color-white);
     background: var(--cd-color-bg-1, #fff);
     border: 1px solid var(--cd-color-border);
-    border-radius: var(--cd-radius-small, 3px);
+    border-radius: var(--cd-border-radius-small);
   }
   .cd-tree-select__checkbox--checked,
   .cd-tree-select__checkbox--half {
@@ -1607,13 +1944,27 @@
     color: var(--cd-color-text-3);
     text-align: center;
   }
+  /* +N 折叠触发器：内联包裹 Tag，承载 aria-label（Popover trigger 宿主） */
+  .cd-tree-select__rest-trigger {
+    display: inline-flex;
+    align-items: center;
+  }
+  /* showRestTagsPopover 浮层内剩余 Tag 列表：换行铺排，限制最大宽避免过宽 */
+  .cd-tree-select__rest-tags {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--cd-spacing-extra-tight);
+    align-items: center;
+    max-inline-size: 240px;
+  }
   @media (prefers-reduced-motion: reduce) {
     .cd-tree-select__trigger,
     .cd-tree-select__arrow,
     .cd-tree-select__expand {
       transition: none;
     }
-    .cd-tree-select__spinner {
+    .cd-tree-select__spinner,
+    .cd-tree-select__panel--motion {
       animation: none;
     }
   }