knight-ui 1.2.5 → 1.2.6

package/README.md

@@ -83,6 +83,7 @@
   - [Spin 加载中](#spin-加载中)
   - [Feedback 反馈组件](#feedback-反馈组件)
 - Plus 增强
+  - [AttachmentPicker 附件选择器](#attachmentpicker-附件选择器)
   - [Markdown](#markdown)
   - [CodeEditor 代码编辑器](#codeeditor-代码编辑器)
   - [CodeHighlight 代码高亮](#codehighlight-代码高亮)
@@ -97,6 +98,8 @@
   - [AIChatInput AI 对话输入](#aichatinput-ai-对话输入)
   - [AIChatDialogue AI 对话展示](#aichatdialogue-ai-对话展示)
   - [Sidebar AI 侧栏](#sidebar-ai-侧栏)
+- Utility 工具
+  - [AttachmentUtility 附件工具](#attachmentutility-附件工具)
 - Other 其他
   - [ConfigProvider 全局配置](#configprovider-全局配置)
   - [LocaleProvider 国际化](#localeprovider-国际化)
@@ -250,8 +253,8 @@ Token（`--ku-color-glass` / `-strong` / `-head`、`--ku-blur-base` … `-xl`）
 |---|---|---|
 | `ku-glass` | 容器级（侧栏、卡片、面板） | `--ku-color-glass` / `--ku-blur-lg` |
 | `ku-glass-head` | 头部、顶栏 | `--ku-color-glass-head` / `--ku-blur-lg` |
-| `ku-glass-overlay` | 浮层（弹窗、抽屉、筛选面板、Toast / Notification / Feedback，以及 Cascader / AutoComplete / TreeSelect / DatePicker / TimePicker / ColorPicker 的弹层） | `--ku-color-glass-strong` / `--ku-blur-xl` |
-| `ku-glass-menu` | 选项面板（`Dropdown` 与 `Select` 的菜单；其余下拉类弹层尚未换档） | `--ku-color-glass-menu` / `--ku-blur-menu` |
+| `ku-glass-overlay` | 浮层（弹窗、抽屉、筛选面板、Toast / Notification / Feedback，以及 DatePicker / TimePicker / ColorPicker 的弹层） | `--ku-color-glass-strong` / `--ku-blur-xl` |
+| `ku-glass-menu` | 选项面板（`Dropdown` / `Select` / `AutoComplete` 的菜单，以及 `Cascader` / `TreeSelect` 的下拉）—— 判据是"要逐行读的密集文字选项面" | `--ku-color-glass-menu` / `--ku-blur-menu` |
 | `ku-glass-tip` | 小浮层气泡（Popover / Tooltip / Popconfirm / AudioPlayer 与 VideoPlayer 的音量条与倍速菜单 / Chat 的表情面板；`FloatButton` 的按钮也走这一档） | `--ku-color-glass-tip` / `--ku-blur-tip` / `--ku-glass-grain`（`Popconfirm` 再叠一层 `ku-glass-tip-popconfirm` 换膜） |
 | `ku-glass-subtle` | 表格级（面积大，糊太重会糊掉内容） | `--ku-color-glass` / `--ku-blur-base` |
 | `ku-mask` | 遮罩（Modal / SideSheet / Image 预览 / UserGuide / Cropper 裁剪蒙版 / Spin 覆盖层） | `--ku-color-mask` / `--ku-blur-mask` |
@@ -468,7 +471,7 @@ Token（`--ku-color-glass` / `-strong` / `-head`、`--ku-blur-base` … `-xl`）
 | `ku-glass*` / `ku-mask` | 玻璃底色 + 模糊 + `@supports` 回退 | `backdrop-filter` 与 `@supports` 都写不进内联 |
 | `ku-table-*`（行 / 表头 / 排序 / 筛选） | 条纹、悬停、选中、表头吸顶 | 行与表头的内联不含底色 |
 | `ku-calendar-cell*` | 悬停、今天、选中 | 单元格内联刻意只留布局属性 |
-| `ku-select-option*` / `ku-dropdown-item*` / `ku-collapse-header` / `ku-table-filter-item` | 悬停底、选中底、展开过渡 | 内联没写底色（只有 `cursor` 被内联占了） |
+| `ku-select-option*` / `ku-dropdown-item*` / `ku-menu-option*`（`Cascader` / `TreeSelect` 的选项行）/ `ku-collapse-header` / `ku-table-filter-item` | 悬停底、选中底、展开过渡 | 内联没写底色（只有 `cursor` 被内联占了） |
 | `ku-tag` / `ku-scrollbar` / `ku-float-button` | 过渡、滚动条伪元素、悬浮/展开态、玻璃档 | 内联未涉及这些属性；`ku-float-button` 还独占了三项：**底色**（内联已不再写 `background-color`）、**UA 重置**（`appearance: none` / `border: none` —— 少了下标就会露出 UA 的原生 `outset` 斜角环）、以及**阴影的两个状态**（`:hover` 的 `-lg` 与 `box-shadow` 过渡都写不了内联，组件里那句内联 `boxShadow` 因此是删掉的） |
 | `ku-layout-sider-trigger` | 折叠钮的**几何**（绝对定位骑在侧栏右边缘、24px 圆钮）、**UA 重置**（`appearance: none` 等）与不透明底色 | 这些属性内联没写——钮要压出侧栏边缘，位置只能由类给；UA 重置同理，写不进内联的语义里 |
 | `ku-userguide-card` | UserGuide 引导卡片的**不透明**底（`--ku-color-bg-3`） | 卡片不挂玻璃，底色改由类提供（内联原本就没写 `background-color`） |
@@ -1212,12 +1215,59 @@ const data = ["Apple", "Banana", "Orange", "Grape"];
 />
 ```
 
+**"可选可输"**（候选里挑一个，或手打一个候选外的值）：
+
+```tsx
+const models = ["deepseek-chat", "deepseek-reasoner", "qwen-plus"];
+const [model, setModel] = React.useState("");
+
+<AutoComplete
+  data={models}
+  value={model}
+  onChange={setModel}                          // 手输与选中都走这一个
+  onBlur={(value) => setModel(value.trim())}   // 失焦时收尾
+/>
+```
+
+**异步拉候选**（聚焦即拉，敲键再按关键词拉）：
+
+```tsx
+const [data, setData] = React.useState<string[]>([]);
+const [loading, setLoading] = React.useState(false);
+
+<AutoComplete
+  data={data}
+  loading={loading}                  // 必须: 拉取期间置 true
+  filter={false}                     // 必须: 由服务端过滤, 本地别再筛一遍
+  onFocus={() => fetchCandidates("")}
+  onSearch={(keyword) => fetchCandidates(keyword)}
+  onChange={setValue}
+/>
+```
+
 | 属性 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
 | `data` | `(string \| AutoCompleteOption)[]` | — | 数据源 |
-| `filter` | `boolean` | — | 本地过滤 |
-| `onSearch` | `(inputValue) => void` | — | 搜索回调 |
-| `onSelect` | `(option) => void` | — | 选中回调 |
+| `value / defaultValue` | `string` | — | 值（受控 / 非受控） |
+| `filter` | `boolean` | `true` | 本地过滤；关掉即"输入什么就显示什么"（服务端过滤时用） |
+| `onChange` | `(value, option?) => void` | — | 值变化回调，**手输与选中都触发**（手输时 `option` 为空） |
+| `onSearch` | `(inputValue) => void` | — | 搜索回调，敲键时与 `onChange` 同一时刻触发 |
+| `onFocus` | `(value) => void` | — | 聚焦，交出聚焦那一刻的文本 |
+| `onBlur` | `(value) => void` | — | 失焦，交出离开时的文本 |
+| `onSelect` | `(option) => void` | — | 选中回调（要选项对象、含 `extra` 时用它） |
+| `renderItem` | `(option) => ReactNode` | — | 自定义渲染候选项 |
+| `emptyContent` | `ReactNode` | `"无匹配结果"` | 空数据提示 |
+| `loading` | `boolean` | — | 加载中 |
+| `size` | `"small" \| "default" \| "large"` | `"default"` | 尺寸 |
+| `placeholder` | `string` | — | 占位符 |
+
+> **一个"值来源"，三个语义不同的回调**：`onChange` 管"值变了"（手输与选中都触发，**要拿当前值只接它就够**）；`onSearch` 管"该搜了"（敲键时与 `onChange` 同一时刻触发，挂异步请求用）；`onBlur` 管"输完了"（失焦一次，用来 `trim` / 规范化 / 校验这个值是否已知）。三个都留着各接各的 —— 合并会逼着异步场景和值同步场景共用一个口子。
+>
+> **"可选可输"就是 `onChange` + `onBlur` 两个口子**：`onChange` 保证手打一个候选外的值也有人告诉你（这是这个用法唯一容易踩的地方），`onBlur` 给你一个收尾的落点。要选项对象（例如带 `extra`）时另接 `onSelect`。
+>
+> **异步拉候选的两个约定**：① 拉取期间把 `loading` 置 `true` —— 不置的话 `data` 还空着，下拉会先闪一下"无匹配结果"；② 由服务端过滤时 `filter` 传 `false`，否则本地会把服务端返回的结果再筛一遍。
+>
+> 聚焦与失焦都是**先回调再动下拉**，且给的是**那一刻的文本**，不随下拉的开合变化。下拉本身的收起有 150ms 延迟（选项的 `mousedown` 要抢在 `blur` 之前生效，否则点不中候选项）。
 
 ### Transfer 穿梭框
 
@@ -2551,6 +2601,39 @@ import { Feedback } from "knight-ui";
 
 ## Plus 增强
 
+### AttachmentPicker 附件选择器
+
+```tsx
+import { AttachmentPicker, IconPaperclip } from "knight-ui";
+
+<AttachmentPicker
+  accept="image/*,.pdf"
+  maxSize={5 * 1024 * 1024}
+  maxCount={3}
+  count={attachments.length}
+  onPick={(files) => addFiles(files)}
+  onValidateFail={(reason) => Toast.warning(reason.message)}
+>
+  <IconPaperclip size="small" />
+</AttachmentPicker>
+```
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `accept` | `string` | — | 可收类型，与 `<input accept>` 同语法（如 `"image/*,.pdf"`） |
+| `multiple` | `boolean` | `true` | 是否多选 |
+| `maxCount` | `number` | — | 数量上限，与 `count` 一起算剩余名额 |
+| `maxSize` | `number` | — | 单个文件字节上限 |
+| `count` | `number` | — | 已有数量 —— 由调用方喂当前附件数 |
+| `onPick` | `(files: Array<File>) => void` | — | 通过校验的文件 |
+| `onValidateFail` | `(reason: RejectReason) => void` | — | 未通过校验，见 [AttachmentUtility](#attachmentutility-附件工具) |
+
+> **只管"弹框 + 校验"**：点 `children` 触发系统选文件框，选完按 `accept` / `maxSize` / `maxCount` 过滤，通过的交 `onPick`、没通过的交 `onValidateFail`（**提示语由调用方决定，库不自己弹**）。触发体长什么样完全由 `children` 决定，好让各处沿用自己那套按钮样式 —— 上面的 `IconPaperclip` 只是一例，换成一个 `Button` 或一枚图标按钮都行。
+>
+> **不做去重、也不转成 `Attachment`**：交出来的是原始 `File[]`。要不要生成缩略图（`URL.createObjectURL`）、要不要顺带建对象 URL，都是调用方的事；这两步在 `AttachmentUtility.fromFiles` 里有现成的。
+>
+> 每次 `change` 之后会把 input 的值置空，否则**连续选同一个文件不会再触发 change** —— 浏览器只在值发生变化时才派发事件。
+
 ### Markdown
 
 ```tsx
@@ -2880,15 +2963,78 @@ import { AIChatInput } from "knight-ui";
 | `loading` | `boolean` | `false` | 加载中 |
 | `minRows` | `number` | `2` | 最小(初始)行数，不足时留白；被 `style` 撑高也不塌 |
 | `maxRows` | `number` | `4` | 最大行数，超出后框内竖直滚动 |
-| `attachments` | `Attachment[]` | — | 附件列表 |
+| `attachments` | `Attachment[]` | — | 附件列表。**受控**：传了就以它为准，增删只回调（见下方引用块） |
+| `toolbar` | `React.ReactNode` | — | 底部工具条左端内容。**原名 `bottomBar`**，连同新增的 `toolbarEnd` 一起改名。不传则保留 20px 空白垫高 |
+| `toolbarEnd` | `React.ReactNode` | — | 底部工具条右端内容，与 `toolbar` 同一行、自动靠右 |
+| `accept` | `string` | — | 可收附件类型，与 `<input accept>` 同语法（如 `"image/*,.pdf"`），不传则不限 |
+| `multiple` | `boolean` | `true` | 是否允许多选 |
+| `maxCount` | `number` | — | 附件数量上限，不传则不限 |
+| `maxSize` | `number` | — | 单个附件字节上限，不传则不限 |
+| `onAddAttachments` | `(files: Array<File>) => void` | — | 附件通过校验 |
+| `onRemoveAttachment` | `(attachment: Attachment, index: number) => void` | — | 附件被移除 |
+| `onValidateFail` | `(reason: RejectReason) => void` | — | 附件未通过校验，见 [AttachmentUtility](#attachmentutility-附件工具) |
 | `onSend` | `(value, attachments) => void` | — | 发送回调 |
 | `backgroundColor` | `string` | — | 输入框底色。缺省走 `.ku-chat-surface`（暗 `#131620` / 亮 `#f5f6f8`）。**要与 `AIChatDialogue` 一起改** |
 
+多模态（工具栏放附件按钮，附件状态由调用方持有）：
+
+```tsx
+import { AIChatInput, AttachmentPicker, AttachmentUtility, IconPaperclip, Toast } from "knight-ui";
+
+const [attachments, setAttachments] = React.useState<Attachment[]>([]);
+
+const addFiles = (files: Array<File>) =>
+  setAttachments((prev) => [...prev, ...AttachmentUtility.fromFiles(files)]);
+
+<AIChatInput
+  attachments={attachments}
+  accept="image/*"
+  maxCount={4}
+  toolbar={
+    <AttachmentPicker accept="image/*" count={attachments.length} maxCount={4}
+      onPick={addFiles} onValidateFail={(r) => Toast.warning(r.message)}>
+      <IconPaperclip size="small" />
+    </AttachmentPicker>
+  }
+  toolbarEnd={<McpSelect servers={servers} />}
+  onAddAttachments={addFiles}
+  onRemoveAttachment={(a) => setAttachments((prev) => prev.filter((item) => item !== a))}
+  onSend={(text, files) => {
+    // 编码(转 base64 / 拼 FormData)由上层做, 组件只把 File 原样递出来
+    files.forEach(AttachmentUtility.release);
+    setAttachments([]);
+  }}
+/>
+```
+
+**`Attachment` 字段**：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | `string` | 稳定标识 —— 由 `AttachmentUtility.fromFiles` 生成，也允许调用方自带 |
+| `name` | `string` | 文件名 |
+| `size` | `number` | 字节数 |
+| `type` | `string` | MIME |
+| `kind` | `"image" \| "file" \| "audio" \| "video"` | 类别 —— 决定缩略图形状与发送时对应的 part 形态 |
+| `thumbnail` | `string` | 图片缩略图（objectURL / dataURL） |
+| `url` | `string` | 远程地址（已有附件回填时用） |
+| `file` | `File` | 原始文件 —— **编码责任在上层** |
+
+> **三种添加入口**：点 `toolbar` 里的 `AttachmentPicker`、直接 `Ctrl+V` 粘贴、把文件拖到输入框上。三条都按同一套规则校验（`accept` / `maxSize` / `maxCount`，都走 `AttachmentUtility.filter`），但**回调分两个口子**：选择器那条从 `AttachmentPicker.onPick` 出来，粘贴与拖拽那条从 `AIChatInput.onAddAttachments` 出来 —— 因为选择器是独立组件、有自己的 `<input>`，它的 change 不经过 `AIChatInput`。示例里两个口子都接到同一个 `addFiles`，所以不会重复添加；选择器那边记得把当前附件数喂给它的 `count`，否则两条入口各自算名额，`maxCount` 会被突破。粘贴时**以文件为准**：截图粘贴是主场景，剪贴板里顺带的文字与地址不会被一并塞进正文。
+>
+> 拖拽悬停时输入框上会盖一层磨砂遮罩并提示「拖拽可添加附件」，此时描边也换成主色。遮罩走 `.ku-mask`（遮罩档：压暗 34% + `blur(10px) saturate(120%)`），不用玻璃档 —— 带颗粒的 `ku-glass-overlay` / `-tip` / `-menu` **三档叠的是同一颗 `--ku-glass-grain`**，铺满整块输入框时颗粒感明显；遮罩档不含颗粒，且"压暗"本就是遮罩要表达的语义。
+>
+> **纯附件也能发**：`hasContent = 正文非空 || 附件数 > 0`，发送键的可用态与 Enter 的判定用的是同一个值，所以只贴图不写字照样发得出去。
+>
+> **`attachments` 受控 / 非受控**：**不传** = 库自己管 —— 拖拽 / 粘贴 / 选择器直接可用，发送后自动清空，卸载时自动 `AttachmentUtility.release` 归还缩略图；**传了** = 以你为准，库不再改动这个数组，增删只回调（`onAddAttachments` / `onRemoveAttachment`），**缩略图的 `release` 与发送后的清空都由调用方负责** —— 示例里那句 `files.forEach(AttachmentUtility.release)` 干的就是这件事。
+>
+> **组件只收集、不编码**：`onSend` 递出来的是原始 `File`。转 base64、拼 `FormData`、还是先传到对象存储换一个 URL，各家有各家的做法，所以这一层留在外面。
+>
 > **面**：面板挂 `.ku-chat-surface`（**不透明**底，暗 `#131620` / 亮 `#f5f6f8`），与 `AIChatDialogue` / `Chat` **共用这一条类规则**。它是**同一个对话区的下半块**——两块底色必须一致，只改一边会在中间露出一条分界线，所以它跟着对话面板走，而不是像别的输入类控件那样走 `fill-0`（见 `input/Input.tsx`）。它仍是一个**面板**——自带内边距，里面装着 textarea + 附件条 + 发送键——不是 `Input` 那种单字段控件，那个分野没变。内部 textarea 本来就是透明的，附件标签走不透明的 `fill-1`（在这块面上是**更亮**的一档，读起来是一枚筹码）。
 >
 > **`backgroundColor` 只在传了的时候落内联**（`...(backgroundColor ? { backgroundColor } : {})`）。**不能无条件写内联 `backgroundColor`**——内联优先级高于类，写死就把 `.ku-chat-surface` 那一档盖死了。要与 `AIChatDialogue` 一起改，理由同上一段。展开见「对话区的面」。
 >
-> 内边距 `10px 12px`，**横向略大于纵向**：纵向那 10px 会跟 textarea 下面 20px 的垫高叠在一起（发送键就落在右下角那个垫高层里），再大就把键从右下角推离边框；横向是文字起笔的位置，12px 才不显得贴在框上。附件条的横向缩进交给外框提供——它原来自己带 12px，于是比 textarea 多缩进一层、两个左边缘对不齐，现在只留底边距把附件和正文隔开。
+> 内边距 `10px 12px`，**横向略大于纵向**：纵向那 10px 会跟 textarea 下面 20px 的垫高叠在一起（发送键就落在右下角那个垫高层里，那 20px 如今正是 `toolbar` 那一行的 `minHeight`，放了内容就随内容长高），再大就把键从右下角推离边框；横向是文字起笔的位置，12px 才不显得贴在框上。附件条的横向缩进交给外框提供——它原来自己带 12px，于是比 textarea 多缩进一层、两个左边缘对不齐，现在只留底边距把附件和正文隔开。
 >
 > `minRows` 默认 `2`、`maxRows` 默认 `4`：即初始两行，最多长到四行，再超就在框内滚动。要更宽松的书写区就自己传 `maxRows`（`minRows` 与它拉开几行才有余地）。
 >
@@ -2982,6 +3128,53 @@ const items = [
 
 ---
 
+## Utility 工具
+
+### AttachmentUtility 附件工具
+
+附件相关的纯函数集合，命名空间导出（`AttachmentUtility.xxx`）。**无状态、不碰 React** —— 组件里的附件逻辑都建立在这几个函数上，别的项目要单独用也可以直接引。
+
+```tsx
+import { AttachmentUtility } from "knight-ui";
+
+// File[] → Attachment[]，图片顺带生成 objectURL 缩略图
+const items = AttachmentUtility.fromFiles(files);
+
+// 按条件过滤，通过的与没通过的分开交回
+const { accepted, rejected } = AttachmentUtility.filter(files, {
+  accept: "image/*,.pdf", maxSize: 5 * 1024 * 1024, maxCount: 3, count: 2,
+});
+
+// 归还缩略图（只 revoke blob: 开头的 objectURL，dataURL 不动）
+items.forEach(AttachmentUtility.release);
+
+AttachmentUtility.kindOf(file);      // "image" | "file" | "audio" | "video"
+AttachmentUtility.readSize(1536);    // "1.5 KB"
+```
+
+| 成员 | 签名 | 说明 |
+|---|---|---|
+| `fromFiles` | `(files: Array<File>) => Array<Item>` | 转成附件对象，图片顺带建 `thumbnail` |
+| `filter` | `(files, options?) => { accepted, rejected }` | 按 `accept` / `maxSize` / `maxCount`(+`count`) 分类 |
+| `release` | `(attachment) => void` | 归还缩略图占的 objectURL |
+| `kindOf` | `(file: File) => Kind` | 判类别，**MIME 优先、退回后缀** |
+| `readSize` | `(size: number) => string` | 字节数转可读文本（`B` / `KB` / `MB`） |
+
+| 类型 | 说明 |
+|---|---|
+| `Kind` | `"image" \| "file" \| "audio" \| "video"` |
+| `Item` | 附件的内部形态：`id` / `name` / `size` / `type` / `kind` / `thumbnail?` / `file` |
+| `FilterOptions` | `accept?` / `multiple?` / `maxCount?` / `maxSize?` / `count?` |
+| `RejectReason` | 未通过的原因：`file` / `code`（`"type"` 类型不符、`"size"` 超体积、`"count"` 超数量或多选受限）/ `message` |
+
+> **`release` 只 revoke `blob:`**：`fromFiles` 生成的缩略图是 objectURL，不归还就是一次内存泄漏；而回填的远程附件（`url`）或调用方自己塞的 dataURL 都没有可归还的东西，所以按前缀甄别，不误伤。
+>
+> **`filter` 的 `count` 是"已有多少"**：`maxCount` 是总数上限而不是"这次能选几个"，所以剩余名额 = `maxCount - count`。不传 `count` 就当作从零开始。
+>
+> **`kindOf` 先看 MIME 再看后缀**：浏览器给的 `file.type` 有时是空的（少见扩展名尤其容易），此时退回按扩展名判；两样都认不出就归 `"file"`。
+
+---
+
 ## Other 其他
 
 ### ConfigProvider 全局配置

package/component/ai/AIChatInput.d.ts

@@ -1,27 +1,46 @@
 import React from "react";
 import { AbstractUI, type UIProps, type UIState } from "../../base";
-export interface Attachment {
-    id?: string;
-    name: string;
-    size?: number;
-    type?: string;
-    url?: string;
-}
+import { AttachmentUtility } from "../../utility";
 /**
  * AI 聊天输入框。
  */
 export declare class AIChatInput extends AbstractUI<AIChatInputProps, AIChatInputState> {
+    /** 行高(px)：textarea 的 min/max 高度、以及行数换算都以此为单位 */
+    private static readonly LINE_HEIGHT;
+    /** 最小行数默认值：一处定义、三处消费(measure / 发送后复位 / 渲染)，免得默认值改一处漏两处 */
+    private static readonly DEFAULT_MIN_ROWS;
+    /** 最大行数默认值 */
+    private static readonly DEFAULT_MAX_ROWS;
     private textareaRef;
     constructor(props: AIChatInputProps);
     componentDidUpdate(prevProps: Readonly<AIChatInputProps>, prevState: Readonly<AIChatInputState>): void;
     componentDidMount(): void;
     componentWillUnmount(): void;
     private onTextareaWheel;
+    /** 归还一批附件的缩略图 */
+    private releaseAll;
     private autoResize;
     private handleSend;
     private handleKeyDown;
     private handleChange;
     private handleRemoveAttachment;
+    /** 新文件统一入口 — 选文件 / 粘贴 / 拖拽都走这里。
+     *  校验按 props 的 accept/maxSize/maxCount 做, 未通过的交回 onValidateFail;
+     *  未受控时自己转成 Attachment 存下, 受控时只把原始 File[] 抛给 onAddAttachments */
+    private acceptFiles;
+    /** 粘贴带文件时以文件为准 —— 截图粘贴是主场景, 不该把剪贴板里的文字/地址一并塞进正文
+     *  以下挂到 DOM 上的处理器一律写成箭头属性: React 是裸调用, 原型方法进去 this 就没了 */
+    private handlePaste;
+    /** 拖拽深度 — dragenter / dragleave 在子元素之间来回成对触发, 靠计数才分得清"真离开" */
+    private dragDepth;
+    private handleDragEnter;
+    private handleDragOver;
+    private handleDragLeave;
+    private handleDrop;
+    /** 悬停高亮 — 判得出不是文件就不亮; 判不出来(浏览器给的信息不规整)宁可亮, 别让人以为拖不进来 */
+    private markDragging;
+    /** 拖的是不是文件 — 认不出来按文件算 */
+    private static looksLikeFiles;
     protected OnRenderContent(): React.ReactElement;
 }
 export interface AIChatInputProps extends UIProps {
@@ -35,16 +54,54 @@ export interface AIChatInputProps extends UIProps {
     backgroundColor?: string;
     disabled?: boolean;
     loading?: boolean;
+    /** 附件列表。**受控**: 传了就以它为准, 增删只回调(缩略图的 release、发送后清空都由调用方负责);
+     *  不传则库自己管 —— 拖拽/粘贴/选择器直接可用, 发送后自动清空、卸载时自动归还缩略图 */
     attachments?: Attachment[];
     /** 最小(初始)行数 @default 2 */
     minRows?: number;
     /** 最大行数,超出后滚动 @default 4 */
     maxRows?: number;
-    /** 底部工具条内容(输入框内、textarea 下方、发送键左侧) —— 库不关心放什么,由调用方组装;不传则保留 20px 空白垫高 */
-    bottomBar?: React.ReactNode;
+    /** 底部工具条左端内容(输入框内、textarea 下方) —— 库不关心放什么,由调用方组装;不传则保留 20px 空白垫高 */
+    toolbar?: React.ReactNode;
+    /** 底部工具条右端内容 —— 与 toolbar 同一行, 自动靠右 */
+    toolbarEnd?: React.ReactNode;
+    /** 可收附件类型, 与 <input accept> 同语法(如 "image/*,.pdf"), 不传则不限 */
+    accept?: string;
+    /** 是否允许多选 @default true */
+    multiple?: boolean;
+    /** 附件数量上限, 不传则不限 */
+    maxCount?: number;
+    /** 单个附件字节上限, 不传则不限 */
+    maxSize?: number;
+    /** 附件通过校验 —— 受控时调用方据此把 File 转成 Attachment 回传 attachments */
+    onAddAttachments?: (files: Array<File>) => void;
+    /** 附件被移除 */
+    onRemoveAttachment?: (attachment: Attachment, index: number) => void;
+    /** 附件未通过校验 —— 提示语由调用方决定, 库不自己弹 */
+    onValidateFail?: (reason: AttachmentUtility.RejectReason) => void;
 }
 interface AIChatInputState extends UIState {
     value: string;
     attachments: Attachment[];
+    /** 有文件拖到框上 — 仅用于描边高亮 */
+    dragging: boolean;
+}
+export interface Attachment {
+    /** 稳定标识 — 由 AttachmentUtility.fromFiles 生成, 也允许调用方自带 */
+    id?: string;
+    /** 文件名 */
+    name: string;
+    /** 字节数 */
+    size?: number;
+    /** MIME */
+    type?: string;
+    /** 远程地址(已有附件回填时用) */
+    url?: string;
+    /** 类别 — 决定缩略图形状与发送时对应的 part 形态 */
+    kind?: AttachmentUtility.Kind;
+    /** 图片缩略图(objectURL / dataURL) */
+    thumbnail?: string;
+    /** 原始文件 — 编码责任在上层 */
+    file?: File;
 }
 export {};

package/component/input/AutoComplete.d.ts

@@ -1,6 +1,5 @@
 import React from "react";
 import { AbstractUI, type UIProps, type UIState } from "../../base";
-import type { ValidateStatus } from "../types";
 export interface AutoCompleteOption {
     value: string;
     label?: React.ReactNode;
@@ -19,7 +18,13 @@ export declare class AutoComplete extends AbstractUI<AutoCompleteProps, AutoComp
     focus(): void;
     protected OnRenderContent(): React.ReactElement;
     private getFilteredData;
-    private onInputChange;
+    private handleInputChange;
+    /** 聚焦 — 先把当前文本交出去(在展开下拉之前), 再展开。
+     *  异步拉候选的入口: 聚焦时去服务端要一份候选, 期间把 loading 置 true */
+    private handleFocus;
+    /** 失焦 — 先把当前文本交出去(在收起下拉之前), 再收下拉。
+     *  有了它, "手输一个列表里没有的值"才有落点: 单靠 onChange 只说明值变过, 说不清"输完了" */
+    private handleBlur;
     private openDropdown;
     private closeDropdown;
     private onDocClick;
@@ -35,9 +40,15 @@ export interface AutoCompleteProps extends UIProps {
     defaultValue?: string;
     /** 搜索回调(用于异步请求) */
     onSearch?: (inputValue: string) => void;
+    /** 聚焦 — 交出聚焦那一刻的文本。异步拉候选的入口: 聚焦时去服务端要一份候选,
+     *  期间把 loading 置 true(否则 data 还空着会闪一下"无匹配结果") */
+    onFocus?: (value: string) => void;
+    /** 失焦 — 交出离开时的文本, 给调用方一个"输完了"的边界(trim / 规范化 / 校验是否已知值) */
+    onBlur?: (value: string) => void;
     /** 选中回调 */
     onSelect?: (option: AutoCompleteOption) => void;
-    /** 值变化回调 */
+    /** 值变化回调 — **手输与选中都触发**: 手输时 option 为空, 选中时带上。
+     *  与 onSearch 在敲键时同一时刻触发, 但语义不同 —— 这个是"值变了", 那个是"该搜了" */
     onChange?: (value: string, option?: AutoCompleteOption) => void;
     /** 是否本地过滤 */
     filter?: boolean;
@@ -49,7 +60,6 @@ export interface AutoCompleteProps extends UIProps {
     loading?: boolean;
     size?: "small" | "default" | "large";
     placeholder?: string;
-    validateStatus?: ValidateStatus;
 }
 interface AutoCompleteState extends UIState {
     value: string;

package/component/input/TreeSelect.d.ts

@@ -26,6 +26,9 @@ export declare class TreeSelect extends AbstractUI<TreeSelectProps, TreeSelectSt
     componentWillUnmount(): void;
     private onClickOutside;
     protected OnRenderContent(): React.ReactElement;
+    /** 选项行的类: 悬停 / 选中 / 禁用三态都交给 .ku-menu-option 那几档类。
+     *  底色**不能写内联** —— 内联优先级高于类, 写了悬停就没反应(与 Select / Cascader 同一条规矩) */
+    private optionClass;
     private flatItemStyle;
     private renderCheckbox;
     private renderTreeNode;

package/component/plus/AttachmentPicker.d.ts

@@ -0,0 +1,30 @@
+import React from "react";
+import { AbstractUI, type UIProps, type UIState } from "../../base";
+import { AttachmentUtility } from "../../utility";
+/**
+ * 附件选择器 — 点击触发体弹系统选文件框, 选完按 accept / maxSize / maxCount 校验后回调。
+ * 只管"弹框 + 校验"; 触发体长什么样由 children 决定, 好让各处沿用自己那套按钮样式。
+ */
+export declare class AttachmentPicker extends AbstractUI<AttachmentPickerProps, UIState> {
+    private inputRef;
+    constructor(props: AttachmentPickerProps);
+    private handleClick;
+    private handleChange;
+    protected OnRenderContent(): React.ReactElement;
+}
+export interface AttachmentPickerProps extends UIProps {
+    /** 可收类型, 与 <input accept> 同语法(如 "image/*,.pdf") */
+    accept?: string;
+    /** 是否多选 @default true */
+    multiple?: boolean;
+    /** 数量上限, 与 count 一起算剩余名额 */
+    maxCount?: number;
+    /** 单个文件字节上限 */
+    maxSize?: number;
+    /** 已有数量 — 由调用方喂当前附件数 */
+    count?: number;
+    /** 通过校验的文件 */
+    onPick?: (files: Array<File>) => void;
+    /** 未通过校验 — 提示语由调用方决定 */
+    onValidateFail?: (reason: AttachmentUtility.RejectReason) => void;
+}

package/component/plus/index.d.ts

@@ -1,3 +1,5 @@
+export { AttachmentPicker } from "./AttachmentPicker";
+export type { AttachmentPickerProps } from "./AttachmentPicker";
 export { AudioPlayer } from "./AudioPlayer";
 export type { AudioPlayerProps } from "./AudioPlayer";
 export { Chat } from "./Chat";

package/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./base";
 export * from "./component";
+export * from "./utility";