@manohub/ui 0.7.1 → 0.8.0

package/dist/components/select/index.js

@@ -1,7 +1,8 @@
-import { defineComponent, ref, computed, createVNode, Fragment, mergeProps, createTextVNode } from "vue";
-import { Icon } from "@manohub/icon";
-import { Input } from "../input/index.js";
-const isGroup = (item) => Array.isArray(item.options);
+import { defineComponent, ref, computed, createVNode, Fragment } from "vue";
+import { SelectList } from "./select-list.js";
+import { SelectPanel } from "./select-panel.js";
+import { SelectTrigger } from "./select-trigger.js";
+import { createSelectPanelId, isGroup, createTriggerKeydown, showPanel, hidePanel } from "./select-shared.js";
 const Select = /* @__PURE__ */ defineComponent({
   name: "Select",
   inheritAttrs: false,
@@ -102,7 +103,7 @@ const Select = /* @__PURE__ */ defineComponent({
     slots,
     attrs
   }) {
-    const panelId = `mh-select-${Math.random().toString(36).slice(2, 10)}`;
+    const panelId = createSelectPanelId();
     const panelRef = ref(null);
     const inner = ref(props.defaultValue);
     const keyword = ref("");
@@ -149,7 +150,7 @@ const Select = /* @__PURE__ */ defineComponent({
       emit("update:modelValue", value);
       props.onChange?.(value);
     };
-    const hidePanel = () => panelRef.value?.hidePopover?.();
+    const hide = () => hidePanel(panelRef.value);
     const pick = (option) => {
       if (option.disabled) return;
       if (props.multiple) {
@@ -158,7 +159,7 @@ const Select = /* @__PURE__ */ defineComponent({
         return;
       }
       commit(option.value);
-      hidePanel();
+      hide();
     };
     const createFromKeyword = () => {
       const value = keyword.value.trim();
@@ -175,104 +176,67 @@ const Select = /* @__PURE__ */ defineComponent({
       const next = at < 0 ? step > 0 ? 0 : items.length - 1 : (at + step + items.length) % items.length;
       items[next].focus();
     };
-    const onTriggerKeydown = (event) => {
-      if (event.key === "Delete" && props.clearable) clear();
-      if (event.key === "ArrowDown" || event.key === "ArrowUp") {
-        event.preventDefault();
-        if (!props.disabled) {
-          panelRef.value?.showPopover?.();
-          requestAnimationFrame(() => moveFocus(event.key === "ArrowDown" ? 0 : -1));
-        }
-      }
-    };
+    const onTriggerKeydown = createTriggerKeydown({
+      clearable: props.clearable,
+      disabled: props.disabled,
+      clear,
+      openPanel: () => showPanel(panelRef.value),
+      focusFirst: (direction) => moveFocus(direction)
+    });
     const onPanelKeydown = (event) => {
       if (event.key === "ArrowDown" || event.key === "ArrowUp") {
         event.preventDefault();
         moveFocus(event.key === "ArrowDown" ? 1 : -1);
       }
     };
-    const renderOption = (option) => createVNode("button", {
-      "key": String(option.value),
-      "type": "button",
-      "class": ["mh-select__option", option.disabled ? "is-disabled" : ""].filter(Boolean).join(" "),
-      "data-state": selectedValues.value.includes(option.value) ? "selected" : "unselected",
-      "disabled": option.disabled,
-      "role": "option",
-      "aria-selected": selectedValues.value.includes(option.value) ? "true" : "false",
-      "onClick": () => pick(option)
-    }, [option.label]);
     return () => {
       const hasValue = selectedValues.value.length > 0;
       return createVNode("div", {
         "class": ["mh-popup-host", attrs.class].filter(Boolean).join(" "),
         "style": attrs.style
-      }, [createVNode(Input, {
-        "as": "button",
+      }, [createVNode(SelectTrigger, {
+        "panelId": panelId,
         "size": props.size,
         "status": props.status,
         "disabled": props.disabled,
         "clearable": props.clearable,
         "hasValue": hasValue,
-        "class": "mh-popup-anchor mh-select-host",
-        "controlClass": ["mh-select", props.multiple ? "mh-select--multiple" : "", props.size === "md" ? "" : `mh-select--${props.size}`].filter(Boolean).join(" "),
-        "controlAttrs": {
-          popovertarget: panelId,
-          "aria-haspopup": "listbox",
-          "aria-expanded": "false",
-          onKeydown: onTriggerKeydown
-        },
-        "onChange": clear
-      }, {
-        default: () => props.multiple ? createVNode(Fragment, null, [visibleTags.value.map((option) => createVNode("span", {
+        "multiple": props.multiple,
+        "placeholder": props.placeholder,
+        "label": selectedOptions.value[0]?.label,
+        "onKeydown": onTriggerKeydown,
+        "onClear": clear,
+        "renderValue": props.multiple ? () => createVNode(Fragment, null, [visibleTags.value.map((option) => createVNode("span", {
           "key": String(option.value),
           "class": "mh-select__chip"
         }, [option.label])), foldedCount.value > 0 ? createVNode("span", {
           "class": "mh-select__chip mh-select__chip--fold"
         }, [foldText.value]) : null, !hasValue ? createVNode("span", {
           "class": "mh-select__value mh-select__value--placeholder"
-        }, [props.placeholder]) : null]) : createVNode("span", {
-          "class": ["mh-select__value", hasValue ? "" : "mh-select__value--placeholder"].filter(Boolean).join(" ")
-        }, [selectedOptions.value[0]?.label ?? props.placeholder]),
-        /* 箭头沿用输入框的右侧图标位（本次不开放自定义入口） */
-        suffix: () => createVNode(Icon, {
-          "name": "chevron-down",
-          "class": "mh-select__caret mh-popup-caret"
-        }, null)
-      }), createVNode("div", mergeProps({
-        "ref": panelRef,
-        "id": panelId
-      }, {
-        popover: "auto"
-      }, {
-        "class": "mh-popup mh-select__panel mh-popup--anchored",
-        "data-side": "bottom",
-        "data-align": "start",
-        "role": "listbox",
+        }, [props.placeholder]) : null]) : void 0
+      }, null), createVNode(SelectPanel, {
+        "id": panelId,
+        "elementRef": panelRef,
+        "searchable": showSearch.value,
+        "keyword": keyword.value,
+        "onKeyword": (value) => {
+          keyword.value = value;
+          props.onSearch?.(value);
+        },
         "onKeydown": onPanelKeydown
-      }), [showSearch.value ? createVNode("div", {
-        "class": "mh-select__search"
-      }, [createVNode("input", {
-        "class": "mh-input",
-        "value": keyword.value,
-        "placeholder": "搜索",
-        "onInput": (event) => {
-          keyword.value = event.target.value;
-          props.onSearch?.(keyword.value);
-        }
-      }, null)]) : null, props.loading ? createVNode("span", {
-        "class": "mh-select__option mh-select__option--hint"
-      }, [createTextVNode("加载中…")]) : visibleOptions.value.length === 0 && !creatable.value ? slots.empty ? slots.empty() : createVNode("span", {
-        "class": "mh-select__option mh-select__option--empty"
-      }, [props.emptyText]) : createVNode(Fragment, null, [visibleOptions.value.map((item, index) => isGroup(item) ? createVNode("div", {
-        "key": `group-${index}`,
-        "class": "mh-select__group"
-      }, [createVNode("span", {
-        "class": "mh-select__group-label"
-      }, [item.label]), item.options.map((option) => renderOption(option))]) : renderOption(item)), creatable.value ? createVNode("button", {
-        "type": "button",
-        "class": "mh-select__option mh-select__add",
-        "onClick": createFromKeyword
-      }, [createTextVNode("创建「"), keyword.value.trim(), createTextVNode("」")]) : null])])]);
+      }, {
+        default: () => createVNode(SelectList, {
+          "options": visibleOptions.value,
+          "selectedValues": selectedValues.value,
+          "loading": props.loading,
+          "emptyText": props.emptyText,
+          "creatable": creatable.value,
+          "keyword": keyword.value,
+          "onPick": pick,
+          "onCreate": createFromKeyword,
+          "renderEmpty": slots.empty
+        }, null)
+      })]);
     };
   }
 });

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

@@ -0,0 +1,125 @@
+/**
+ * SelectList —— 选择器族的**选项列表体内件**（`Select` 用，不对外导出）。
+ *
+ * 它拥有「面板里那一撮选项」的全部形态与状态行：平铺选项 / 分组（组标题不可点）/ 「创建」行 /
+ * 空态行 / 加载行。**不含面板壳与搜索行**（那是 `SelectPanel` 的事），也不持有任何状态 ——
+ * 过滤结果、选中值、是否可创建统统由消费方算好喂进来，本件只渲染。
+ *
+ * 选项是真实 `<button role="option">`（不是 div + JS 高亮）：键盘可达、`:focus-visible` 可直接
+ * 承载「高亮行」这层语义，于是不需要再维护一份 JS 高亮下标 —— **焦点即高亮**，
+ * 状态只有 DOM 焦点一个来源。四条按钮重置（`border` / `background` / `font-family` /
+ * `text-align`）在面上自带（reset 层清了前三条、`text-align` 属列表行语义故面里显式写），
+ * 否则选项会长成原生按钮的灰底立体框 —— 见 `select.css` 的 `.mh-select__option` 一节。
+ *
+ * 选中态**三源等价**（面层只写一份声明）：组件下发 `[data-state='selected']` /
+ * 原生 `:has(input:checked)`（静态页零 JS 单选路径）/ `.is-selected`（规格冻结档）。
+ */
+import { type PropType, type VNodeChild } from 'vue';
+import { type SelectItem, type SelectOption } from './select-shared';
+export declare const SelectList: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    /** 已经过滤过的渲染树（分组内全空则由消费方整组去掉） */
+    options: {
+        type: PropType<SelectItem[]>;
+        default: () => never[];
+    };
+    /** 当前选中值（多选为数组；只用于判定选项行的选中态） */
+    selectedValues: {
+        type: PropType<Array<string | number>>;
+        default: () => never[];
+    };
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    emptyText: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 可创建：搜索词无命中时由消费方判定，本件只负责渲染那一行 */
+    creatable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 当前搜索词（「创建「xxx」」那一行的文案来源） */
+    keyword: {
+        type: StringConstructor;
+        default: string;
+    };
+    onPick: {
+        type: PropType<(option: SelectOption) => void>;
+        default: undefined;
+    };
+    onCreate: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+    /**
+     * 空态自定义内容。
+     *
+     * 用**函数 prop** 而不是插槽：内件不对外，插槽还要多一层 `SlotsType` 签名与父层的对象写法，
+     * 而这一处只有「给或是不给」两种。返回 `undefined` 即走内建的空态行。
+     */
+    renderEmpty: {
+        type: PropType<() => VNodeChild>;
+        default: undefined;
+    };
+}>, () => string | number | boolean | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}> | import("vue").VNodeArrayChildren, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    /** 已经过滤过的渲染树（分组内全空则由消费方整组去掉） */
+    options: {
+        type: PropType<SelectItem[]>;
+        default: () => never[];
+    };
+    /** 当前选中值（多选为数组；只用于判定选项行的选中态） */
+    selectedValues: {
+        type: PropType<Array<string | number>>;
+        default: () => never[];
+    };
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    emptyText: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 可创建：搜索词无命中时由消费方判定，本件只负责渲染那一行 */
+    creatable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 当前搜索词（「创建「xxx」」那一行的文案来源） */
+    keyword: {
+        type: StringConstructor;
+        default: string;
+    };
+    onPick: {
+        type: PropType<(option: SelectOption) => void>;
+        default: undefined;
+    };
+    onCreate: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+    /**
+     * 空态自定义内容。
+     *
+     * 用**函数 prop** 而不是插槽：内件不对外，插槽还要多一层 `SlotsType` 签名与父层的对象写法，
+     * 而这一处只有「给或是不给」两种。返回 `undefined` 即走内建的空态行。
+     */
+    renderEmpty: {
+        type: PropType<() => VNodeChild>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    loading: boolean;
+    options: SelectItem[];
+    selectedValues: (string | number)[];
+    emptyText: string;
+    creatable: boolean;
+    keyword: string;
+    onPick: (option: SelectOption) => void;
+    onCreate: () => void;
+    renderEmpty: () => VNodeChild;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

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

@@ -0,0 +1,95 @@
+import { defineComponent, createVNode, createTextVNode, Fragment } from "vue";
+import { isGroup } from "./select-shared.js";
+const SelectList = /* @__PURE__ */ defineComponent({
+  name: "SelectList",
+  inheritAttrs: false,
+  props: {
+    /** 已经过滤过的渲染树（分组内全空则由消费方整组去掉） */
+    options: {
+      type: Array,
+      default: () => []
+    },
+    /** 当前选中值（多选为数组；只用于判定选项行的选中态） */
+    selectedValues: {
+      type: Array,
+      default: () => []
+    },
+    loading: {
+      type: Boolean,
+      default: false
+    },
+    emptyText: {
+      type: String,
+      default: "暂无数据"
+    },
+    /** 可创建：搜索词无命中时由消费方判定，本件只负责渲染那一行 */
+    creatable: {
+      type: Boolean,
+      default: false
+    },
+    /** 当前搜索词（「创建「xxx」」那一行的文案来源） */
+    keyword: {
+      type: String,
+      default: ""
+    },
+    onPick: {
+      type: Function,
+      default: void 0
+    },
+    onCreate: {
+      type: Function,
+      default: void 0
+    },
+    /**
+     * 空态自定义内容。
+     *
+     * 用**函数 prop** 而不是插槽：内件不对外，插槽还要多一层 `SlotsType` 签名与父层的对象写法，
+     * 而这一处只有「给或是不给」两种。返回 `undefined` 即走内建的空态行。
+     */
+    renderEmpty: {
+      type: Function,
+      default: void 0
+    }
+  },
+  setup(props) {
+    const renderOption = (option) => {
+      const selected = props.selectedValues.includes(option.value);
+      return createVNode("button", {
+        "key": String(option.value),
+        "type": "button",
+        "class": ["mh-select__option", option.disabled ? "is-disabled" : ""].filter(Boolean).join(" "),
+        "data-state": selected ? "selected" : "unselected",
+        "disabled": option.disabled,
+        "role": "option",
+        "aria-selected": selected ? "true" : "false",
+        "onClick": () => props.onPick?.(option)
+      }, [option.label]);
+    };
+    return () => {
+      if (props.loading) {
+        return createVNode("span", {
+          "class": "mh-select__option mh-select__option--hint"
+        }, [createTextVNode("加载中…")]);
+      }
+      if (props.options.length === 0 && !props.creatable) {
+        const custom = props.renderEmpty?.();
+        return custom !== void 0 && custom !== null ? custom : createVNode("span", {
+          "class": "mh-select__option mh-select__option--empty"
+        }, [props.emptyText]);
+      }
+      return createVNode(Fragment, null, [props.options.map((item, index) => isGroup(item) ? createVNode("div", {
+        "key": `group-${index}`,
+        "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]);
+    };
+  }
+});
+export {
+  SelectList
+};

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

@@ -0,0 +1,106 @@
+/**
+ * SelectPanel —— 选择器族的**面板壳内件**（`Select` 与 `SelectTree` 共用，不对外导出）。
+ *
+ * 它只拥有三样东西：**原生 popover 元素**（开合 / Esc / 点外部关闭 / 顶层渲染 / 定位全归浏览器）、
+ * **搜索行**（面板顶部那一个输入框）、以及**内容槽**（列表体或树体）。
+ * 「面板里装什么」不在本件 —— 这正是让列表与树共用同一份面板皮肤的原因。
+ *
+ * 组合类名与服务端三条属性都是**操作层的组合**，不是本件新造的浮层：
+ * `class="mh-popup mh-select__panel mh-popup--anchored"`（状态根 + 本族皮肤 + 显式锚档）、
+ * `data-side` / `data-align`（`popup.css` 的定位档）、`popover="auto"`（原生轻 dismiss）。
+ * 面板宽度跟触发器走：`select.css` 的 `.mh-select__panel` 用 `anchor-size(width)` 取锚点宽，
+ * 锚是挂在**表壳**上的 `.mh-popup-anchor`（触发器进壳后隐式锚会缩成壳内控件，故走显式锚档）。
+ *
+ * `elementRef` 是**由消费方持有的 ref**（不是本件自己的）：开面板（触发器 ↑↓）、收起面板（选中后）、
+ * 以及列表形态的 `.mh-select__option` 焦点遍历都要在父层拿到这个 DOM 元素。
+ */
+import { type PropType, type SlotsType, type VNodeChild } from 'vue';
+import type { ElementRef } from './select-shared';
+export declare const SelectPanel: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    /** 面板 id（必须与触发器的 `popovertarget` 成对） */
+    id: {
+        type: StringConstructor;
+        required: true;
+    };
+    /** 面板元素的 ref，由消费方持有（父层要用它开合与遍历选项） */
+    elementRef: {
+        type: PropType<ElementRef>;
+        default: undefined;
+    };
+    /** 是否渲染搜索行（列表形态：`searchable` 或选项多于 8 条；树形态同口径） */
+    searchable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    keyword: {
+        type: StringConstructor;
+        default: string;
+    };
+    searchPlaceholder: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 搜索词变化（消费方负责写回 keyword，并自行决定要不要上抛 `onSearch`） */
+    onKeyword: {
+        type: PropType<(keyword: string) => void>;
+        default: undefined;
+    };
+    /**
+     * 面板上的键盘契约。
+     *
+     * 列表形态给 `↑↓` 移动高亮行（选项是真实 `<button>`，焦点即高亮）；树形态不给 ——
+     * 树的行是 `div`、没有 tabindex，焦点无处可落（与 `Tree` 自身不做键盘导航同口径）。
+     */
+    onKeydown: {
+        type: PropType<(event: KeyboardEvent) => 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: {
+        type: StringConstructor;
+        required: true;
+    };
+    /** 面板元素的 ref，由消费方持有（父层要用它开合与遍历选项） */
+    elementRef: {
+        type: PropType<ElementRef>;
+        default: undefined;
+    };
+    /** 是否渲染搜索行（列表形态：`searchable` 或选项多于 8 条；树形态同口径） */
+    searchable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    keyword: {
+        type: StringConstructor;
+        default: string;
+    };
+    searchPlaceholder: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 搜索词变化（消费方负责写回 keyword，并自行决定要不要上抛 `onSearch`） */
+    onKeyword: {
+        type: PropType<(keyword: string) => void>;
+        default: undefined;
+    };
+    /**
+     * 面板上的键盘契约。
+     *
+     * 列表形态给 `↑↓` 移动高亮行（选项是真实 `<button>`，焦点即高亮）；树形态不给 ——
+     * 树的行是 `div`、没有 tabindex，焦点无处可落（与 `Tree` 自身不做键盘导航同口径）。
+     */
+    onKeydown: {
+        type: PropType<(event: KeyboardEvent) => void>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    onKeydown: (event: KeyboardEvent) => void;
+    keyword: string;
+    elementRef: ElementRef;
+    searchable: boolean;
+    searchPlaceholder: string;
+    onKeyword: (keyword: string) => void;
+}, SlotsType<{
+    default?: () => VNodeChild;
+}>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

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

@@ -0,0 +1,72 @@
+import { defineComponent, createVNode, mergeProps } from "vue";
+const SelectPanel = /* @__PURE__ */ defineComponent({
+  name: "SelectPanel",
+  inheritAttrs: false,
+  props: {
+    /** 面板 id（必须与触发器的 `popovertarget` 成对） */
+    id: {
+      type: String,
+      required: true
+    },
+    /** 面板元素的 ref，由消费方持有（父层要用它开合与遍历选项） */
+    elementRef: {
+      type: Object,
+      default: void 0
+    },
+    /** 是否渲染搜索行（列表形态：`searchable` 或选项多于 8 条；树形态同口径） */
+    searchable: {
+      type: Boolean,
+      default: false
+    },
+    keyword: {
+      type: String,
+      default: ""
+    },
+    searchPlaceholder: {
+      type: String,
+      default: "搜索"
+    },
+    /** 搜索词变化（消费方负责写回 keyword，并自行决定要不要上抛 `onSearch`） */
+    onKeyword: {
+      type: Function,
+      default: void 0
+    },
+    /**
+     * 面板上的键盘契约。
+     *
+     * 列表形态给 `↑↓` 移动高亮行（选项是真实 `<button>`，焦点即高亮）；树形态不给 ——
+     * 树的行是 `div`、没有 tabindex，焦点无处可落（与 `Tree` 自身不做键盘导航同口径）。
+     */
+    onKeydown: {
+      type: Function,
+      default: void 0
+    }
+  },
+  slots: Object,
+  setup(props, {
+    slots
+  }) {
+    return () => createVNode("div", mergeProps({
+      "ref": props.elementRef,
+      "id": props.id
+    }, {
+      popover: "auto"
+    }, {
+      "class": "mh-popup mh-select__panel mh-popup--anchored",
+      "data-side": "bottom",
+      "data-align": "start",
+      "role": "listbox",
+      "onKeydown": props.onKeydown
+    }), [props.searchable ? createVNode("div", {
+      "class": "mh-select__search"
+    }, [createVNode("input", {
+      "class": "mh-input",
+      "value": props.keyword,
+      "placeholder": props.searchPlaceholder,
+      "onInput": (event) => props.onKeyword?.(event.target.value)
+    }, null)]) : null, slots.default?.()]);
+  }
+});
+export {
+  SelectPanel
+};

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

@@ -0,0 +1,64 @@
+/**
+ * 选择器族的**共用原子**（类型、面板 id、popover 开合、触发器键盘契约）。
+ *
+ * 这是 `select/` 目录里的**叶子模块**：它不 import 同目录任何其它文件，因此触发器 / 面板壳 /
+ * 列表体 / 树体四件可以自由地互相组合而不产生环。内件一律**不对外导出**（`src/index.ts` 只出
+ * `Select` 与 `SelectTree`），故本文件的导出面是「族内契约」，改它要同时看那四件。
+ *
+ * 为什么单独一份而不是各自写一遍：这四样都是**跨两件以上**的东西 ——
+ * 类型（列表体与树体都要）、面板 id 生成器（两件的面板都得全页唯一）、
+ * popover 开合（两件都要收起面板）、触发器键盘契约（两件的触发器是同一个形态）。
+ */
+import type { Ref } from 'vue';
+/** 选项（平铺项与分组内选项同构） */
+export interface SelectOption {
+    label: string;
+    value: string | number;
+    disabled?: boolean;
+    /** 分组标题用的标记（内部判别用，消费方不必写） */
+    options?: never;
+}
+/** 分组选项（`{ label: '进行中', options: [...] }`，组内选项与平铺选项同构） */
+export interface SelectOptionGroup {
+    label: string;
+    options: SelectOption[];
+}
+export type SelectItem = SelectOption | SelectOptionGroup;
+export type SelectValue = string | number | Array<string | number>;
+/** 判别：带 `options` 数组的是分组 */
+export declare const isGroup: (item: SelectItem) => item is SelectOptionGroup;
+/** 生成全页唯一的面板 id（随机段与全库其它随机 id 同法） */
+export declare const createSelectPanelId: () => string;
+/**
+ * 开 / 收面板 —— 调的是**原生** `showPopover()` / `hidePopover()`，不是自建浮层逻辑
+ * （面板的开合、Esc、点外部关闭、顶层渲染全归浏览器与 `styles/operations/popup.css`）。
+ *
+ * 先探存在性再调用：jsdom 至今没实现这套 API，直接 `?.()` 会在测试里抛「不是函数」。
+ */
+export declare const showPanel: (element: HTMLElement | null) => void;
+export declare const hidePanel: (element: HTMLElement | null) => void;
+/** 触发器键盘契约的输入 */
+export interface TriggerKeydownOptions {
+    /** 有清除位时才接 `Delete` 清值（与输入框的键盘清除同款） */
+    clearable: boolean;
+    disabled: boolean;
+    clear: () => void;
+    openPanel: () => void;
+    /**
+     * 面板打开后把焦点落到某一项上（**可选**）。
+     *
+     * 列表形态给上它（选项是真实 `<button>`，焦点即高亮）；树形态不给 ——
+     * 树的行是 `div`、没有 tabindex，焦点无处可落。
+     */
+    focusFirst?: (direction: 1 | -1) => void;
+}
+/**
+ * 触发器上的键盘契约（`Select` 与 `SelectTree` 共用一份）。
+ *
+ * `Delete` 清值、`↑` / `↓` 开面板（并可选聚焦首 / 末项）—— 这一对是**触发器形态**的通用操作，
+ * 与「面板里装的是列表还是树」无关，故两件同源。`focusFirst` 的入参是**方向**而不是下标：
+ * 列表侧据此在「尚未聚焦任何项」时落到首项（向下）或末项（向上）。
+ */
+export declare function createTriggerKeydown(options: TriggerKeydownOptions): (event: KeyboardEvent) => void;
+/** 供内件声明 ref 属性用的类型别名（面板壳的 elementRef 入参） */
+export type ElementRef = Ref<HTMLElement | null>;

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

@@ -0,0 +1,24 @@
+const isGroup = (item) => Array.isArray(item.options);
+const PANEL_ID_PREFIX = "mh-select-";
+const createSelectPanelId = () => `${PANEL_ID_PREFIX}${Math.random().toString(36).slice(2, 10)}`;
+const showPanel = (element) => element?.showPopover?.();
+const hidePanel = (element) => element?.hidePopover?.();
+function createTriggerKeydown(options) {
+  return (event) => {
+    if (event.key === "Delete" && options.clearable) options.clear();
+    if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+      event.preventDefault();
+      if (options.disabled) return;
+      options.openPanel();
+      const direction = event.key === "ArrowDown" ? 1 : -1;
+      if (options.focusFirst) requestAnimationFrame(() => options.focusFirst?.(direction));
+    }
+  };
+}
+export {
+  createSelectPanelId,
+  createTriggerKeydown,
+  hidePanel,
+  isGroup,
+  showPanel
+};