@manohub/ui 1.0.4 → 1.0.6

package/dist/components/radio/index.d.ts

@@ -1,25 +1,24 @@
 import { type PropType, type SlotsType, type VNodeChild } from 'vue';
 import type { ControlSize } from '../control-size';
 /**
- * 单选族（一个文件三成员，对应面 `styles/components/radio.css` 的两段）：
+ * 单选族（一个文件三成员，对应面 `styles/components/radio.css` 的两段）：`Radio`（单个选项 —— 原生路径的
+ * 受控叶，`checked` 由使用方算）、`Radio.Group`（普通单选组 —— 一行一项，横排 16 / 纵排 12）、
+ * `Radio.Card`（卡片式单选组 —— 一个选项一张卡、整卡可点）。
  *
- * - `Radio`：单个选项（原生路径的受控叶，`checked` 由使用方算）
- * - `Radio.Group`：普通单选组 —— 一行一项，横排 16 / 纵排 12
- * - `Radio.Card`：卡片式单选组 —— 一个选项一张卡、整卡可点
+ * **判据**：选项只有一行文字 → `Radio.Group`；选项要「标题 + 说明」且整卡可点 → `Radio.Card`；要按钮形态的
+ * 分组 → `Capsule`（本族不重复造按钮档）。
  *
- * **判据**：选项只有一行文字 → `Radio.Group`；选项要「标题 + 说明」且整卡可点 → `Radio.Card`；
- * 要按钮形态的分组 → `Capsule`（本族不重复造按钮档）。
- *
- * **受控口径（族内统一）**：两个组都是「受控传 `modelValue`，不传即非受控（由 `defaultValue` 起）」，
- * 选中上报 `emit('update:modelValue')`（`v-model` 落地）+ `onChange` 双走 —— 与 `Capsule` /
- * `Checkbox.Group` 同一份口径，故 `v-model` 是本族的推荐写法。
- *
- * **单选组必须有值**：`modelValue` 与非受控初值都没给时，落到**第一个可选项**（跳过禁用项）——
- * 单选语义就是必选其一，与 `Tabs` 的「缺省第一项」同口径；没有可选项（表为空或全禁用）才是空值。
- * 自排插槽（`Radio.Group` 不给 `options`）时组件无从推断有哪些值，缺省值由消费方自定。
+ * **受控口径（族内统一）**：两个组都是「受控传 `modelValue`，不传即非受控（由 `defaultValue` 起）」，选中
+ * 上报 `emit('update:modelValue')` + `onChange` 双走 —— 与 `Capsule` / `Checkbox.Group` 同一份口径，故
+ * `v-model` 是本族的推荐写法。
+ * **单选组必须有值**：`modelValue` 与非受控初值都没给时落到**第一个可选项**（跳过禁用项）—— 单选语义就是
+ * 必选其一，与 `Tabs` 的「缺省第一项」同口径；没有可选项（表为空或全禁用）才是空值。自排插槽
+ * （`Radio.Group` 不给 `options`）时组件无从推断有哪些值，缺省值由消费方自定。
  *
  * 状态表达不统一是**有意的**（各自贴着自己的面）：`Radio` 走原生 `input:checked + .mh-radio__box`
  * （故 **input 必须紧邻框体之前**），`Radio.Card` 走卡片上的 `data-state`（卡片就是 label，圆点在卡内）。
+ *
+ * 用法见 `docs/demos/radio/`（每个维度一份可运行样例；文档页 `docs/components/radio.md`）。
  */
 export interface RadioProps {
     /** 本项的值（组内唯一） */
@@ -43,9 +42,6 @@ export interface RadioProps {
  * 三源等价的选中态由样式层承担（原生 `:checked` / 组件 `[data-state]` / 静态档 `.is-*`），
  * 本件只负责把原生 input 与自绘框体的顺序摆对（**input 必须在框体之前** —— 样式层靠
  * `input:checked + .mh-radio__box` 选态）。
- *
- * @example 单用（自己管互斥）
- * <Radio name="scope" value="all" label="全部" checked={v === 'all'} onChange={setV} />
  */
 export declare const Radio: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     value: {

package/dist/components/search/index.d.ts

@@ -38,45 +38,25 @@ export interface SearchProps {
  * | 图标按钮 | `action="icon"` | ❌（让给按钮） | 主色图标按钮 |
  * | 文案按钮 | `searchText="搜索"` | ✅ | 主色文案按钮 |
  *
- * **框内放大镜与图标按钮不会同时出现** —— 两者是同一个语义的两种画法，
- * 摆在一起就是「一行里两个放大镜，分不出哪个能点」（0.6.0 的缺陷，0.6.1 靠「不给按钮」绕开，
- * 0.7.0 起由 `action="icon"` 把「图标按钮」这一档补上，取图标按钮时框内自动不再画装饰）。
- * 缺省形态的提交走**回车**（`Input` 的 `onEnter` 与 `onSearch` 是同一次语义）。
+ * **框内放大镜与图标按钮不会同时出现** —— 两者是同一个语义的两种画法，摆在一起就是「一行里两个放大镜，分不
+ * 出哪个能点」（0.6.0 的缺陷；0.7.0 起由 `action="icon"` 把「图标按钮」这一档补上，取它时框内自动不再画
+ * 装饰）。缺省形态的提交走**回车**（`Input` 的 `onEnter` 与 `onSearch` 是同一次语义）。
  *
  * ## 为什么不是 `Input` 的一个档，而是单独一件
  *
- * 搜索语义有两件 `Input` 不该背的事：
- * ① **触发是显式的**（回车与点按钮都算一次「搜索」，与「值变了」不是同一件事）——
- *    调用方要的是「提交时查一次」，而不是「每敲一个字查一次」；
- * ② **清空是一个独立事件**（由非空变空时补发 `onClear`）——这是上游控件长期的坑
- *    （清空只改值、不发触发），每处调用都自己写 watch 兜底。
- * 本件把这两条收进一处：`onChange` 管值、`onSearch` / `onClear` 管动作。
+ * 搜索语义有两件 `Input` 不该背的事：① **触发是显式的**（回车与点按钮都算一次「搜索」，与「值变了」不是同一
+ * 件事）—— 调用方要的是「提交时查一次」而不是「每敲一个字查一次」；② **清空是一个独立事件**（由非空变空时补
+ * 发 `onClear`）—— 上游控件长期的坑是「清空只改值、不发触发」，每处调用都自己写 watch 兜底。本件把这两条收
+ * 进一处：`onChange` 管值、`onSearch` / `onClear` 管动作。
  *
  * ## 复用而不是重画
  *
- * 输入框那一段**就是本包的 `Input`**（框、内距、清除位、聚焦态、禁用态、`aria-invalid`
- * 全部沿用输入框面），本件只加「一行里怎么摆」与（可选的）搜索按钮 —— 不另写一份输入框几何
- * （两份几何必然在改令牌时漂开）。
+ * 输入框那一段**就是本包的 `Input`**（框 / 内距 / 清除位 / 聚焦态 / 禁用态 / `aria-invalid` 全部沿用输入框
+ * 面），本件只加「一行里怎么摆」与（可选的）搜索按钮 —— 不另写一份输入框几何（两份几何必然在改令牌时漂开）。
+ * **受控口径与全库同款**：传 `modelValue` 即受控（`update:modelValue` 与 `onChange` 双走），不传即非受控
+ * （由 `defaultValue` 起）。
  *
- * ## 受控口径（与全库同款）
- *
- * 传 `modelValue` 即受控（`update:modelValue` 与 `onChange` 双走），不传即非受控（由 `defaultValue` 起）。
- *
- * @example 最简（框内放大镜 + 回车触发）
- * <Search modelValue={kw} onChange={setKw} onSearch={apply} />
- *
- * @example 带文案的搜索按钮 + 清空动作
- * <Search
- *   modelValue={kw}
- *   placeholder="搜索技能名称"
- *   search-text="搜索"
- *   onChange={setKw}
- *   onSearch={apply}
- *   onClear={() => apply('')}
- * />
- *
- * @example 纯图标按钮（框内不再画装饰放大镜；`searchText` 退化为无障碍名）
- * <Search modelValue={kw} action="icon" search-text="搜索" onChange={setKw} onSearch={apply} />
+ * 用法见 `docs/demos/search/`（每个维度一份可运行样例；文档页 `docs/components/search.md`）。
  */
 export declare const Search: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     modelValue: {

package/dist/components/select/index.d.ts

@@ -1,62 +1,43 @@
 /**
  * Select —— 选择器（**自绘**，不封装 farris）；同目录另出 `SelectTree`（树选择）。
  *
- * 本文件是选择器族的**组装层与出口**：`Select` 与 `SelectTree` 都只是把下面这几个内件拼起来，
- * 内件一律不对外导出（`src/index.ts` 只出 `Select` 与 `SelectTree`，成员不平级、也不挂点号）。
- *
- * ```
- * components/select/
- *   index.tsx            组装层与出口（Select / SelectTree）
- *   select-shared.ts     叶子模块：类型、面板 id、popover 开合、触发器键盘契约
- *   select-trigger.tsx   触发器内件（输入框的「触发器形态」）
- *   select-panel.tsx     面板壳内件（原生 popover + 搜索行 + 内容槽）
- *   select-list.tsx      选项列表体内件（平铺 / 分组 / 创建行 / 空态与加载行）
- *   select-tree.tsx      树体内件（SelectTree 的实现）
- *   select-tree-filter.ts 纯函数：树过滤与命中切分
- * ```
- *
- * 拆件的收益是**规格只剩一份**：触发器（像输入框 / 清除位 / 箭头 / 键盘开面板）与面板壳
- * （皮肤 / 定位档 / 显式锚 / 搜索行）在「列表形态」与「树形态」之间是同一份代码，改一处两处都跟着走。
- * 面上仍是**一个** `styles/components/select.css`（一件的多种形态共用一份面与一个目录）。
+ * 本文件是选择器族的**组装层与出口**：`Select` 与 `SelectTree` 都只是把下面几个内件拼起来，内件一律不对外
+ * 导出（`src/index.ts` 只出这两个，成员不平级、也不挂点号）：
+ * `select-shared.ts`（类型 / 面板 id / popover 开合 / 触发器键盘契约）、`select-trigger.tsx`（触发器内件）、
+ * `select-panel.tsx`（面板壳）、`select-list.tsx`（列表体）、`select-tree.tsx`（树体）、
+ * `select-tree-filter.ts`（纯函数：树过滤与命中切分）。
+ * 拆件的收益是**规格只剩一份**：触发器与面板壳在「列表形态」与「树形态」之间是同一份代码，改一处两处都
+ * 跟着走；面上仍是**一个** `styles/components/select.css`。
  *
  * ## 触发器的框不在本件
  *
- * 触发器 = 输入框的「触发器形态」（`<Input as="button">`，见 `select-trigger.tsx`）：框 / 内距 /
- * 边 / 圆角 / 底 / 字 / hover / 聚焦 / 禁用 / 校验色与**清除位**、**右侧图标位**全部归输入面与它的表壳。
- * 本件只给选择器自己的排版（值 / 标签 / 面板内容）。
+ * 触发器 = 输入框的「触发器形态」（`<Input as="button">`，见 `select-trigger.tsx`）：框 / 内距 / 边 / 圆角 /
+ * 底 / 字 / hover / 聚焦 / 禁用 / 校验色与**清除位**、**右侧图标位**全部归输入面与它的表壳；本件只给选择器
+ * 自己的排版（值 / 标签 / 面板内容）。
  *
  * ## 浮层边界（与「popup 只给零 JS 面」的取舍一致）
  *
- * 面板走**原生 popover**：`<button popovertarget>` + `<div popover>`，开合 / Esc / 点外部关闭 /
- * 顶层渲染 / 定位档全部由浏览器与 `styles/operations/popup.css` 承担，本件**不实现**第二套浮层行为
- * （不做 JS 定位、不做 resize 监听）。本件只补原生做不到的：选中值回填、多选数组的增删与收纳、
- * 搜索过滤与「创建」项、以及键盘的下拉导航（↑↓ 移动高亮行）。
- *
- * **面板有高度上限**：`--ui-select-panel-max-height`（默认 320px，钉在 `select.css` 的面板根上）——
- * 超出即面板内容区（`.mh-select__body`）滚动、搜索行常驻；列表与 `SelectTree` 两形态共用这一份。
+ * 面板走**原生 popover**（`<button popovertarget>` + `<div popover>`）：开合 / Esc / 点外部关闭 / 顶层渲染 /
+ * 定位档全部由浏览器与 `styles/operations/popup.css` 承担，本件**不实现**第二套浮层行为（不做 JS 定位、
+ * 不做 resize 监听），只补原生做不到的：选中值回填、多选数组的增删与收纳、搜索过滤与「创建」项、键盘的
+ * 下拉导航（↑↓ 移动高亮行）。
+ * **面板有高度上限**：`--ui-select-panel-max-height`（默认 320px，钉在 `select.css` 的面板根上）—— 超出即
+ * 面板内容区（`.mh-select__body`）滚动、搜索行常驻；列表与 `SelectTree` 两形态共用这一份。
  *
  * ## 键盘与高亮（焦点**留在触发器上**）
  *
- * 面板里的选项是 `div[role='option']`、**不是 button**、也不可聚焦：高亮位由本件持有
- * （可激活项里的格号），列表体据此下发 `data-active`，触发器上的 `aria-activedescendant`
- * 指到那一行的 id —— 原生 popover 下的「虚拟焦点」标准表达。两条入口共用同一份模型：
- * 触发器（`↑` / `↓` 开面板并平移、`Enter` / `Space` 提交高亮项）与面板内的搜索行
- * （`↑` / `↓` / `Enter` 冒泡到面板）。可激活项 = 摊平 + 跳过禁用项 + （可创建时）末尾那一格
- * 「创建 xxx」行，顺序由 `activatableOptions()` 一处给。
+ * 面板里的选项是 `div[role='option']`、**不是 button**、也不可聚焦：高亮位由本件持有（可激活项里的格号），
+ * 列表体据此下发 `data-active`，触发器上的 `aria-activedescendant` 指到那一行的 id —— 原生 popover 下的
+ * 「虚拟焦点」标准表达。两条入口共用同一份模型：触发器（`↑` / `↓` 开面板并平移、`Enter` / `Space` 提交高亮
+ * 项）与面板内的搜索行（`↑` / `↓` / `Enter` 冒泡到面板）。可激活项 = 摊平 + 跳过禁用项 +（可创建时）末尾
+ * 那一格「创建 xxx」行，顺序由 `activatableOptions()` 一处给。
  *
  * ## 状态三源等价
  *
- * 选中行 = `[data-state='selected']`（组件下发）/ 原生 `input:checked`（静态页零 JS 路径）/
- * `.is-selected`（规格冻结档），样式层只写一份声明（见 `select-list.tsx`）。
- *
- * @example 单选
- * <Select options={opts} modelValue={v} placeholder="请选择" onChange={setV} />
- *
- * @example 多选（超出 maxTagCount 收纳成「其他 n 项」）
- * <Select multiple maxTagCount={2} options={opts} modelValue={list} onChange={setList} />
+ * 选中行 = `[data-state='selected']`（组件下发）/ 原生 `input:checked`（静态页零 JS 路径）/ `.is-selected`
+ * （规格冻结档），样式层只写一份声明（见 `select-list.tsx`）。
  *
- * @example 分组 + 搜索 + 可创建
- * <Select searchable allowCreate multiple options={grouped} modelValue={list} onChange={setList} />
+ * 用法见 `docs/demos/select/`（每个维度一份可运行样例；文档页 `docs/components/select.md`）。
  */
 import { type PropType, type SlotsType, type VNodeChild } from 'vue';
 import type { ControlSize } from '../control-size';
@@ -133,9 +114,9 @@ export declare const Select: import("vue").DefineComponent<import("vue").Extract
         default: undefined;
     };
     /**
-     * 有无边框（框由触发器 `<Input as="button">` 带，三档口径与 `Input` 的同名 prop 完全一致）：
-     * `true`（缺省）常有框 / `false` 无框（常态、悬停、聚焦都不显）/ `'focus'` 聚焦（与悬停）才显框。
-     * 表格单元格里想要「常态像值、点进去才亮框」就用 `'focus'`。
+     * 有无边框（框由触发器 `<Input as="button">` 带，三档口径与 `Input` 的同名 prop 完全一致）：`true`（缺省）
+     * 常有框 / `false` 无框（常态、悬停、聚焦都不显）/ `'focus'` 聚焦（与悬停）才显框 —— 表格单元格里想要
+     * 「常态像值、点进去才亮框」就用 `'focus'`。
      */
     bordered: {
         type: PropType<boolean | "focus">;
@@ -231,9 +212,9 @@ export declare const Select: import("vue").DefineComponent<import("vue").Extract
         default: undefined;
     };
     /**
-     * 有无边框（框由触发器 `<Input as="button">` 带，三档口径与 `Input` 的同名 prop 完全一致）：
-     * `true`（缺省）常有框 / `false` 无框（常态、悬停、聚焦都不显）/ `'focus'` 聚焦（与悬停）才显框。
-     * 表格单元格里想要「常态像值、点进去才亮框」就用 `'focus'`。
+     * 有无边框（框由触发器 `<Input as="button">` 带，三档口径与 `Input` 的同名 prop 完全一致）：`true`（缺省）
+     * 常有框 / `false` 无框（常态、悬停、聚焦都不显）/ `'focus'` 聚焦（与悬停）才显框 —— 表格单元格里想要
+     * 「常态像值、点进去才亮框」就用 `'focus'`。
      */
     bordered: {
         type: PropType<boolean | "focus">;

package/dist/components/select/index.js

@@ -75,9 +75,9 @@ const Select = /* @__PURE__ */ defineComponent({
       default: void 0
     },
     /**
-     * 有无边框（框由触发器 `<Input as="button">` 带，三档口径与 `Input` 的同名 prop 完全一致）：
-     * `true`（缺省）常有框 / `false` 无框（常态、悬停、聚焦都不显）/ `'focus'` 聚焦（与悬停）才显框。
-     * 表格单元格里想要「常态像值、点进去才亮框」就用 `'focus'`。
+     * 有无边框（框由触发器 `<Input as="button">` 带，三档口径与 `Input` 的同名 prop 完全一致）：`true`（缺省）
+     * 常有框 / `false` 无框（常态、悬停、聚焦都不显）/ `'focus'` 聚焦（与悬停）才显框 —— 表格单元格里想要
+     * 「常态像值、点进去才亮框」就用 `'focus'`。
      */
     bordered: {
       type: [Boolean, String],

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

@@ -1,24 +1,22 @@
 /**
  * SelectPanel —— 选择器族的**面板壳内件**（`Select` 与 `SelectTree` 共用，不对外导出）。
  *
- * 它只拥有四样东西：**原生 popover 元素**（开合 / Esc / 点外部关闭 / 顶层渲染 / 定位全归浏览器）、
- * **搜索行**（面板顶部那一个输入框）、**内容区**（`.mh-select__body`，面板里唯一的滚动容器，
- * 也是**两形态共用的一处内容内距** —— 列表的选项与树的树都直接装在它里面，形态里不再各包一层给内距）
- * 与**内容槽**（列表体或树体）。
- * 「面板里装什么」不在本件 —— 这正是让列表与树共用同一份面板皮肤的原因。
+ * 它只拥有四样东西：**原生 popover 元素**（开合 / Esc / 点外部关闭 / 顶层渲染 / 定位全归浏览器）、**搜索行**、**内容区**
+ * （`.mh-select__body`，面板里唯一的滚动容器，也是**两形态共用的一处内容内距** —— 列表的选项与树的树都直接装在它里面，
+ * 形态里不再各包一层给内距）与**内容槽**（列表体或树体）。「面板里装什么」不在本件 —— 这正是让列表与树共用同一份面板
+ * 皮肤的原因。
  *
- * **限高在面层**：面板根上钉着 `--ui-select-panel-max-height`（`select.css`），超出即内容区滚动、
- * 搜索行常驻不滚。内容区这一层因此是**结构性的**（不是可有可无的包裹）：少了它，长列表 / 长树
- * 会把面板一路撑高（实测 60 条选项 2212px），搜索行也会跟着滚走。本件只负责把它渲染出来。
+ * **限高在面层**：面板根上钉着 `--ui-select-panel-max-height`（`select.css`），超出即内容区滚动、搜索行常驻不滚。内容区
+ * 这一层因此是**结构性的**（不是可有可无的包裹）：少了它，长列表 / 长树会把面板一路撑高（实测 60 条选项 2212px），搜索行
+ * 也会跟着滚走。本件只负责把它渲染出来。
  *
- * 组合类名与服务端三条属性都是**操作层的组合**，不是本件新造的浮层：
- * `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`（触发器进壳后隐式锚会缩成壳内控件，故走显式锚档）。
+ * 组合类名与定位属性都是**操作层的组合**，不是本件新造的浮层：`class="mh-popup mh-select__panel mh-popup--anchored"`
+ * （状态根 + 本族皮肤 + 显式锚档）、`data-side` / `data-align`（`popup.css` 的定位档）、`popover="auto"`（原生轻
+ * dismiss）。面板宽度跟触发器走：`.mh-select__panel` 用 `anchor-size(width)` 取锚点宽，锚是挂在**表壳**上的
+ * `.mh-popup-anchor`（触发器进壳后隐式锚会缩成壳内控件，故走显式锚档）。
  *
- * `elementRef` 是**由消费方持有的 ref**（不是本件自己的）：开面板（触发器 ↑↓）、收起面板（选中后）、
- * 以及列表形态按 `[data-active]` 取高亮行（滚动入视）都要在父层拿到这个 DOM 元素。
+ * `elementRef` 是**由消费方持有的 ref**（不是本件自己的）：开面板（触发器 ↑↓）、收起面板（选中后）、以及列表形态按
+ * `[data-active]` 取高亮行（滚动入视）都要在父层拿到这个 DOM 元素。
  */
 import { type PropType, type SlotsType, type VNodeChild } from 'vue';
 import type { ElementRef } from './select-shared';
@@ -52,22 +50,17 @@ export declare const SelectPanel: import("vue").DefineComponent<import("vue").Ex
         default: undefined;
     };
     /**
-     * 面板上的键盘契约（列表形态给，树形态不给）。
-     *
-     * 列表形态接 `↑` / `↓`（平移高亮）与 `Enter`（提交高亮项）。这些事件**来自面板内的搜索行**
-     * —— 选项是 `div[role='option']`、不可聚焦，焦点留在触发器上（触发器那条路走
-     * `createTriggerKeydown()`，两条路共用同一份高亮模型）。树形态不给：树的行不做键盘导航
-     * （与 `Tree` 自身同口径）。
+     * 面板上的键盘契约（列表形态给，树形态不给）：列表形态接 `↑` / `↓`（平移高亮）与 `Enter`（提交高亮项）。这些事件
+     * **来自面板内的搜索行** —— 选项是 `div[role='option']`、不可聚焦，焦点留在触发器上（触发器那条路走
+     * `createTriggerKeydown()`，两条路共用同一份高亮模型）。树形态不给（与 `Tree` 自身同口径）。
      */
     onKeydown: {
         type: PropType<(event: KeyboardEvent) => void>;
         default: undefined;
     };
     /**
-     * 面板的原生 `toggle` 事件（开合态变化，含 Esc 与点外部关闭）。
-     *
-     * 声明成本件的 prop 而不是靠 `attrs`：本件的 `attrs` 是关掉的（`inheritAttrs: false`），
-     * 且这个事件要落到**面板元素**上（`toggle` 只有它派发）。消费方据此回写「面板开着吗」
+     * 面板的原生 `toggle` 事件（开合态变化，含 Esc 与点外部关闭）。声明成 prop 而不是靠 `attrs`：本件的 `attrs` 是关掉的
+     * （`inheritAttrs: false`），且这个事件要落到**面板元素**上（只有它派发 `toggle`）。消费方据此回写「面板开着吗」
      * —— 那是 `Enter` 接管的判定依据（见 `Select` 的 `isPanelOpen`）。
      */
     onToggle: {
@@ -104,22 +97,17 @@ export declare const SelectPanel: import("vue").DefineComponent<import("vue").Ex
         default: undefined;
     };
     /**
-     * 面板上的键盘契约（列表形态给，树形态不给）。
-     *
-     * 列表形态接 `↑` / `↓`（平移高亮）与 `Enter`（提交高亮项）。这些事件**来自面板内的搜索行**
-     * —— 选项是 `div[role='option']`、不可聚焦，焦点留在触发器上（触发器那条路走
-     * `createTriggerKeydown()`，两条路共用同一份高亮模型）。树形态不给：树的行不做键盘导航
-     * （与 `Tree` 自身同口径）。
+     * 面板上的键盘契约（列表形态给，树形态不给）：列表形态接 `↑` / `↓`（平移高亮）与 `Enter`（提交高亮项）。这些事件
+     * **来自面板内的搜索行** —— 选项是 `div[role='option']`、不可聚焦，焦点留在触发器上（触发器那条路走
+     * `createTriggerKeydown()`，两条路共用同一份高亮模型）。树形态不给（与 `Tree` 自身同口径）。
      */
     onKeydown: {
         type: PropType<(event: KeyboardEvent) => void>;
         default: undefined;
     };
     /**
-     * 面板的原生 `toggle` 事件（开合态变化，含 Esc 与点外部关闭）。
-     *
-     * 声明成本件的 prop 而不是靠 `attrs`：本件的 `attrs` 是关掉的（`inheritAttrs: false`），
-     * 且这个事件要落到**面板元素**上（`toggle` 只有它派发）。消费方据此回写「面板开着吗」
+     * 面板的原生 `toggle` 事件（开合态变化，含 Esc 与点外部关闭）。声明成 prop 而不是靠 `attrs`：本件的 `attrs` 是关掉的
+     * （`inheritAttrs: false`），且这个事件要落到**面板元素**上（只有它派发 `toggle`）。消费方据此回写「面板开着吗」
      * —— 那是 `Enter` 接管的判定依据（见 `Select` 的 `isPanelOpen`）。
      */
     onToggle: {

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

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

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

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

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

@@ -1,18 +1,17 @@
 /**
  * SelectTree —— **树选择**（`Select` 的树形态，与它平级导出：`import { SelectTree } from '@manohub/ui'`）。
  *
- * 它与 `Select` 共用**同一批内件**：触发器（像输入框 / 清除位 / 箭头 / 键盘开面板）、
- * 面板壳（皮肤 / 定位档 / 显式锚 / 搜索行）、共用原子（面板 id / popover 开合 / 键盘契约）。
- * 所以「面板长相与开合行为」两件只有一份规格；本件独有的只有**树体那一层**：
+ * 它与 `Select` 共用**同一批内件**：触发器（像输入框 / 清除位 / 箭头 / 键盘开面板）、面板壳（皮肤 / 定位档 /
+ * 显式锚 / 搜索行）、共用原子（面板 id / popover 开合 / 键盘契约）—— 故「面板长相与开合行为」只有一份规格；
+ * 本件独有的只有**树体那一层**：
  *
- * 1. **仅叶子可选**：点叶子行即选中并收起面板；点父节点行只切换展开（不产生选中值）——
- *    父节点是「分组」而不是「选项」，选中它语义上是空的（`Tree` 自身不做这个判断，故在此兜住）。
- * 2. **本地过滤树**：搜索行在场时按关键词过滤，命中节点的**祖先链保留**、父节点自身命中则
- *    **整支保留**，并强制全展到命中层（算法与切分都是纯函数，见 `select-tree-filter.ts`）；
- *    命中文本按面层的 `.mh-select__hit` 高亮（靠 `Tree` 的可选 `renderLabel` 钩子落进标签槽）。
- * 3. **面板内限高滚动**：限高归面板（`.mh-select__panel` 的 `--ui-select-panel-max-height`）、
- *    溢出与内容内距都由面板内容区（`.mh-select__body`）承担 —— 两形态共用同一份，本件因此
- *    把树**直接**装进内容区，不再自持一层只给内距的包裹（限高与内距都不由形态自持）。
+ * 1. **仅叶子可选**：点叶子行即选中并收起面板；点父节点行只切换展开（父节点是「分组」而不是「选项」，选中它
+ *    语义上是空的 —— `Tree` 自身不做这个判断，故在此兜住）。
+ * 2. **本地过滤树**：搜索行在场时按关键词过滤，命中节点的**祖先链保留**、父节点自身命中则**整支保留**，并强制
+ *    全展到命中层（算法与切分都是纯函数，见 `select-tree-filter.ts`）；命中文本按面层的 `.mh-select__hit`
+ *    高亮（靠 `Tree` 的 `renderLabel` 钩子落进标签槽）。
+ * 3. **面板内限高滚动**：限高归面板（`--ui-select-panel-max-height`），溢出与内容内距都由面板内容区
+ *    （`.mh-select__body`）承担 —— 两形态共用同一份，故本件把树**直接**装进内容区，不自持一层只给内距的包裹。
  *
  * ## 与 `Select` 的三处有意差异（都是「树不是列表」决定的）
  *
@@ -22,11 +21,7 @@
  * | 面板内 ↑↓ 行导航 | 有（高亮位由 `data-active` 表达，焦点留在触发器上） | **无**（树的行不做键盘导航，与 `Tree` 自身同口径） |
  * | 空 / 加载态 | 列表体的内建行 | 面板内同样出一行文字（**不复用**整件三态容器：下拉里出空态插画太重） |
  *
- * @example 基础单选
- * <SelectTree nodes={tree} rowKey="id" modelValue={v} onChange={setV} placeholder="请选择业务域" />
- *
- * @example 搜索 + 默认全展开
- * <SelectTree nodes={tree} rowKey="id" labelKey="name" searchable defaultExpandAll onChange={setV} />
+ * 用法见 `docs/demos/select/`（每个维度一份可运行样例；文档页 `docs/components/select.md`）。
  */
 import { type PropType, type SlotsType, type VNodeChild } from 'vue';
 import type { ControlSize } from '../control-size';

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

@@ -21,10 +21,7 @@ export declare const SelectTrigger: import("vue").DefineComponent<import("vue").
         type: BooleanConstructor;
         default: boolean;
     };
-    /**
-     * 有无边框（**直接透传给输入面**，三档口径与 `Input` 的同名 prop 完全一致）：
-     * `true` 常有框 / `false` 无框（任何状态都不显）/ `'focus'` 聚焦（与悬停）才显框。
-     */
+    /** 有无边框（**直接透传给输入面**，三档口径与 `Input` 的同名 prop 完全一致）：`true` 常有框 / `false` 无框（任何状态都不显）/ `'focus'` 聚焦（与悬停）才显框。 */
     bordered: {
         type: PropType<boolean | "focus">;
         default: boolean;
@@ -54,10 +51,8 @@ export declare const SelectTrigger: import("vue").DefineComponent<import("vue").
         default: undefined;
     };
     /**
-     * 键盘高亮行的 id（`aria-activedescendant`，**列表形态专用**）。
-     *
-     * 选项是 `div[role='option']`、不可聚焦，焦点留在本按钮上 ⇒ 高亮项要靠这个属性告诉读屏。
-     * 树形态不给（树的行不做键盘导航，见 `SelectTree`）。
+     * 键盘高亮行的 id（`aria-activedescendant`，**列表形态专用**）：选项是 `div[role='option']`、不可聚焦，焦点留在
+     * 本按钮上 ⇒ 高亮项要靠这个属性告诉读屏。树形态不给（树的行不做键盘导航，见 `SelectTree`）。
      */
     activeDescendant: {
         type: StringConstructor;
@@ -98,10 +93,7 @@ export declare const SelectTrigger: import("vue").DefineComponent<import("vue").
         type: BooleanConstructor;
         default: boolean;
     };
-    /**
-     * 有无边框（**直接透传给输入面**，三档口径与 `Input` 的同名 prop 完全一致）：
-     * `true` 常有框 / `false` 无框（任何状态都不显）/ `'focus'` 聚焦（与悬停）才显框。
-     */
+    /** 有无边框（**直接透传给输入面**，三档口径与 `Input` 的同名 prop 完全一致）：`true` 常有框 / `false` 无框（任何状态都不显）/ `'focus'` 聚焦（与悬停）才显框。 */
     bordered: {
         type: PropType<boolean | "focus">;
         default: boolean;
@@ -131,10 +123,8 @@ export declare const SelectTrigger: import("vue").DefineComponent<import("vue").
         default: undefined;
     };
     /**
-     * 键盘高亮行的 id（`aria-activedescendant`，**列表形态专用**）。
-     *
-     * 选项是 `div[role='option']`、不可聚焦，焦点留在本按钮上 ⇒ 高亮项要靠这个属性告诉读屏。
-     * 树形态不给（树的行不做键盘导航，见 `SelectTree`）。
+     * 键盘高亮行的 id（`aria-activedescendant`，**列表形态专用**）：选项是 `div[role='option']`、不可聚焦，焦点留在
+     * 本按钮上 ⇒ 高亮项要靠这个属性告诉读屏。树形态不给（树的行不做键盘导航，见 `SelectTree`）。
      */
     activeDescendant: {
         type: StringConstructor;

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

@@ -24,10 +24,7 @@ const SelectTrigger = /* @__PURE__ */ defineComponent({
       type: Boolean,
       default: false
     },
-    /**
-     * 有无边框（**直接透传给输入面**，三档口径与 `Input` 的同名 prop 完全一致）：
-     * `true` 常有框 / `false` 无框（任何状态都不显）/ `'focus'` 聚焦（与悬停）才显框。
-     */
+    /** 有无边框（**直接透传给输入面**，三档口径与 `Input` 的同名 prop 完全一致）：`true` 常有框 / `false` 无框（任何状态都不显）/ `'focus'` 聚焦（与悬停）才显框。 */
     bordered: {
       type: [Boolean, String],
       default: true
@@ -57,10 +54,8 @@ const SelectTrigger = /* @__PURE__ */ defineComponent({
       default: void 0
     },
     /**
-     * 键盘高亮行的 id（`aria-activedescendant`，**列表形态专用**）。
-     *
-     * 选项是 `div[role='option']`、不可聚焦，焦点留在本按钮上 ⇒ 高亮项要靠这个属性告诉读屏。
-     * 树形态不给（树的行不做键盘导航，见 `SelectTree`）。
+     * 键盘高亮行的 id（`aria-activedescendant`，**列表形态专用**）：选项是 `div[role='option']`、不可聚焦，焦点留在
+     * 本按钮上 ⇒ 高亮项要靠这个属性告诉读屏。树形态不给（树的行不做键盘导航，见 `SelectTree`）。
      */
     activeDescendant: {
       type: String,
@@ -98,9 +93,8 @@ const SelectTrigger = /* @__PURE__ */ defineComponent({
       "controlAttrs": {
         popovertarget: props.panelId,
         "aria-haspopup": "listbox",
-        /* 开合态由原生 popover 与 popup.css 的箭头转向承担，本件不维护第二份；
-           恒定 'false' 是既有口径（输入面的触发器形态不跟踪 popover 的开关状态）。
-           ⚠️ 这与 `aria-activedescendant`（下面那条）**都是焦点留在触发器上的必然结果**：
+        /* 开合态由原生 popover 与 popup.css 的箭头转向承担，本件不维护第二份；恒定 'false' 是既有口径（输入面的触发器
+           形态不跟踪 popover 的开关状态）。⚠️ 这与 `aria-activedescendant` **都是焦点留在触发器上的必然结果**：
            真的做完整要连 `aria-expanded` 一起跟踪开合态，那是另一次改动（见 select.md 的注意事项）。 */
         "aria-expanded": "false",
         /* 高亮行引用（列表形态给、树形态不给）：值 `undefined` 时 Vue 会整个摘掉这个属性 */

package/dist/components/skeleton/index.d.ts

@@ -20,11 +20,7 @@ export interface SkeletonProps {
  * `@keyframes mh-skeleton-shimmer`），`QueryState` 的加载态复用它 —— 别处不要再写一份
  * （两处各写一份必然漂，同一屏会出现两种呼吸节奏）。
  *
- * @example 列表骨架（5 行）
- * <Skeleton :rows="5" />
- *
- * @example 卡片体占位
- * <Skeleton block height={120} />
+ * 用法见 `docs/demos/skeleton/`（每个维度一份可运行样例；文档页 `docs/components/skeleton.md`）。
  */
 export declare const Skeleton: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     rows: {