@manohub/ui 0.7.1 → 0.8.0

package/README.md

@@ -58,7 +58,7 @@ import { Card, Form, Tree, Checkbox } from '@manohub/ui'
 | 容器与分区 | `Page`（页面级骨架：`.Header` / `.Body` / `.Footer` / `.Filter` / `.Toolbar` / `.Split`）、`Panel`（+ `.Header` / `.Body` / `.Footer`）、`Card`（+ 三件）、`Nav`、`Layout`（`Layout.Row` 排「行」/ `Layout.Column` 排「列」：轴向 × 间距档 × 对齐） |
 | 数据展示 | `Tree`、`ListView`（+ `.CardItem`）、`Badge`、`Tag`（常规 / 状态 / 可选 / 新增 / 筛选片） |
 | 展示 | `Avatar`（+ `.Group`）、`Skeleton`（行 / 列表 / 块状） |
-| 表单基础（**自绘**） | `Button`（+ `.Group` / `.Divider`；五型 / 小号 / 加载 / 菜单按钮 / 连体切换）、`Input`（+ `.Group` / `.Chip` / `.Display` / `.Textarea`；清除 / 可见性切换 / 校验）、`Search`（搜索框：值 / 搜索 / 清空三条回调）、`Select`（单选 / 多选 / 搜索 / 加载；面板用原生 popover）、`Switch`（表格档 / 表单档） |
+| 表单基础（**自绘**） | `Button`（+ `.Group` / `.Divider`；五型 / 小号 / 加载 / 菜单按钮 / 连体切换）、`Input`（+ `.Group` / `.Chip` / `.Display` / `.Textarea`；清除 / 可见性切换 / 校验）、`Search`（搜索框：值 / 搜索 / 清空三条回调）、`Select`（单选 / 多选 / 搜索 / 加载；面板用原生 popover）、`SelectTree`（树形态：仅叶子可选 + 本地过滤 + 命中高亮；与 `Select` 平级导出、共用触发器与面板）、`Switch`（表格档 / 表单档） |
 | 表单与选择 | `Form`（+ `.Header` / `.Item`；标签体系、成员归位、`v-model` 值收集与命令式 `clear()`）、`Filter`（+ `.Item`；`Form` 的壳：条件字段写成子件、控件自放、查询/重置与快照归一）、`Checkbox`、`Radio`（+ `.Group` / `.Card`；卡片式单选）、`Capsule`（胶囊选择器；胶囊 / 方形两档外形，与 `Tabs` 组合即页签） |
 | 反馈与三态 | `Notice`（条状提示）、`Notification`（通知卡：标题 + 头像 / 标签 / 操作 / 关闭位）、`QueryState`（三态容器；内建空 / 错误插画取自设计交付的四张 SVG，原样内联在 `src/utils/state-illustration.ts`）、`Loading`（转圈 + 遮罩：行内 / 区域 / 全屏三形态） |
 | 反馈与引导（**自绘**） | `Toast`（消息提示：语义四档 / loading + 可选动作 + 自动消失计时 + `.Stack` 堆叠）、`Steps`（步骤条：节点式 / 燕尾段式 / `.Progress` 进度条） |

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

@@ -7,6 +7,11 @@ import type { ControlSize } from '../control-size';
  * `danger` 保留在枚举里是**向后兼容**：它等价于 `variant="primary"` 叠加 `danger` 布尔，
  * 语义上「危险」是色彩角色（与主色正交），不是第六种结构形态 ——
  * 故新代码请用 `danger` 布尔修饰任意型，`variant="danger"` 只在旧调用点继续有效。
+ *
+ * `text` 与 `link` 都是无底色档，但**语义不同，别混**：
+ * `text` = 「行内文本操作」（编辑 / 删除 / 更多 / 展开，无下划线）；
+ * `link` = 「跳转语义」（带下划线，像超链接）。
+ *「行内可点文字」一律用它 → `text`。
  */
 export type ButtonVariant = 'primary' | 'secondary' | 'dashed' | 'danger' | 'text' | 'link' | 'icon' | 'off';
 /** 外形档：`round` = 胶囊；`circle` = 正圆（配 `variant="icon"` 用） */
@@ -28,6 +33,7 @@ export type ButtonShape = 'default' | 'round' | 'circle';
  * @example 六型
  * <Button variant="primary" onClick={save}>保存</Button>
  * <Button variant="secondary">取消</Button>
+ * <Button variant="text">编辑</Button>
  * <Button variant="link">查看详情</Button>
  *
  * @example 修饰叠加

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

@@ -13,7 +13,7 @@ export type CardHeaderIcon = string | (() => VNodeChild);
  * 也不得在应用侧写这四类属性 —— 需要不同形态就用本件的维度（`variant` / `interactive` /
  * `selected` / `disabled`），或提为骨架层待建件。
  *
- * ## 几何来源（portal 技能市场卡片实测，逐项落 `--ui-*` 令牌）
+ * ## 几何来源（技能市场卡片实测，逐项落 `--ui-*` 令牌）
  *
  * - 圆角 8（`--ui-radius-md`）、内距 20（`--mh-card-padding`，原型 `p-5`）
  * - 底 `--ui-base-100`、弱描边 `--ui-base-300`（原型 `border-border`）

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

@@ -133,21 +133,15 @@ export interface FormItemProps {
     /** 在两列表单里跨满整行（说明行 / 卡片组 / 表格 / 文本域等整块内容） */
     fullWidth?: boolean;
     /**
-     * **只读文本形态**：传了它（含空串）即不走控件插槽，改为在控件位渲染纯文本 ——
-     * 用于「摘要 / 详情」这类静态表单行（同一个表单里 label 列、行距、错误、说明全部复用）。
+     * **只读展示行**：把 label 降一档**次要色**（与值拉开层级），内容仍走默认插槽。
      *
-     * 空值（`''` / 全空白）由组件统一显示 `—`，消费方不必每处写 `value || '—'`；
-     * 换行符原样保留（SQL where 这类多行文本回显不会被压成一行）。
+     * 用于「摘要 / 详情」这类只读行 —— 控件位可以是文本值，也可以是徽标 / 链接这类非文本内容：
      *
-     * 传了它这一行的 label 会降一档**次要色**（与正文色的值拉开层级），控件行不受影响。
-     */
-    text?: string;
-    /**
-     * **只读展示行**：只把 label 弱化（次要色），内容仍走默认插槽 ——
-     * 用于控件位不是纯文本的只读内容（徽标 / 链接这类）。
-     *
-     * 纯文本一律用 `text`（它自带只读语义，不必再传本开关）；本开关与 `text` 互斥不会冲突 ——
-     * 两个都给时 `text` 优先（`readonly` 只是把 label 的弱化带过去）。
+     * - **文本值**：控件位放 `<Input model-value={…} readonly bordered={false} />` ——
+     *   几何复用输入面（与可编辑输入框**同高、同内距**，值文字落在同一条竖线与中线上），
+     *   并且「无框 + 只读」会自动退掉输入框的交互线索（不显悬停底与聚焦框环，仍可选中复制）；
+     *   空值占位由业务侧自己拼（如 `model-value="v || '—'"`）；
+     * - **非文本内容**：内容直接从默认插槽进，`readonly` 只负责弱化 label。
      */
     readonly?: boolean;
     /**
@@ -199,14 +193,24 @@ export interface FormItemProps {
  * `{ y, x }` 上下 / 左右分别给，缺省 0（贴容器边）。页面里的表单在 `Panel.Body` 里、内距由那块给；
  * **弹窗 / 抽屉里没有别的容器**给内距，就用表单自带的 `padding={{ y: 16, x: 20 }}`。
  *
- * ## 静态表单（摘要 / 详情）
+ * ## 只读值（摘要 / 详情）
+ *
+ * 「向导最后一步的确认摘要」「详情弹窗」不需要另起一套描述列表件 —— 只用表单行本身，
+ * label 列宽、行距、错误与说明全部复用。控件位放**只读 + 无框**的输入框即可（本件不给
+ * 「静态文本」形态：那套几何与输入框迟早会漂开 —— 从前它没有高度与内距，值文字既不在
+ * 输入框那条竖线上、也不在同一条中线上）：
+ *
+ * ```tsx
+ * <Form.Item label="创建人" readonly>
+ *   <Input model-value={row.creator || '—'} readonly bordered={false} />
+ * </Form.Item>
+ * ```
  *
- * `Form.Item` 传 `text` 即切成**只读文本行**，三类行可以在同一个表单里混排 ——
- * label 列宽、行距、错误与说明全部共用，所以「向导最后一步的确认摘要」「详情弹窗」不需要
- * 另起一套描述列表件（自绘表格的 label/value 几何与表单行迟早会漂开）。
- * 空值占位 `—`、长文案折行、换行符保留都由组件给；只读行的 label 自动降一档次要色，
- * 字段名与取值一眼分得开（应用侧写不了 `color`，这层区分只能由组件给）。
- * 控件位要放徽标 / 链接这类**非文本**只读内容时传 `readonly`：内容走默认插槽，label 的弱化照旧。
+ * - **几何与可编辑行完全一致**：值文字与输入框内的值同高、同左缘、同中线，混排时节奏整齐；
+ * - **没有「可编辑」的线索**：不显悬停底色、不给聚焦边框与主色环，但仍可点进去选中 / 复制；
+ * - **空值占位归业务**：组件不再替你把 `''` 显示成 `—`，按上面的写法自己拼；
+ * - **label 弱化**：传 `readonly` 把 label 降一档次要色，字段名与取值一眼分得开；
+ * - 控件位是徽标 / 链接这类**非文本**只读内容时同样传 `readonly`：内容直接走默认插槽。
  *
  * @example
  * <Form labelWidth={120} columns={2}>
@@ -259,12 +263,7 @@ export declare const FormItem: import("vue").DefineComponent<import("vue").Extra
         type: BooleanConstructor;
         default: boolean;
     };
-    /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
-    text: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+    /** 只读展示行（label 弱化）：文本值放 Input 的只读 + 无框形态，非文本内容走默认插槽 */
     readonly: {
         type: BooleanConstructor;
         default: boolean;
@@ -312,12 +311,7 @@ export declare const FormItem: import("vue").DefineComponent<import("vue").Extra
         type: BooleanConstructor;
         default: boolean;
     };
-    /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
-    text: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+    /** 只读展示行（label 弱化）：文本值放 Input 的只读 + 无框形态，非文本内容走默认插槽 */
     readonly: {
         type: BooleanConstructor;
         default: boolean;
@@ -328,7 +322,6 @@ export declare const FormItem: import("vue").DefineComponent<import("vue").Extra
         default: undefined;
     };
 }>> & Readonly<{}>, {
-    text: string;
     name: string;
     label: string;
     error: string;
@@ -714,12 +707,7 @@ export declare const Form: {
             type: BooleanConstructor;
             default: boolean;
         };
-        /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
-        text: {
-            type: StringConstructor;
-            default: undefined;
-        };
-        /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+        /** 只读展示行（label 弱化）：文本值放 Input 的只读 + 无框形态，非文本内容走默认插槽 */
         readonly: {
             type: BooleanConstructor;
             default: boolean;
@@ -767,12 +755,7 @@ export declare const Form: {
             type: BooleanConstructor;
             default: boolean;
         };
-        /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
-        text: {
-            type: StringConstructor;
-            default: undefined;
-        };
-        /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+        /** 只读展示行（label 弱化）：文本值放 Input 的只读 + 无框形态，非文本内容走默认插槽 */
         readonly: {
             type: BooleanConstructor;
             default: boolean;
@@ -783,7 +766,6 @@ export declare const Form: {
             default: undefined;
         };
     }>> & Readonly<{}>, {
-        text: string;
         name: string;
         label: string;
         error: string;

package/dist/components/form/index.js

@@ -3,7 +3,6 @@ import { mergePartStyle } from "../part-padding.js";
 const FORM_LABEL_WIDTH = /* @__PURE__ */ Symbol("mh-form-label-width");
 const FORM_CONTROL_WIDTH = /* @__PURE__ */ Symbol("mh-form-control-width");
 const FORM_LABEL_ALIGN = /* @__PURE__ */ Symbol("mh-form-label-align");
-const FORM_TEXT_EMPTY = "—";
 const FORM_STORE = /* @__PURE__ */ Symbol("mh-form-store");
 const FormItem = /* @__PURE__ */ defineComponent({
   name: "FormItem",
@@ -46,12 +45,7 @@ const FormItem = /* @__PURE__ */ defineComponent({
       type: Boolean,
       default: false
     },
-    /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
-    text: {
-      type: String,
-      default: void 0
-    },
-    /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+    /** 只读展示行（label 弱化）：文本值放 Input 的只读 + 无框形态，非文本内容走默认插槽 */
     readonly: {
       type: Boolean,
       default: false
@@ -92,9 +86,6 @@ const FormItem = /* @__PURE__ */ defineComponent({
         "--mh-form-label-width": `${labelWidth}px`
       } : null].filter(Boolean);
       const showLabel = !!props.label || props.required;
-      const hasText = props.text !== void 0;
-      const textIsEmpty = hasText && !props.text.trim();
-      const isReadonlyRow = hasText || props.readonly;
       return createVNode("div", {
         "class": [
           "mh-form-item",
@@ -107,7 +98,7 @@ const FormItem = /* @__PURE__ */ defineComponent({
           // 右对齐是基类默认值，只有左对齐需要额外的修饰类（两处都挂会让「谁胜出」依赖源码顺序）
           labelAlign === "left" ? "mh-form-item--label-left" : "",
           // 只读展示行：label 降一档为次要色，与值拉开层级（样式见 `.mh-form-item--readonly .mh-form-item__label`）
-          isReadonlyRow ? "mh-form-item--readonly" : "",
+          props.readonly ? "mh-form-item--readonly" : "",
           attrs.class
         ].filter(Boolean).join(" "),
         "data-invalid": props.error ? "true" : "false",
@@ -123,16 +114,7 @@ const FormItem = /* @__PURE__ */ defineComponent({
         "style": controlWidth ? {
           maxWidth: `${controlWidth}px`
         } : void 0
-      }, [hasText ? (
-        /*
-         * 只读文本形态（摘要 / 详情行）：控件位直接渲染业务值，占位与换行规则都在组件里
-         * —— 应用侧不再自绘 label/value 表格（那套几何与表单行迟早会漂开）。
-         */
-        createVNode("div", {
-          "class": "mh-form-item__text",
-          "data-empty": textIsEmpty ? "true" : "false"
-        }, [textIsEmpty ? FORM_TEXT_EMPTY : props.text])
-      ) : slots.default?.(scope())]), props.error ? createVNode("div", {
+      }, [slots.default?.(scope())]), props.error ? createVNode("div", {
         "class": "mh-form-item__error"
       }, [props.error]) : null, props.hint ? createVNode("div", {
         "class": "mh-form-item__hint"

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

@@ -68,6 +68,14 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         type: BooleanConstructor;
         default: boolean;
     };
+    /**
+     * **只读**：值可选中 / 复制，但不能改。
+     *
+     * 与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是 `Form.Item`
+     * 的 `readonly` 行推荐的写法）：几何与可编辑输入框**完全一致**（同高、同内距、值文字同左缘），
+     * 但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
+     * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+     */
     readonly: {
         type: BooleanConstructor;
         default: boolean;
@@ -87,7 +95,10 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         type: BooleanConstructor;
         default: boolean;
     };
-    /** 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底） */
+    /**
+     * 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底，靠悬停与聚焦给反馈）。
+     * 配 `readonly` 即**只读值档**：连悬停底与聚焦框环都退掉（见 `readonly`）。
+     */
     bordered: {
         type: BooleanConstructor;
         default: boolean;
@@ -167,6 +178,14 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         type: BooleanConstructor;
         default: boolean;
     };
+    /**
+     * **只读**：值可选中 / 复制，但不能改。
+     *
+     * 与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是 `Form.Item`
+     * 的 `readonly` 行推荐的写法）：几何与可编辑输入框**完全一致**（同高、同内距、值文字同左缘），
+     * 但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
+     * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+     */
     readonly: {
         type: BooleanConstructor;
         default: boolean;
@@ -186,7 +205,10 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         type: BooleanConstructor;
         default: boolean;
     };
-    /** 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底） */
+    /**
+     * 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底，靠悬停与聚焦给反馈）。
+     * 配 `readonly` 即**只读值档**：连悬停底与聚焦框环都退掉（见 `readonly`）。
+     */
     bordered: {
         type: BooleanConstructor;
         default: boolean;
@@ -276,6 +298,7 @@ export interface TextareaProps {
     /** 尺寸档 */
     size?: ControlSize;
     disabled?: boolean;
+    /** 只读（配 `bordered={false}` 即只读值档，口径见 `Input` 的同名 prop） */
     readonly?: boolean;
     /** 校验态（下发 `aria-invalid`） */
     invalid?: boolean;
@@ -289,7 +312,15 @@ export interface TextareaProps {
     autofocus?: boolean;
     onChange?: (v: string) => void;
 }
-/** 多行输入（同一份面；结构与单行不同，故单列一个件） */
+/**
+ * 多行输入（同一份面；结构与单行不同，故单列一个件）。
+ *
+ * ⚠️ 本件**没有** `mono` 档（`Input` 有）。要等宽的输入框别拿 `Text mono` 去包 —— 那会丢掉输入能力；
+ * 该写法目前只能保留一条带 `font-family: var(--ui-font-mono)` 的应用侧样式登记（缺口见包内 `docs/kit-gaps.md`）。
+ *
+ * @example 备注框：自适应 2~6 行 + 限长计数
+ * <Textarea modelValue={note} autoSize={{ minRows: 2, maxRows: 6 }} maxlength={500} showCount onChange={setNote} />
+ */
 export declare const Textarea: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     modelValue: {
         type: StringConstructor;
@@ -319,6 +350,7 @@ export declare const Textarea: import("vue").DefineComponent<import("vue").Extra
         type: BooleanConstructor;
         default: boolean;
     };
+    /** 只读：值可选中 / 复制；配 `bordered={false}` 即只读值档（口径见 `Input` 的同名 prop） */
     readonly: {
         type: BooleanConstructor;
         default: boolean;
@@ -382,6 +414,7 @@ export declare const Textarea: import("vue").DefineComponent<import("vue").Extra
         type: BooleanConstructor;
         default: boolean;
     };
+    /** 只读：值可选中 / 复制；配 `bordered={false}` 即只读值档（口径见 `Input` 的同名 prop） */
     readonly: {
         type: BooleanConstructor;
         default: boolean;
@@ -463,6 +496,14 @@ export declare const InputCompound: {
             type: BooleanConstructor;
             default: boolean;
         };
+        /**
+         * **只读**：值可选中 / 复制，但不能改。
+         *
+         * 与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是 `Form.Item`
+         * 的 `readonly` 行推荐的写法）：几何与可编辑输入框**完全一致**（同高、同内距、值文字同左缘），
+         * 但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
+         * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+         */
         readonly: {
             type: BooleanConstructor;
             default: boolean;
@@ -482,7 +523,10 @@ export declare const InputCompound: {
             type: BooleanConstructor;
             default: boolean;
         };
-        /** 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底） */
+        /**
+         * 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底，靠悬停与聚焦给反馈）。
+         * 配 `readonly` 即**只读值档**：连悬停底与聚焦框环都退掉（见 `readonly`）。
+         */
         bordered: {
             type: BooleanConstructor;
             default: boolean;
@@ -596,6 +640,14 @@ export declare const InputCompound: {
             type: BooleanConstructor;
             default: boolean;
         };
+        /**
+         * **只读**：值可选中 / 复制，但不能改。
+         *
+         * 与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是 `Form.Item`
+         * 的 `readonly` 行推荐的写法）：几何与可编辑输入框**完全一致**（同高、同内距、值文字同左缘），
+         * 但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
+         * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+         */
         readonly: {
             type: BooleanConstructor;
             default: boolean;
@@ -615,7 +667,10 @@ export declare const InputCompound: {
             type: BooleanConstructor;
             default: boolean;
         };
-        /** 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底） */
+        /**
+         * 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底，靠悬停与聚焦给反馈）。
+         * 配 `readonly` 即**只读值档**：连悬停底与聚焦框环都退掉（见 `readonly`）。
+         */
         bordered: {
             type: BooleanConstructor;
             default: boolean;
@@ -720,6 +775,14 @@ export declare const InputCompound: {
         type: BooleanConstructor;
         default: boolean;
     };
+    /**
+     * **只读**：值可选中 / 复制，但不能改。
+     *
+     * 与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是 `Form.Item`
+     * 的 `readonly` 行推荐的写法）：几何与可编辑输入框**完全一致**（同高、同内距、值文字同左缘），
+     * 但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
+     * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+     */
     readonly: {
         type: BooleanConstructor;
         default: boolean;
@@ -739,7 +802,10 @@ export declare const InputCompound: {
         type: BooleanConstructor;
         default: boolean;
     };
-    /** 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底） */
+    /**
+     * 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底，靠悬停与聚焦给反馈）。
+     * 配 `readonly` 即**只读值档**：连悬停底与聚焦框环都退掉（见 `readonly`）。
+     */
     bordered: {
         type: BooleanConstructor;
         default: boolean;
@@ -847,6 +913,7 @@ export declare const InputCompound: {
             type: BooleanConstructor;
             default: boolean;
         };
+        /** 只读：值可选中 / 复制；配 `bordered={false}` 即只读值档（口径见 `Input` 的同名 prop） */
         readonly: {
             type: BooleanConstructor;
             default: boolean;
@@ -910,6 +977,7 @@ export declare const InputCompound: {
             type: BooleanConstructor;
             default: boolean;
         };
+        /** 只读：值可选中 / 复制；配 `bordered={false}` 即只读值档（口径见 `Input` 的同名 prop） */
         readonly: {
             type: BooleanConstructor;
             default: boolean;

package/dist/components/input/index.js

@@ -32,6 +32,14 @@ const Input = /* @__PURE__ */ defineComponent({
       type: Boolean,
       default: false
     },
+    /**
+     * **只读**：值可选中 / 复制，但不能改。
+     *
+     * 与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是 `Form.Item`
+     * 的 `readonly` 行推荐的写法）：几何与可编辑输入框**完全一致**（同高、同内距、值文字同左缘），
+     * 但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
+     * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+     */
     readonly: {
       type: Boolean,
       default: false
@@ -51,7 +59,10 @@ const Input = /* @__PURE__ */ defineComponent({
       type: Boolean,
       default: false
     },
-    /** 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底） */
+    /**
+     * 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底，靠悬停与聚焦给反馈）。
+     * 配 `readonly` 即**只读值档**：连悬停底与聚焦框环都退掉（见 `readonly`）。
+     */
     bordered: {
       type: Boolean,
       default: true
@@ -225,6 +236,7 @@ const Textarea = /* @__PURE__ */ defineComponent({
       type: Boolean,
       default: false
     },
+    /** 只读：值可选中 / 复制；配 `bordered={false}` 即只读值档（口径见 `Input` 的同名 prop） */
     readonly: {
       type: Boolean,
       default: false

package/dist/components/list-view/index.d.ts

@@ -84,7 +84,7 @@ export interface ListViewProps {
  *
  * 以 `Card interactive` 为壳，卡片外观与悬浮反馈都来自它；本件只管卡片**内部**的排版与几何
  * （最小高 144、图标 36、标题 16/600、描述两行截断、尾部贴底、胶囊与标签片），
- * 几何来源同 `Card`（portal 技能市场卡片实测）。
+ * 几何来源同 `Card`（技能市场卡片实测）。
  *
  * 三处「有意为之」：
  * 1. **操作位默认隐藏**（`opacity: 0`），卡片悬浮或卡内获得焦点时显形；触屏（无 hover 能力）恒显形 ——

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

@@ -34,7 +34,7 @@ export declare const Pagination: import("vue").DefineComponent<import("vue").Ext
         type: NumberConstructor;
         default: number;
     };
-    /** 当前页（**1 起**） */
+    /** 当前页（**1 起**；接口用 0 基的话在调用方 ±1 换算，别把 0 基值直接接进来） */
     modelValue: {
         type: NumberConstructor;
         default: number;
@@ -96,7 +96,7 @@ export declare const Pagination: import("vue").DefineComponent<import("vue").Ext
         type: NumberConstructor;
         default: number;
     };
-    /** 当前页（**1 起**） */
+    /** 当前页（**1 起**；接口用 0 基的话在调用方 ±1 换算，别把 0 基值直接接进来） */
     modelValue: {
         type: NumberConstructor;
         default: number;

package/dist/components/pagination/index.js

@@ -9,7 +9,7 @@ const Pagination = /* @__PURE__ */ defineComponent({
       type: Number,
       default: 0
     },
-    /** 当前页（**1 起**） */
+    /** 当前页（**1 起**；接口用 0 基的话在调用方 ±1 换算，别把 0 基值直接接进来） */
     modelValue: {
       type: Number,
       default: 1

package/dist/components/query-state/index.d.ts

@@ -45,13 +45,29 @@ export interface QueryStateProps {
  *
  * 文案 props 可覆盖（i18n 由消费方传 t() 结果；本包不内置文案）。
  *
- * @example 空态带 CTA、错误态带重试
+ * ## 两个容易拿不准的点
+ *
+ * - `empty` 是**触发位**，不是「文案 prop」：`true` 触发并用默认文案；给字符串则**既触发、
+ *   又当空态标题**（副文案仍走 `emptyDescription`）；
+ * - **本件不自带数据源**：`loading` / `error` / `empty` 都由调用方按自己的请求结果给。
+ *   `Table` 自带加载与空两态却**没有错误态** —— 要么只把 error 交给本件，要么整块三态由本件在外层表达：
+ *
+ * @example 列表页：三态在外层，表格只管数据（经典写法）
+ * <QueryState
+ *   loading={isLoading}
+ *   error={loadError}
+ *   :empty="rows.length === 0"
+ *   :error-action-text="t('common.retry')"
+ *   onErrorAction={() => refetch()}>
+ *   <Table :columns="columns" :data="rows" row-key="id" />
+ * </QueryState>
+ *
+ * @example 三态齐备（空态带 CTA、错误态带重试）
  * <QueryState
  *   loading={isLoading}
  *   error={loadError.value}
  *   errorActionText={t('common.retry')}
  *   onErrorAction={() => reload()}
- *   empty={topics.length === 0}
  *   empty={t('topic.empty')}
  *   emptyDescription={t('topic.emptyDescription')}
  *   emptyActionText={t('topic.create')}

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

@@ -1,33 +1,29 @@
-import { type PropType, type SlotsType, type VNodeChild } from 'vue';
-import type { ControlSize } from '../control-size';
-import { type InputStatus } from '../input';
-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>;
 /**
- * 选择器（**自绘**，不封装 farris）。
+ * 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 纯函数：树过滤与命中切分
+ * ```
  *
- * 触发器由 `<Input as="button">` 渲染 —— 框 / 内距 / 边 / 圆角 / 字号 / hover / 聚焦 / 禁用 /
- * 校验色（红·黄）/ **内建清除位** / **右侧图标位**全部来自输入面与它的表壳，本件只提供值 / 标签的排版。
- * 好处是「像输入框」这件事只剩一份规格（改输入框即自动跟随），且清除与右侧图标不必再自绘一套。
- * 三条落点各有其处：`class` → 表壳（显式锚 + 本件对壳的微调）、`controlClass` → 壳内控件（本件排版类）、
- * `controlAttrs` → 控件上的原生语义与键盘契约（`popovertarget` / `aria-*` / `keydown`）。
- * 触发器仍是原生 `<button>`（`popovertarget` 只认 button），故零 JS 开合与隐式锚路径不变；
- * 面板改挂 `mh-popup--anchored`：锚显式钉在**表壳**上 —— 否则隐式锚会缩成壳内控件，
- * 面板不再与整件同宽（`anchor-size(width)` 取的是锚的宽）。
+ * 拆件的收益是**规格只剩一份**：触发器（像输入框 / 清除位 / 箭头 / 键盘开面板）与面板壳
+ * （皮肤 / 定位档 / 显式锚 / 搜索行）在「列表形态」与「树形态」之间是同一份代码，改一处两处都跟着走。
+ * 面上仍是**一个** `styles/components/select.css`（一件的多种形态共用一份面与一个目录）。
+ *
+ * ## 触发器的框不在本件
+ *
+ * 触发器 = 输入框的「触发器形态」（`<Input as="button">`，见 `select-trigger.tsx`）：框 / 内距 /
+ * 边 / 圆角 / 底 / 字 / hover / 聚焦 / 禁用 / 校验色与**清除位**、**右侧图标位**全部归输入面与它的表壳。
+ * 本件只给选择器自己的排版（值 / 标签 / 面板内容）。
  *
  * ## 浮层边界（与「popup 只给零 JS 面」的取舍一致）
  *
@@ -39,7 +35,7 @@ export type SelectValue = string | number | Array<string | number>;
  * ## 状态三源等价
  *
  * 选中行 = `[data-state='selected']`（组件下发）/ 原生 `input:checked`（静态页零 JS 路径）/
- * `.is-selected`（规格冻结档），样式层只写一份声明。
+ * `.is-selected`（规格冻结档），样式层只写一份声明（见 `select-list.tsx`）。
  *
  * @example 单选
  * <Select options={opts} modelValue={v} placeholder="请选择" onChange={setV} />
@@ -50,6 +46,12 @@ export type SelectValue = string | number | Array<string | number>;
  * @example 分组 + 搜索 + 可创建
  * <Select searchable allowCreate multiple options={grouped} modelValue={list} onChange={setList} />
  */
+import { type PropType, type SlotsType, type VNodeChild } from 'vue';
+import type { ControlSize } from '../control-size';
+import type { InputStatus } from '../input';
+import { type SelectItem, type SelectOption, type SelectValue } from './select-shared';
+export type { SelectItem, SelectOption, SelectOptionGroup, SelectValue } from './select-shared';
+export { SelectTree } from './select-tree';
 export declare const Select: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 选项表（平铺项与分组项可混用） */
     options: {
@@ -241,12 +243,12 @@ export declare const Select: import("vue").DefineComponent<import("vue").Extract
     status: InputStatus;
     clearable: boolean;
     onSearch: (keyword: string) => void;
+    emptyText: string;
+    searchable: boolean;
     maxTagCount: number;
     maxTagPlaceholder: string;
-    searchable: boolean;
     filterOption: (option: SelectOption, keyword: string) => boolean;
     allowCreate: boolean;
-    emptyText: string;
 }, SlotsType<{
     empty?: () => VNodeChild;
 }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;