@manohub/ui 0.10.1 → 0.10.3

package/dist/components/select/select-list.d.ts

@@ -3,15 +3,20 @@
  *
  * 它拥有「面板里那一撮选项」的全部形态与状态行：平铺选项 / 分组（组标题不可点）/ 「创建」行 /
  * 空态行 / 加载行。**不含面板壳与搜索行**（那是 `SelectPanel` 的事），也不持有任何状态 ——
- * 过滤结果、选中值、是否可创建统统由消费方算好喂进来，本件只渲染。
- * 行由面板壳装在**内容区**（`.mh-select__body`，面板里唯一的滚动容器）里，限高与滚动都归面层，
- * 本件不写第二个滚动容器。
+ * 过滤结果、选中值、高亮格号、是否可创建统统由消费方算好喂进来，本件只渲染。
+ * 行由面板壳装在**内容区**（`.mh-select__body`，面板里唯一的滚动容器）里：限高、滚动与内容内距
+ * 都归那一层（与树形态共用一份），本件不写第二个滚动容器、也不自己包一层给内距。
  *
- * 选项是真实 `<button role="option">`（不是 div + JS 高亮）：键盘可达、`:focus-visible` 可直接
- * 承载「高亮行」这层语义，于是不需要再维护一份 JS 高亮下标 —— **焦点即高亮**，
- * 状态只有 DOM 焦点一个来源。四条按钮重置（`border` / `background` / `font-family` /
- * `text-align`）在面上自带（reset 层清了前三条、`text-align` 属列表行语义故面里显式写），
- * 否则选项会长成原生按钮的灰底立体框 —— 见 `select.css` 的 `.mh-select__option` 一节。
+ * ## 选项是 `div[role='option']`，**不是 button**
+ *
+ * listbox 的 option 不是交互控件：真实按钮会带来第二套语义（可激活、可聚焦、`:focus-visible`
+ * 的 UA 描边）与四件套 UA 外观重置（见 `select.css` 的选项行一节 —— 那几条已随本改动退场）。
+ * 键盘因此换一套模型：**焦点留在触发器上**，高亮由 `data-active` 表达，并由
+ * `aria-activedescendant` 指到这一行的 `id`（`optionDomId()`，格号 = 可激活项里的顺序）。
+ * 点击仍是真实 `onClick`（`div` 一样收得到），禁用项靠 `aria-disabled` + 消费方的 `pick()` 兜住
+ * —— 没有 `disabled` 属性可用，这一点在 `Select` 的选中逻辑里成对处理。
+ *
+ * 空 / 加载行仍是 `span`（不进键盘顺序：`role` 不给，消费方的条数只数 `role='option'`）。
  *
  * 选中态**三源等价**（面层只写一份声明）：组件下发 `[data-state='selected']` /
  * 原生 `:has(input:checked)`（静态页零 JS 单选路径）/ `.is-selected`（规格冻结档）。
@@ -29,6 +34,20 @@ export declare const SelectList: import("vue").DefineComponent<import("vue").Ext
         type: PropType<Array<string | number>>;
         default: () => never[];
     };
+    /**
+     * 键盘高亮位（可激活项里的格号；`undefined` = 没有高亮）。
+     *
+     * 格号由 `activatableOptions()` 的顺序给，「创建」行占末尾那一格（= 可激活项总数）。
+     */
+    activeIndex: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    /** 面板 id：选项行的 `id` 由它 + 格号拼出（`aria-activedescendant` 要指过来） */
+    idBase: {
+        type: StringConstructor;
+        required: true;
+    };
     loading: {
         type: BooleanConstructor;
         default: boolean;
@@ -78,6 +97,20 @@ export declare const SelectList: import("vue").DefineComponent<import("vue").Ext
         type: PropType<Array<string | number>>;
         default: () => never[];
     };
+    /**
+     * 键盘高亮位（可激活项里的格号；`undefined` = 没有高亮）。
+     *
+     * 格号由 `activatableOptions()` 的顺序给，「创建」行占末尾那一格（= 可激活项总数）。
+     */
+    activeIndex: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    /** 面板 id：选项行的 `id` 由它 + 格号拼出（`aria-activedescendant` 要指过来） */
+    idBase: {
+        type: StringConstructor;
+        required: true;
+    };
     loading: {
         type: BooleanConstructor;
         default: boolean;
@@ -118,6 +151,7 @@ export declare const SelectList: import("vue").DefineComponent<import("vue").Ext
     loading: boolean;
     options: SelectItem[];
     selectedValues: (string | number)[];
+    activeIndex: number;
     emptyText: string;
     creatable: boolean;
     keyword: string;

package/dist/components/select/select-list.js

@@ -1,5 +1,5 @@
-import { defineComponent, createVNode, createTextVNode, Fragment } from "vue";
-import { isGroup } from "./select-shared.js";
+import { defineComponent, computed, createVNode, createTextVNode, Fragment } from "vue";
+import { activatableOptions, isGroup, optionDomId } from "./select-shared.js";
 const SelectList = /* @__PURE__ */ defineComponent({
   name: "SelectList",
   inheritAttrs: false,
@@ -14,6 +14,20 @@ const SelectList = /* @__PURE__ */ defineComponent({
       type: Array,
       default: () => []
     },
+    /**
+     * 键盘高亮位（可激活项里的格号；`undefined` = 没有高亮）。
+     *
+     * 格号由 `activatableOptions()` 的顺序给，「创建」行占末尾那一格（= 可激活项总数）。
+     */
+    activeIndex: {
+      type: Number,
+      default: void 0
+    },
+    /** 面板 id：选项行的 `id` 由它 + 格号拼出（`aria-activedescendant` 要指过来） */
+    idBase: {
+      type: String,
+      required: true
+    },
     loading: {
       type: Boolean,
       default: false
@@ -52,16 +66,19 @@ const SelectList = /* @__PURE__ */ defineComponent({
     }
   },
   setup(props) {
+    const activatable = computed(() => activatableOptions(props.options));
     const renderOption = (option) => {
       const selected = props.selectedValues.includes(option.value);
-      return createVNode("button", {
+      const slot = activatable.value.indexOf(option);
+      return createVNode("div", {
         "key": String(option.value),
-        "type": "button",
+        "id": optionDomId(props.idBase, slot),
         "class": ["mh-select__option", option.disabled ? "is-disabled" : ""].filter(Boolean).join(" "),
-        "data-state": selected ? "selected" : "unselected",
-        "disabled": option.disabled,
         "role": "option",
+        "data-state": selected ? "selected" : "unselected",
+        "data-active": props.activeIndex === slot ? "true" : void 0,
         "aria-selected": selected ? "true" : "false",
+        "aria-disabled": option.disabled ? "true" : void 0,
         "onClick": () => props.onPick?.(option)
       }, [option.label]);
     };
@@ -82,11 +99,19 @@ const SelectList = /* @__PURE__ */ defineComponent({
         "class": "mh-select__group"
       }, [createVNode("span", {
         "class": "mh-select__group-label"
-      }, [item.label]), item.options.map((option) => renderOption(option))]) : renderOption(item)), props.creatable ? createVNode("button", {
-        "type": "button",
-        "class": "mh-select__option mh-select__add",
-        "onClick": () => props.onCreate?.()
-      }, [createTextVNode("创建「"), props.keyword.trim(), createTextVNode("」")]) : null]);
+      }, [item.label]), item.options.map((option) => renderOption(option))]) : renderOption(item)), props.creatable ? (
+        /* 「创建」行也占一个可激活格（末尾那格）：箭头键能走到它、回车即创建 —— 
+           它同样写 `.mh-select__option` 基类（行几何与三态全沿用），`.mh-select__add` 只改字色 */
+        createVNode("div", {
+          "id": optionDomId(props.idBase, activatable.value.length),
+          "class": "mh-select__option mh-select__add",
+          "role": "option",
+          "data-state": "unselected",
+          "data-active": props.activeIndex === activatable.value.length ? "true" : void 0,
+          "aria-selected": "false",
+          "onClick": () => props.onCreate?.()
+        }, [createTextVNode("创建「"), props.keyword.trim(), createTextVNode("」")])
+      ) : null]);
     };
   }
 });

package/dist/components/select/select-panel.d.ts

@@ -2,7 +2,8 @@
  * SelectPanel —— 选择器族的**面板壳内件**（`Select` 与 `SelectTree` 共用，不对外导出）。
  *
  * 它只拥有四样东西：**原生 popover 元素**（开合 / Esc / 点外部关闭 / 顶层渲染 / 定位全归浏览器）、
- * **搜索行**（面板顶部那一个输入框）、**内容区**（`.mh-select__body`，面板里唯一的滚动容器）
+ * **搜索行**（面板顶部那一个输入框）、**内容区**（`.mh-select__body`，面板里唯一的滚动容器，
+ * 也是**两形态共用的一处内容内距** —— 列表的选项与树的树都直接装在它里面，形态里不再各包一层给内距）
  * 与**内容槽**（列表体或树体）。
  * 「面板里装什么」不在本件 —— 这正是让列表与树共用同一份面板皮肤的原因。
  *
@@ -17,7 +18,7 @@
  * 锚是挂在**表壳**上的 `.mh-popup-anchor`（触发器进壳后隐式锚会缩成壳内控件，故走显式锚档）。
  *
  * `elementRef` 是**由消费方持有的 ref**（不是本件自己的）：开面板（触发器 ↑↓）、收起面板（选中后）、
- * 以及列表形态的 `.mh-select__option` 焦点遍历都要在父层拿到这个 DOM 元素。
+ * 以及列表形态按 `[data-active]` 取高亮行（滚动入视）都要在父层拿到这个 DOM 元素。
  */
 import { type PropType, type SlotsType, type VNodeChild } from 'vue';
 import type { ElementRef } from './select-shared';
@@ -51,15 +52,28 @@ export declare const SelectPanel: import("vue").DefineComponent<import("vue").Ex
         default: undefined;
     };
     /**
-     * 面板上的键盘契约。
+     * 面板上的键盘契约（列表形态给，树形态不给）。
      *
-     * 列表形态给 `↑↓` 移动高亮行（选项是真实 `<button>`，焦点即高亮）；树形态不给 ——
-     * 树的行是 `div`、没有 tabindex，焦点无处可落（与 `Tree` 自身不做键盘导航同口径）。
+     * 列表形态接 `↑` / `↓`（平移高亮）与 `Enter`（提交高亮项）。这些事件**来自面板内的搜索行**
+     * —— 选项是 `div[role='option']`、不可聚焦，焦点留在触发器上（触发器那条路走
+     * `createTriggerKeydown()`，两条路共用同一份高亮模型）。树形态不给：树的行不做键盘导航
+     * （与 `Tree` 自身同口径）。
      */
     onKeydown: {
         type: PropType<(event: KeyboardEvent) => void>;
         default: undefined;
     };
+    /**
+     * 面板的原生 `toggle` 事件（开合态变化，含 Esc 与点外部关闭）。
+     *
+     * 声明成本件的 prop 而不是靠 `attrs`：本件的 `attrs` 是关掉的（`inheritAttrs: false`），
+     * 且这个事件要落到**面板元素**上（`toggle` 只有它派发）。消费方据此回写「面板开着吗」
+     * —— 那是 `Enter` 接管的判定依据（见 `Select` 的 `isPanelOpen`）。
+     */
+    onToggle: {
+        type: PropType<(event: Event) => void>;
+        default: undefined;
+    };
 }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
     /** 面板 id（必须与触发器的 `popovertarget` 成对） */
     id: {
@@ -90,17 +104,31 @@ export declare const SelectPanel: import("vue").DefineComponent<import("vue").Ex
         default: undefined;
     };
     /**
-     * 面板上的键盘契约。
+     * 面板上的键盘契约（列表形态给，树形态不给）。
      *
-     * 列表形态给 `↑↓` 移动高亮行（选项是真实 `<button>`，焦点即高亮）；树形态不给 ——
-     * 树的行是 `div`、没有 tabindex，焦点无处可落（与 `Tree` 自身不做键盘导航同口径）。
+     * 列表形态接 `↑` / `↓`（平移高亮）与 `Enter`（提交高亮项）。这些事件**来自面板内的搜索行**
+     * —— 选项是 `div[role='option']`、不可聚焦，焦点留在触发器上（触发器那条路走
+     * `createTriggerKeydown()`，两条路共用同一份高亮模型）。树形态不给：树的行不做键盘导航
+     * （与 `Tree` 自身同口径）。
      */
     onKeydown: {
         type: PropType<(event: KeyboardEvent) => void>;
         default: undefined;
     };
+    /**
+     * 面板的原生 `toggle` 事件（开合态变化，含 Esc 与点外部关闭）。
+     *
+     * 声明成本件的 prop 而不是靠 `attrs`：本件的 `attrs` 是关掉的（`inheritAttrs: false`），
+     * 且这个事件要落到**面板元素**上（`toggle` 只有它派发）。消费方据此回写「面板开着吗」
+     * —— 那是 `Enter` 接管的判定依据（见 `Select` 的 `isPanelOpen`）。
+     */
+    onToggle: {
+        type: PropType<(event: Event) => void>;
+        default: undefined;
+    };
 }>> & Readonly<{}>, {
     onKeydown: (event: KeyboardEvent) => void;
+    onToggle: (event: Event) => void;
     keyword: string;
     elementRef: ElementRef;
     searchable: boolean;

package/dist/components/select/select-panel.js

@@ -32,14 +32,27 @@ const SelectPanel = /* @__PURE__ */ defineComponent({
       default: void 0
     },
     /**
-     * 面板上的键盘契约。
+     * 面板上的键盘契约（列表形态给，树形态不给）。
      *
-     * 列表形态给 `↑↓` 移动高亮行（选项是真实 `<button>`，焦点即高亮）；树形态不给 ——
-     * 树的行是 `div`、没有 tabindex，焦点无处可落（与 `Tree` 自身不做键盘导航同口径）。
+     * 列表形态接 `↑` / `↓`（平移高亮）与 `Enter`（提交高亮项）。这些事件**来自面板内的搜索行**
+     * —— 选项是 `div[role='option']`、不可聚焦，焦点留在触发器上（触发器那条路走
+     * `createTriggerKeydown()`，两条路共用同一份高亮模型）。树形态不给：树的行不做键盘导航
+     * （与 `Tree` 自身同口径）。
      */
     onKeydown: {
       type: Function,
       default: void 0
+    },
+    /**
+     * 面板的原生 `toggle` 事件（开合态变化，含 Esc 与点外部关闭）。
+     *
+     * 声明成本件的 prop 而不是靠 `attrs`：本件的 `attrs` 是关掉的（`inheritAttrs: false`），
+     * 且这个事件要落到**面板元素**上（`toggle` 只有它派发）。消费方据此回写「面板开着吗」
+     * —— 那是 `Enter` 接管的判定依据（见 `Select` 的 `isPanelOpen`）。
+     */
+    onToggle: {
+      type: Function,
+      default: void 0
     }
   },
   slots: Object,
@@ -56,7 +69,8 @@ const SelectPanel = /* @__PURE__ */ defineComponent({
       "data-side": "bottom",
       "data-align": "start",
       "role": "listbox",
-      "onKeydown": props.onKeydown
+      "onKeydown": props.onKeydown,
+      "onToggle": props.onToggle
     }), [props.searchable ? createVNode("div", {
       "class": "mh-select__search"
     }, [createVNode("input", {

package/dist/components/select/select-shared.d.ts

@@ -1,13 +1,14 @@
 /**
- * 选择器族的**共用原子**（类型、面板 id、popover 开合、触发器键盘契约）。
+ * 选择器族的**共用原子**（类型、面板 id、popover 开合、触发器键盘契约、键位模型的可激活项摊平）。
  *
  * 这是 `select/` 目录里的**叶子模块**：它不 import 同目录任何其它文件，因此触发器 / 面板壳 /
  * 列表体 / 树体四件可以自由地互相组合而不产生环。内件一律**不对外导出**（`src/index.ts` 只出
  * `Select` 与 `SelectTree`），故本文件的导出面是「族内契约」，改它要同时看那四件。
  *
- * 为什么单独一份而不是各自写一遍：这四样都是**跨两件以上**的东西 ——
+ * 为什么单独一份而不是各自写一遍：这些都是**跨两件以上**的东西 ——
  * 类型（列表体与树体都要）、面板 id 生成器（两件的面板都得全页唯一）、
- * popover 开合（两件都要收起面板）、触发器键盘契约（两件的触发器是同一个形态）。
+ * popover 开合（两件都要收起面板）、触发器键盘契约（两件的触发器是同一个形态）、
+ * 可激活项的摊平顺序（`Select` 算下一个高亮位、`SelectList` 算行 id 与高亮态，必须同一份）。
  */
 import type { Ref } from 'vue';
 /** 选项（平铺项与分组内选项同构） */
@@ -27,6 +28,29 @@ export type SelectItem = SelectOption | SelectOptionGroup;
 export type SelectValue = string | number | Array<string | number>;
 /** 判别：带 `options` 数组的是分组 */
 export declare const isGroup: (item: SelectItem) => item is SelectOptionGroup;
+/**
+ * **键盘可激活项**：摊平成一行行（分组只影响渲染、不影响键盘顺序）并跳过禁用项。
+ *
+ * 摊平这件事**只在键位模型里**需要（`Select` 算下一个高亮位、`SelectList` 算「这一行是第几格」），
+ * 两处都调本函数 ⇒ 顺序只有一个来源，不会各自摊一遍。返回的是**原对象引用**
+ * （选项对象来自消费方传入的同一批数据），故列表侧可以直接用 `indexOf` 反查格号。
+ */
+export declare const activatableOptions: (items: SelectItem[]) => SelectOption[];
+/**
+ * 可激活格总数。
+ *
+ * `creatable` 时**末尾多一格**「创建 xxx」行 —— 它也是可激活的一格（回车即创建），
+ * 键位模型与 id 生成都按「选项格 + 尾格」这同一条约定走。
+ */
+export declare const activatableCount: (items: SelectItem[], creatable: boolean) => number;
+/**
+ * 选项行 / 「创建」行的元素 id。
+ *
+ * 两处用途：`aria-activedescendant` 指过来（原生 popover 下的虚拟焦点，见 `Select`），
+ * 以及消费方与用例的稳定锚点。格号由 `activatableOptions` 的顺序给，与值本身无关
+ * （值可能含空格，直接拼进 id 会破坏 `aria-activedescendant` 的引用）。
+ */
+export declare const optionDomId: (panelId: string, index: number) => string;
 /** 生成全页唯一的面板 id（随机段与全库其它随机 id 同法） */
 export declare const createSelectPanelId: () => string;
 /**
@@ -45,19 +69,36 @@ export interface TriggerKeydownOptions {
     clear: () => void;
     openPanel: () => void;
     /**
-     * 面板打开后把焦点落到某一项上（**可选**）。
+     * 面板当前是否开着（**只服务 `Enter` / `Space` 的接管判定**，可选）。
+     *
+     * 开着才把这两个键从触发器的原生行为（开 / 收面板）里抢过来交给高亮项；
+     * 关着时必须原样放过 —— 否则「关掉面板后再按回车」不会重开面板。
+     */
+    isPanelOpen?: () => boolean;
+    /**
+     * 面板打开后把**键盘高亮**平移一格（**可选**）。
+     *
+     * 注意它**不移动焦点**：选项行不是可聚焦元素（`div[role='option']`），高亮由 `data-active`
+     * 与 `aria-activedescendant` 表达（见 `Select`）。入参是**方向**而不是下标：
+     * 尚无高亮时落到首项（向下）或末项（向上）。
+     * 列表形态给上它；树形态不给 —— 树的行既不可聚焦也不做键盘导航（与 `Tree` 自身同口径）。
+     */
+    moveActive?: (direction: 1 | -1) => void;
+    /**
+     * 提交当前高亮项（**可选**），返回**是否真的提交了**。
      *
-     * 列表形态给上它（选项是真实 `<button>`，焦点即高亮）；树形态不给 ——
-     * 树的行是 `div`、没有 tabindex，焦点无处可落。
+     * 有高亮才返回 `true`（此时键被接管：`preventDefault`，不再切换面板）；
+     * 没有高亮就返回 `false`，`Enter` / `Space` 回落到按钮的原生切换行为。
      */
-    focusFirst?: (direction: 1 | -1) => void;
+    commitActive?: () => boolean;
 }
 /**
  * 触发器上的键盘契约（`Select` 与 `SelectTree` 共用一份）。
  *
- * `Delete` 清值、`↑` / `↓` 开面板（并可选聚焦首 / 末项）—— 这一对是**触发器形态**的通用操作，
- * 与「面板里装的是列表还是树」无关，故两件同源。`focusFirst` 的入参是**方向**而不是下标：
- * 列表侧据此在「尚未聚焦任何项」时落到首项（向下）或末项（向上）。
+ * `Delete` 清值、`↑` / `↓` 开面板并可选平移高亮、`Enter` / `Space` 提交高亮项
+ * —— 这几条是**触发器形态**的通用操作，与「面板里装的是列表还是树」无关，故两件同源。
+ * 与改前的一处差别：不再 `requestAnimationFrame` 等一帧等面板可见（那时是为了 `focus()`），
+ * 现在只改状态、不碰焦点；滚动入视由列表侧自己延后一帧（见 `Select` 的 `scrollActiveIntoView`）。
  */
 export declare function createTriggerKeydown(options: TriggerKeydownOptions): (event: KeyboardEvent) => void;
 /** 供内件声明 ref 属性用的类型别名（面板壳的 elementRef 入参） */

package/dist/components/select/select-shared.js

@@ -1,4 +1,7 @@
 const isGroup = (item) => Array.isArray(item.options);
+const activatableOptions = (items) => items.flatMap((item) => isGroup(item) ? item.options : [item]).filter((option) => !option.disabled);
+const activatableCount = (items, creatable) => activatableOptions(items).length + (creatable ? 1 : 0);
+const optionDomId = (panelId, index) => `${panelId}-opt-${index}`;
 const PANEL_ID_PREFIX = "mh-select-";
 const createSelectPanelId = () => `${PANEL_ID_PREFIX}${Math.random().toString(36).slice(2, 10)}`;
 const showPanel = (element) => element?.showPopover?.();
@@ -10,15 +13,22 @@ function createTriggerKeydown(options) {
       event.preventDefault();
       if (options.disabled) return;
       options.openPanel();
-      const direction = event.key === "ArrowDown" ? 1 : -1;
-      if (options.focusFirst) requestAnimationFrame(() => options.focusFirst?.(direction));
+      options.moveActive?.(event.key === "ArrowDown" ? 1 : -1);
+      return;
+    }
+    if (event.key === "Enter" || event.key === " ") {
+      if (!options.isPanelOpen?.()) return;
+      if (options.commitActive?.()) event.preventDefault();
     }
   };
 }
 export {
+  activatableCount,
+  activatableOptions,
   createSelectPanelId,
   createTriggerKeydown,
   hidePanel,
   isGroup,
+  optionDomId,
   showPanel
 };

package/dist/components/select/select-tree.d.ts

@@ -11,15 +11,15 @@
  *    **整支保留**，并强制全展到命中层（算法与切分都是纯函数，见 `select-tree-filter.ts`）；
  *    命中文本按面层的 `.mh-select__hit` 高亮（靠 `Tree` 的可选 `renderLabel` 钩子落进标签槽）。
  * 3. **面板内限高滚动**：限高归面板（`.mh-select__panel` 的 `--ui-select-panel-max-height`）、
- *    溢出由面板内容区（`.mh-select__body`）承担；本件只把树包在 `.mh-select__tree` 里给内距
- *    —— 限高不由形态自持，列表形态共用同一份。
+ *    溢出与内容内距都由面板内容区（`.mh-select__body`）承担 —— 两形态共用同一份，本件因此
+ *    把树**直接**装进内容区，不再自持一层只给内距的包裹（限高与内距都不由形态自持）。
  *
  * ## 与 `Select` 的三处有意差异（都是「树不是列表」决定的）
  *
  * | 事项 | `Select` | `SelectTree` |
  * | --- | --- | --- |
  * | 值 | `string \| number \| Array<…>` | 只单选、只 `string`（`Tree` 的主键本就 `String()` 化） |
- * | 面板内 ↑↓ 行导航 | 有（选项是真实 `<button>`，焦点即高亮） | **无**（树的行是 `div`、没有 tabindex；`Tree` 自身也不做键盘导航） |
+ * | 面板内 ↑↓ 行导航 | 有（高亮位由 `data-active` 表达，焦点留在触发器上） | **无**（树的行不做键盘导航，与 `Tree` 自身同口径） |
  * | 空 / 加载态 | 列表体的内建行 | 面板内同样出一行文字（**不复用**整件三态容器：下拉里出空态插画太重） |
  *
  * @example 基础单选
@@ -139,6 +139,16 @@ export declare const SelectTree: import("vue").DefineComponent<import("vue").Ext
         type: PropType<(keyword: string) => void>;
         default: undefined;
     };
+    /** 面板里树行的节点图标（标签前的一位图标）：透传给 `Tree.renderIcon` */
+    renderIcon: {
+        type: PropType<(node: TreeNode) => unknown>;
+        default: undefined;
+    };
+    /** 面板里树行的展开 / 收起箭头字形：透传给 `Tree.renderCaret` */
+    renderCaret: {
+        type: PropType<(node: TreeNode, expanded: boolean) => unknown>;
+        default: undefined;
+    };
 }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     'update:modelValue': (v: string) => true;
 }, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
@@ -248,6 +258,16 @@ export declare const SelectTree: import("vue").DefineComponent<import("vue").Ext
         type: PropType<(keyword: string) => void>;
         default: undefined;
     };
+    /** 面板里树行的节点图标（标签前的一位图标）：透传给 `Tree.renderIcon` */
+    renderIcon: {
+        type: PropType<(node: TreeNode) => unknown>;
+        default: undefined;
+    };
+    /** 面板里树行的展开 / 收起箭头字形：透传给 `Tree.renderCaret` */
+    renderCaret: {
+        type: PropType<(node: TreeNode, expanded: boolean) => unknown>;
+        default: undefined;
+    };
 }>> & Readonly<{
     "onUpdate:modelValue"?: ((v: string) => any) | undefined;
 }>, {
@@ -257,6 +277,8 @@ export declare const SelectTree: import("vue").DefineComponent<import("vue").Ext
     loading: boolean;
     labelKey: string;
     childrenKey: string;
+    renderCaret: (node: TreeNode, expanded: boolean) => unknown;
+    renderIcon: (node: TreeNode) => unknown;
     expandedKeys: string[];
     defaultExpandedKeys: string[];
     defaultExpandAll: boolean;

package/dist/components/select/select-tree.js

@@ -113,6 +113,16 @@ const SelectTree = /* @__PURE__ */ defineComponent({
     onSearch: {
       type: Function,
       default: void 0
+    },
+    /** 面板里树行的节点图标（标签前的一位图标）：透传给 `Tree.renderIcon` */
+    renderIcon: {
+      type: Function,
+      default: void 0
+    },
+    /** 面板里树行的展开 / 收起箭头字形：透传给 `Tree.renderCaret` */
+    renderCaret: {
+      type: Function,
+      default: void 0
     }
   },
   emits: {
@@ -184,7 +194,8 @@ const SelectTree = /* @__PURE__ */ defineComponent({
       disabled: props.disabled,
       clear,
       openPanel: () => showPanel(panelRef.value)
-      /* 有意不给 `focusFirst`：树的行是 `div`、没有 tabindex，面板内不做 ↑↓ 行导航 */
+      /* 有意不给 `moveActive` / `commitActive`：树不做面板内键盘导航（行不可聚焦、与 `Tree` 自身
+         同口径），故 `↑` / `↓` 只开面板、`Enter` / `Space` 仍归按钮的原生切换行为 */
     });
     const renderHitLabel = (node) => createVNode(Fragment, null, [splitHighlight(treeLabel(node, props.labelKey), keyword.value).map((segment, index) => segment.hit ? createVNode("span", {
       "key": index,
@@ -228,9 +239,7 @@ const SelectTree = /* @__PURE__ */ defineComponent({
               "class": "mh-select__option mh-select__option--empty"
             }, [props.emptyText]);
           }
-          return createVNode("div", {
-            "class": "mh-select__tree"
-          }, [createVNode(Tree, {
+          return createVNode(Tree, {
             "nodes": visibleNodes.value,
             "rowKey": props.rowKey,
             "labelKey": props.labelKey,
@@ -239,8 +248,10 @@ const SelectTree = /* @__PURE__ */ defineComponent({
             "expandedKeys": expandedKeys.value,
             "onExpandChange": handleExpandChange,
             "onSelect": pick,
-            "renderLabel": highlightLabel
-          }, null)]);
+            "renderLabel": highlightLabel,
+            "renderIcon": props.renderIcon,
+            "renderCaret": props.renderCaret
+          }, null);
         }
       })]);
     };

package/dist/components/select/select-trigger.d.ts

@@ -45,6 +45,16 @@ export declare const SelectTrigger: import("vue").DefineComponent<import("vue").
         type: StringConstructor;
         default: undefined;
     };
+    /**
+     * 键盘高亮行的 id（`aria-activedescendant`，**列表形态专用**）。
+     *
+     * 选项是 `div[role='option']`、不可聚焦，焦点留在本按钮上 ⇒ 高亮项要靠这个属性告诉读屏。
+     * 树形态不给（树的行不做键盘导航，见 `SelectTree`）。
+     */
+    activeDescendant: {
+        type: StringConstructor;
+        default: undefined;
+    };
     /** 触发器上的键盘契约（`createTriggerKeydown()` 产出，两件同源） */
     onKeydown: {
         type: PropType<(event: KeyboardEvent) => void>;
@@ -104,6 +114,16 @@ export declare const SelectTrigger: import("vue").DefineComponent<import("vue").
         type: StringConstructor;
         default: undefined;
     };
+    /**
+     * 键盘高亮行的 id（`aria-activedescendant`，**列表形态专用**）。
+     *
+     * 选项是 `div[role='option']`、不可聚焦，焦点留在本按钮上 ⇒ 高亮项要靠这个属性告诉读屏。
+     * 树形态不给（树的行不做键盘导航，见 `SelectTree`）。
+     */
+    activeDescendant: {
+        type: StringConstructor;
+        default: undefined;
+    };
     /** 触发器上的键盘契约（`createTriggerKeydown()` 产出，两件同源） */
     onKeydown: {
         type: PropType<(event: KeyboardEvent) => void>;
@@ -130,5 +150,6 @@ export declare const SelectTrigger: import("vue").DefineComponent<import("vue").
     clearable: boolean;
     hasValue: boolean;
     onClear: () => void;
+    activeDescendant: string;
     renderValue: () => VNodeChild;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/components/select/select-trigger.js

@@ -48,6 +48,16 @@ const SelectTrigger = /* @__PURE__ */ defineComponent({
       type: String,
       default: void 0
     },
+    /**
+     * 键盘高亮行的 id（`aria-activedescendant`，**列表形态专用**）。
+     *
+     * 选项是 `div[role='option']`、不可聚焦，焦点留在本按钮上 ⇒ 高亮项要靠这个属性告诉读屏。
+     * 树形态不给（树的行不做键盘导航，见 `SelectTree`）。
+     */
+    activeDescendant: {
+      type: String,
+      default: void 0
+    },
     /** 触发器上的键盘契约（`createTriggerKeydown()` 产出，两件同源） */
     onKeydown: {
       type: Function,
@@ -80,8 +90,12 @@ const SelectTrigger = /* @__PURE__ */ defineComponent({
         popovertarget: props.panelId,
         "aria-haspopup": "listbox",
         /* 开合态由原生 popover 与 popup.css 的箭头转向承担，本件不维护第二份；
-           恒定 'false' 是既有口径（输入面的触发器形态不跟踪 popover 的开关状态） */
+           恒定 'false' 是既有口径（输入面的触发器形态不跟踪 popover 的开关状态）。
+           ⚠️ 这与 `aria-activedescendant`（下面那条）**都是焦点留在触发器上的必然结果**：
+           真的做完整要连 `aria-expanded` 一起跟踪开合态，那是另一次改动（见 select.md 的注意事项）。 */
         "aria-expanded": "false",
+        /* 高亮行引用（列表形态给、树形态不给）：值 `undefined` 时 Vue 会整个摘掉这个属性 */
+        "aria-activedescendant": props.activeDescendant,
         onKeydown: props.onKeydown
       },
       "onChange": () => props.onClear?.()