@cloudtower/eagle 490.0.6 → 490.0.7

package/docs/core/SearchInput/guide.md

@@ -0,0 +1,125 @@
+# SearchInput
+
+## 简介
+
+搜索输入框组件，基于 Input 封装，提供防抖搜索、结果导航（上一个/下一个/计数器）和最近搜索历史功能。支持受控和非受控两种模式，宽度默认 276px。
+
+## 何时使用
+
+- 表格内搜索高亮匹配结果，需要上下翻页定位
+- 页面全局搜索，需要防抖避免频繁请求
+- 需要保留最近搜索记录的搜索场景
+
+不要使用：
+
+- 仅需要简单输入框 --> 请用 `Input`
+- 下拉选择过滤 --> 请用 `Select` 的搜索模式
+- 级联选择中的搜索 --> `Cascader` 已内置 SearchInput
+
+## 基础用法
+
+最简单的搜索框，仅响应输入变化并防抖处理：
+
+```tsx
+import React, { useState } from "react";
+import { SearchInput } from "@cloudtower/eagle";
+
+const App = () => {
+  const [keyword, setKeyword] = useState("");
+
+  return (
+    <SearchInput
+      debounceWait={300}
+      onChange={(value) => setKeyword(value)}
+    />
+  );
+};
+```
+
+## 常见模式
+
+### 模式一：带结果导航
+
+适用于搜索后需要在匹配结果之间上下翻页的场景（如表格内搜索高亮）。同时提供 `onSearchNext` 和 `onSearchPrev` 后，输入框后缀会显示 "current/total" 计数器和上下翻页按钮。按 Enter 键等同于点击"下一个"。
+
+```tsx
+import React, { useState } from "react";
+import { SearchInput } from "@cloudtower/eagle";
+
+const VmTableSearch = () => {
+  const [matchedVms, setMatchedVms] = useState<string[]>([]);
+
+  return (
+    <SearchInput
+      total={matchedVms.length}
+      onChange={(value) => {
+        // 根据关键词过滤匹配的虚拟机列表
+        const matched = allVms.filter((vm) => vm.name.includes(value));
+        setMatchedVms(matched);
+      }}
+      onSearchNext={(value, current) => {
+        // 滚动到第 current 个匹配结果
+        scrollToVm(matchedVms[current - 1]);
+      }}
+      onSearchPrev={(value, current) => {
+        scrollToVm(matchedVms[current - 1]);
+      }}
+    />
+  );
+};
+```
+
+### 模式二：受控模式（外部控制当前索引）
+
+适用于需要从组件外部控制当前高亮索引的场景，例如同步多个搜索结果视图。通过 `current` prop 传入索引值，组件不再内部管理位置状态。
+
+```tsx
+import React, { useState } from "react";
+import { SearchInput, Button } from "@cloudtower/eagle";
+
+const App = () => {
+  const [value, setValue] = useState("");
+  const [current, setCurrent] = useState(1);
+  const total = 10;
+
+  return (
+    <div>
+      <SearchInput
+        value={value}
+        current={current}
+        total={total}
+        debounceWait={0}
+        onChange={(v) => setValue(v)}
+        onSearchNext={(v, nextCurrent) => setCurrent(nextCurrent)}
+        onSearchPrev={(v, prevCurrent) => setCurrent(prevCurrent)}
+      />
+      <Button onClick={() => setCurrent(1)}>回到第一个</Button>
+    </div>
+  );
+};
+```
+
+注意：使用受控模式（传入 `value`）时，需把 `debounceWait` 设置为 0，否则输入时会有卡顿。
+
+### 模式三：最近搜索历史
+
+启用 `enableRecentSearch` 后，搜索记录会通过 localStorage 持久化存储。聚焦空输入框时自动显示最近搜索记录的下拉菜单，点击记录项可直接填入搜索。不同业务场景应使用不同的 `recentSearchLocalStorageKey` 以隔离数据。
+
+```tsx
+import React from "react";
+import { SearchInput } from "@cloudtower/eagle";
+
+const App = () => (
+  <SearchInput
+    enableRecentSearch
+    recentSearchLocalStorageKey="host-search"
+    maxRecentCount={5}
+    onChange={(value) => console.log("搜索:", value)}
+  />
+);
+```
+
+## 相关组件
+
+- `Input`：基础输入框，SearchInput 基于它封装
+- `Cascader`：级联选择器，内置了 SearchInput 作为搜索区域

package/docs/llms.txt

@@ -44,7 +44,7 @@ npm 包名：@cloudtower/eagle
 - TimePicker: 时间选择器
 - Calendar: 日历面板
 - TimeZoneSelect: 时区选择器，内置全球时区数据
-- SearchInput: 搜索输入框，支持高亮匹配数和上下翻页
+- [SearchInput](core/SearchInput/guide.md): 搜索输入框，支持防抖搜索、结果导航（上下翻页/计数器）和最近搜索历史
 - [TableForm](core/TableForm/guide.md): 表格表单，行内编辑的表格，支持批量填充、多种列类型、增删行、拖拽排序和三种校验模式
 - Fields: 表单字段集合，包含 Boolean/DateTime/Enum/Float/Int/String/TextArea 等预设字段
 - CronPlan: 定时计划配置组件，支持按天/周/月设置 cron 表达式

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudtower/eagle",
-  "version": "490.0.6",
+  "version": "490.0.7",
   "main": "dist/cjs/index.js",
   "module": "./dist/esm/index.js",
   "types": "dist/src/index.d.ts",
@@ -27,8 +27,8 @@
     "sync:color": "node tools/fetch-figma-color.js"
   },
   "dependencies": {
-    "@cloudtower/icons-react": "^490.0.6",
-    "@cloudtower/parrot": "^490.0.6",
+    "@cloudtower/icons-react": "^490.0.7",
+    "@cloudtower/parrot": "^490.0.7",
     "@cloudtower/rc-notification": "^4.6.1",
     "@linaria/core": "^4.2.2",
     "@linaria/react": "^4.3.0",
@@ -116,5 +116,5 @@
     "vite": "^4.5.1",
     "vitest": "^3.1.1"
   },
-  "gitHead": "0b7091ede353aa33a96aa92a464f1d1e58997b29"
+  "gitHead": "1a6679790080e9e7795cddbdc2eea5411e0d5456"
 }