@robot-admin/naive-ui-components 0.22.1 → 0.23.0

package/dist/verification.d.ts

@@ -1,4 +1,4 @@
-import { X as ComponentLocale, Y as ComponentFeedback } from "./useFormConfig.js";
+import { n as ComponentLocale, t as ComponentFeedback } from "./contracts.js";
 import * as vue from "vue";
 
 //#region src/components/C_Captcha/types.d.ts
@@ -76,20 +76,20 @@ declare const __VLS_export: vue.DefineComponent<CaptchaProps, {
   reset: () => void;
   show: () => void;
 }, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {} & {
+  reset: () => any;
   change: (valid: boolean) => any;
   success: (data: CaptchaSuccessPayload) => any;
-  reset: () => any;
-  "load-error": (error: unknown) => any;
   fail: (error: string) => any;
   "verify-error": (error: unknown) => any;
+  "load-error": (error: unknown) => any;
   "visible-change": (visible: boolean) => any;
 }, string, vue.PublicProps, Readonly<CaptchaProps> & Readonly<{
+  onReset?: (() => any) | undefined;
   onChange?: ((valid: boolean) => any) | undefined;
   onSuccess?: ((data: CaptchaSuccessPayload) => any) | undefined;
-  onReset?: (() => any) | undefined;
-  "onLoad-error"?: ((error: unknown) => any) | undefined;
   onFail?: ((error: string) => any) | undefined;
   "onVerify-error"?: ((error: unknown) => any) | undefined;
+  "onLoad-error"?: ((error: unknown) => any) | undefined;
   "onVisible-change"?: ((visible: boolean) => any) | undefined;
 }>, {
   disabled: boolean;

package/dist/workflows.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./useDataResource.cjs`),t=require(`./useFormArray.cjs`);exports.useDataResource=e.t,exports.useFormArray=t.t,exports.useValidationScope=t.n;

package/dist/workflows.d.cts

@@ -0,0 +1,2 @@
+import { a as DataResourceOptions, i as useValidationScope, n as useFormArray, o as DataResourceStatus, r as ValidationParticipant, s as useDataResource, t as FormArrayEntry } from "./useFormArray.cjs";
+export { type DataResourceOptions, type DataResourceStatus, type FormArrayEntry, type ValidationParticipant, useDataResource, useFormArray, useValidationScope };

package/dist/workflows.d.ts

@@ -0,0 +1,2 @@
+import { a as DataResourceOptions, i as useValidationScope, n as useFormArray, o as DataResourceStatus, r as ValidationParticipant, s as useDataResource, t as FormArrayEntry } from "./useFormArray.js";
+export { type DataResourceOptions, type DataResourceStatus, type FormArrayEntry, type ValidationParticipant, useDataResource, useFormArray, useValidationScope };

package/dist/workflows.js

@@ -0,0 +1 @@
+import{t as e}from"./useDataResource.js";import{n as t,t as n}from"./useFormArray.js";export{e as useDataResource,n as useFormArray,t as useValidationScope};

package/docs/components.en.md

@@ -2,7 +2,7 @@
 
 # Component catalog
 
-> 💡 All components provide **interactive live demos**. Visit the [Component Docs](https://www.tzagileteam.com/robot/components/preface) to try them out in real-time (rendered via iframe from Robot Admin production).
+Use the online docs and repository guides for component contracts, and Robot Admin demos for combined workflows.
 
 ## Basic Components
 
@@ -120,3 +120,15 @@ bun add vue naive-ui
 ```
 
 Install optional peers per feature: `vue-router` for `C_Breadcrumb`/`C_TagsView`, and `sortablejs` for C_Table row/column dragging. Subpath imports do not require unrelated optional peers. The formula editor uses a bounded built-in parser and does not execute dynamic JavaScript.
+
+## Business workspace components
+
+| Component        | Purpose                                                   |
+| ---------------- | --------------------------------------------------------- |
+| `C_Density`      | Regional density defaults without wrapper DOM             |
+| `C_SectionNav`   | Section navigation, error badges and keyboard focus       |
+| `C_ErrorSummary` | Navigable validation issues with bounded DOM              |
+| `C_DataPicker`   | Paged entity selection, cross-page draft and batch labels |
+| `C_BatchResult`  | Per-item results, filtering, paging and explicit retry    |
+
+The [data/workflow guide](./guides/data-workflows.md) covers shared dictionaries, numeric codecs, dependent resources, validation scopes and repeatable forms.

package/docs/components.md

@@ -2,7 +2,7 @@
 
 # 组件目录
 
-> 💡 所有组件均提供 **在线交互演示**，访问 [组件文档](https://www.tzagileteam.com/robot/components/preface) 可直接在页面中体验真实效果（通过 iframe 嵌入 Robot Admin 生产环境）。
+组件用法见在线文档与本仓库指南，组合场景可在 Robot Admin 演示中体验。
 
 ## 基础组件
 
@@ -120,3 +120,15 @@ bun add vue naive-ui
 ```
 
 按功能安装可选 peer：使用 `C_Breadcrumb`/`C_TagsView` 时安装 `vue-router`；启用 C_Table 行/列拖拽时安装 `sortablejs`。子路径导入不会要求无关的可选 peer。公式编辑器使用组件库内置的受限表达式解析器，不执行动态 JavaScript。
+
+## 业务工作台组件
+
+| 组件             | 说明                             |
+| ---------------- | -------------------------------- |
+| `C_Density`      | 子树密度默认值，无额外 DOM       |
+| `C_SectionNav`   | 分区导航、错误计数与键盘焦点     |
+| `C_ErrorSummary` | 可导航错误摘要，分页限制 DOM     |
+| `C_DataPicker`   | 分页实体选择、跨页草稿与批量回显 |
+| `C_BatchResult`  | 分项结果、筛选分页与显式重试     |
+
+[数据与工作流指南](./guides/data-workflows.md)：共享字典、数值转换、主从资源、跨区域校验及重复表单。

package/docs/guides/batch-results.md

@@ -0,0 +1,47 @@
+# 批量操作结果
+
+`C_BatchResult` 呈现成功、失败、冲突、跳过及失败原因，支持筛选、分页与显式重试。组件不提交请求，也不自行重试。
+
+```vue
+<script setup lang="ts">
+  import { C_BatchResult } from '@robot-admin/naive-ui-components/C_BatchResult'
+  import type { BatchOperationResult } from '@robot-admin/naive-ui-components/data'
+  import '@robot-admin/naive-ui-components/C_BatchResult/style.css'
+
+  const results: BatchOperationResult[] = [
+    { key: 'ORDER-1', status: 'success' },
+    {
+      key: 'ORDER-2',
+      status: 'conflict',
+      message: '版本已改变，请核对后重试',
+      retryable: true,
+    },
+    {
+      key: 'ORDER-3',
+      status: 'failure',
+      message: '当前状态不允许操作',
+      retryable: false,
+    },
+  ]
+  function retry(keys: (string | number)[]) {
+    // 使用应用已有的命令适配器；后端仍须再次校验权限、状态、版本和幂等令牌。
+    orderActions.retry(keys)
+  }
+</script>
+
+<template>
+  <C_BatchResult
+    :results="results"
+    title="下达结果"
+    @retry="retry"
+  />
+</template>
+```
+
+同一 `key` 多次出现时，以最后一条结果为准，摘要、表格和重试资格保持一致。`retry` 只发送最后状态为 `failure` / `conflict` 且 `retryable: true` 的去重key；后来已成功或跳过的行不会再次发送。失败不等于允许重试。
+
+默认每页20条，可通过 `pageSize` 调整；表格只接收当前页行并使用虚拟滚动，万条结果不会同时创建万条DOM。切换状态筛选时回到第一页，结果数量缩小会修正页码。
+
+原因按文本显示。不要把HTML、Vue节点或后端原始异常堆栈塞进 `message`；业务应提供可以行动的原因，并决定是否保留失败行的编辑草稿、是否刷新成功行以及如何处理冲突。
+
+`locale` 支持应用默认和组件局部中英文配置，统计、筛选、列头与重试文案会随配置更新；显式 `title` 优先。

package/docs/guides/data-picker.md

@@ -0,0 +1,65 @@
+# 远程实体选择器
+
+`C_DataPicker` 用于客户、订单、人员、物料等需要分页查询和多列辨认的选择场景。它复用 `C_Table`、Naive Modal 和资源生命周期，不绑定后端地址，也不维护第二份请求缓存。
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue'
+  import {
+    C_DataPicker,
+    type DataPickerSource,
+  } from '@robot-admin/naive-ui-components/C_DataPicker'
+  import '@robot-admin/naive-ui-components/C_DataPicker/style.css'
+
+  interface Customer {
+    id: string
+    code: string
+    name: string
+  }
+  const selected = ref<string[]>([])
+
+  // customerClient 是应用已有的请求/缓存适配器；signal 透传给真实请求。
+  const source: DataPickerSource<Customer> = {
+    rowKey: 'id',
+    value: row => row.code,
+    label: row => row.name,
+    request: query => customerClient.page(query), // { rows: Customer[], total: number }
+    resolve: (codes, signal) => customerClient.byCodes(codes, { signal }),
+  }
+  const columns = [
+    { key: 'code', title: '客户编码', width: 140 },
+    { key: 'name', title: '客户名称', minWidth: 180 },
+  ]
+</script>
+
+<template>
+  <C_DataPicker
+    v-model="selected"
+    :source="source"
+    :columns="columns"
+    multiple
+    clearable
+    title="选择客户"
+  />
+</template>
+```
+
+## 值与会话
+
+- `source.rowKey` 是表格行身份；`source.value(row)` 是业务提交值，两者可以不同，均须稳定且唯一。业务值支持字符串和数值，`0` 是有效值。
+- 选择在本地草稿中进行，跨分页保留；只有“确认选择”或显式清空才发出 `update:modelValue`。取消、关闭弹窗、卸载不会提交草稿。
+- `select(rows)` 返回已解析的选中行。提供 `source.resolve(values, signal)` 可一次批量回显全部初值；未提供时，尚未加载的初值显示原编码且保留，不猜测标签，不逐条请求。需要完整 `rows` 事件的场景应提供 `resolve`。
+- 源、受控值、单多选模式或可用状态改变时关闭旧会话；旧请求即使忽略 signal，也不能回写到新会话。
+- `readonly` 保留名称展示，但不打开选择、清空或确认；`disabled` 同样禁止变更。名称加载失败保留编码并提供重试。
+
+## 请求与布局
+
+`request` 接收 `{ page, pageSize, search, signal }`，返回 `{ rows, total }`。应用负责接口字段转换、鉴权、业务过滤、去重及缓存。组件不猜测 `data.records` 等响应信封。
+
+默认 `pageSize=20`；密度按显式 `density`、区域 `C_Density` / 表单默认密度、`compact` 依次解析，支持 `default`、`comfortable`。列表使用虚拟表格，已选标签最多同时呈现30个，其余显示数量。可通过实例 `open()` / `close()` 控制选择会话。
+
+`locale` 可覆盖应用中英文配置，标题和 placeholder 的显式配置优先；运行时切换语言不会清空选择草稿。
+
+同一页的业务值必须唯一且为字符串或有限数值；响应的 `rows`、`total` 无效时显示失败和重试入口。`total` 必须为非负安全整数；行身份不可缺失或重复，返回行数不得超过所请求的 `pageSize` 或 `total`，不靠静默截断伪装成合法分页。跨页再次出现同一实体时保留一项选择，移除已选标签会取消该实体。
+
+在 Form/Search 中通过现有自定义渲染器使用这一组件。将 `source` 在业务集成层定义一次并复用即可，不需要让所有表单或搜索入口静态依赖实体选择器。

package/docs/guides/data-workflows.md

@@ -0,0 +1,123 @@
+# 业务数据与多区域工作台
+
+搜索、表单和表格共享值语义，应用保留接口、权限、缓存和业务事务。新增能力均按需接入；未配置时沿用既有行为。
+
+## 一个字典数据源
+
+```ts
+import Components from '@robot-admin/naive-ui-components'
+import type { DictionarySource } from '@robot-admin/naive-ui-components/config'
+
+const planState: DictionarySource = {
+  getOptions: () => [
+    { value: 'released', label: '已下达' },
+    { value: 'running', label: '执行中' },
+  ],
+}
+app.use(Components, {
+  dictionaries: {
+    getDictionary: name => (name === 'planState' ? planState : undefined),
+  },
+})
+```
+
+字段只写 `dictionary: 'planState'`。C_Form 的 `children`、`asyncOptions`，C_FormSearch 的显式 `list/attrs.options`，C_Table 的 `render/formatter/editProps.options` 仍按各自既有优先级生效，未使用的字典不会被加载。
+
+按需安装可通过 `/config` 导出的 `DICTIONARY_PROVIDER_KEY` 注入同一个 Provider。不要因为使用表单而导入 MachTable 根包。
+
+`DictionarySource` 支持：
+
+- `getOptions()`：同步快照，编码保留 string/number/boolean 类型。
+- `load({ signal })`：可选的异步准备；视图会忽略已失效的请求。
+- `subscribe(listener)`：可选的更新通知，返回取消订阅函数。
+
+应用已有 store/resolver 时直接桥接，不叠加第二套 TTL 缓存。源负责组织、租户、语言和业务参数隔离：请求开始时捕获作用域，参数切换后不得把旧响应写进新作用域。可由 `getDictionary` 返回该作用域的稳定源，或发布当前快照变更通知。组件仅管理可销毁的选项视图及派生索引。
+
+选项必须是有效且唯一的原始编码、字符串标签及可选 boolean disabled。空数组是已提供的空选项，不回退到旧数据。未知编码原样回显；停用历史编码可以保留在源中供展示。重复标签在反向解析时报告歧义，不自动选择第一项。高频展示使用 `createDictionaryLabelResolver(options)`，快照变化时重建一次索引。
+
+## 数值：存储、显示和校验分别定义
+
+```ts
+import { createNumberCodec } from '@robot-admin/naive-ui-components/data'
+import { numeric } from '@robot-admin/form-validate'
+
+const weight = createNumberCodec({
+  storage: 'decimal-string',
+  fractionDigits: 3,
+  suffix: ' t',
+})
+const weightRules = [numeric({ totalDigits: 11, fractionDigits: 3, min: 0 })]
+
+weight.parse('12345678.005') // '12345678.005'
+weight.format('12.5004') // '12.500 t'，只舍入显示，不改原值
+```
+
+精确小数用文本控件保留编辑草稿，C_Form 直接消费 `weightRules`，提交前再调用 `parse`。不要在每次输入时解析半成品文本，也不要把 `precision` 当作提交校验。清空得到 null，0 仍为有效数值。默认 number 存储会拒绝不安全整数和不能十进制往返的转换；已经被上游 number 损坏的精度不能恢复，精确接口应传原始字符串。
+
+`fractionDigits: 0` 有效；HALF_UP 处理负数中点。parse 接收普通十进制原始值，format 可加千分位、前后缀；带单位/货币符号的显示文本不是接口值。合计、精确排序、汇率和税费按业务数值策略处理，不拿格式化文本计算。
+
+MachTable 使用侧可在全局列类型中一次接入 `valueParser` 和 `valueFormatter`；精确字符串字段提供相应业务 comparator。其 `createDictionaryColumn` 可显式设置各输出 target 的编码/标签/码名策略，`summarizeRows` 可注入已有精确运算策略。Naive 库不会依赖或代替网格内核。
+
+## 主从资源：本地空值与迟到响应
+
+```ts
+import { useDataResource } from '@robot-admin/naive-ui-components/workflows'
+
+const details = useDataResource({
+  key: () => activeOrderId.value,
+  load: ({ key, signal }) => orderApi.details(key, { signal }),
+})
+```
+
+更换 key 会取消旧请求、清除旧主记录数据；即使传输忽略 signal，旧结果也不能覆盖新记录。同 key 刷新失败保留原展示，`status: 'error'` 与 `stale` 明确表达旧快照，可通过 `reload()` 重试。reload 返回成功与否的 boolean，可直接交给 Search 的 `config.onSearch`。
+
+可选 `source` 表示本地受控数据：undefined 才是未提供，`[]` 和 null 都是明确的本地源。本地源生效时不请求远端。组件卸载会清理 watcher/请求，KeepAlive 停用期间不开始新请求；恢复后按最新 key 继续。普通 effectScope 外使用时调用 `dispose()`。每个 panel 独立实例，互不共享请求状态；不缓存所有访问过的订单。
+
+## 多区域校验和导航
+
+```ts
+import { useValidationScope } from '@robot-admin/naive-ui-components/workflows'
+
+const validation = useValidationScope()
+const unregister = validation.register({
+  id: 'header',
+  dirty: () => formRef.value?.isDirty ?? false,
+  validate: () => formRef.value!.validate(),
+  reveal: issue =>
+    formRef.value?.revealField(issue.target?.field ?? '') ?? false,
+})
+```
+
+原生 `validate(): Promise<void>` 无需转换器，拒绝的字段错误会被标准化。表格校验可返回 `{ key, source, message, target: { section, tab, rowKey, field } }[]`；行地址使用稳定业务 key。注册标识必须唯一；动态区域移除时调用 unregister，旧验证结果不会回填。`dirty` 仅聚合已注册区域，不深遍历整张业务单据。
+
+`C_ErrorSummary` 接收 `validation.issues`，`@navigate="validation.reveal"` 定位问题，默认每页仅挂载8项。`C_SectionNav` 的 items 包含 key/label/errorCount/disabled，通过 `@select` 接入现有分区或折叠面板；它不查找全局 DOM、不监听全局滚动。
+
+Form 的 `revealField` 保留 Tab/Step 原有导航和校验约束，禁用或只读目标不强行聚焦，受阻返回 false。自定义控件通过 `focusTarget` 准备并返回真实元素；迟到的异步定位不会抢走当前焦点。
+
+校验协调不等于数据库事务。保存使用业务接口的版本、幂等和分项结果；结果未确认时保留原操作及请求快照，避免自动重复提交。
+
+## 密度和重复行
+
+```vue
+<C_Density density="compact">
+  <C_FormSearch ... />
+  <C_Form ... />
+  <C_Table ... />
+  <C_Density density="comfortable">
+    <!-- 工位操作区使用较大控件 -->
+    <C_Form ... />
+  </C_Density>
+</C_Density>
+```
+
+C_Density 无额外 DOM，只提供子树默认值，不修改应用或兄弟区域。局部 config、显式 size 继续优先。MachTable 的密度由其公开 size/config 独立配置。
+
+少量异构重复行使用 `useFormArray(initial, { maxRows })`：items 中每行有稳定 key 与独立 value，增删移动保留身份，`getValues()` 返回隔离副本。reset 使用初始快照；动态删除时同步移除该行校验参与者。大量同构明细使用虚拟表格，不挂载整页常驻输入框。
+
+## 批改、结果和输出边界
+
+`createBatchPatch` 把 keep/clear/set 转为明确的标量 payload：keep 不发送，clear 发送 null，set 保留空串、0、false。非标量子记录仍由领域协议定义，不自动猜测嵌套更新。
+
+`C_BatchResult` 只呈现结果和发出可重试 key，不调用后端。重复 key 以最新结果为准，后续成功项不会因旧失败再次重试。批改范围、差异预览、服务端授权和乐观锁由应用负责。见 [批量结果](./batch-results.md)、[远程实体选择](./data-picker.md)。
+
+显示、复制、CSV、XLSX 各 target 可以采用不同策略，但必须使用同一已执行查询、字典和精度快照。大数据导出使用后端任务，模板排版/分页打印使用报表产品。不要把当前加载页当筛选全量，也不要在同步 formatter/serializer 内发请求。

package/docs/guides/form-density.en.md

@@ -54,3 +54,42 @@ app.provide(FORM_GLOBAL_CONFIG_KEY, { density: 'compact' })
 ```
 
 Compact search fields default to 208px and fill the available width on narrow screens; explicit field `attrs.style.width` takes precedence. Compact numeric fields hide step buttons by default while preserving keyboard Up / Down, step, precision and limits. Set `attrs: { showButton: true }` when buttons are useful. Naive UI still owns number handling and themes; the text input avoids browser-native number spinners. Field `attrs.inputProps` can override accessible names and numeric semantics.
+
+## Arrange fields by container width
+
+Opt into `config.grid.minItemWidth` to budget the entire field, including its label. Default spans adapt to the actual split pane or dialog width. Explicit spans stay intact while they fit, and expand only when necessary, up to a full row. Existing `cols`, `offset`, `suffix`, and Naive UI wrapping remain in charge.
+
+```ts
+const config = {
+  density: 'compact',
+  layout: 'grid',
+  grid: { cols: 24, minItemWidth: 300, xGap: 16, yGap: 8 },
+} as const
+```
+
+Omitting the option preserves existing spans. `responsive: false` disables automatic expansion. A container narrower than the budget uses a full row without forcing an overflowing CSS minimum width. One local `ResizeObserver` follows activation, deactivation, and disposal; no global resize listener is added.
+
+## Reveal an invalid field
+
+`await formRef.revealField(field)` enters the field's tab or step, or expands its card group, then scrolls to and focuses an available control. It returns `true` only after actual focus succeeds. Missing, hidden, disabled, or readonly fields, unloaded layouts, and navigation blocked by existing validation or business guards return `false`. It never clears errors, changes validation rules, or enables an editing mode.
+
+```ts
+const focused = await formRef.value?.revealField('customer.name')
+```
+
+Lookup stays within this form's item references. Unmounting, KeepAlive deactivation, a layout change, or a newer reveal request cancels older work, so late results cannot steal focus. A custom or virtual control may supply `focusTarget` on its field. Prepare the control and return its actual element; let the form recheck access and apply focus rather than focusing inside the adapter.
+
+```ts
+const fields = [
+  {
+    type: 'custom-customer',
+    prop: 'customerId',
+    focusTarget: async ({ signal }) => {
+      await customerEditor.ensureMounted(signal)
+      return signal.aborted ? null : customerEditor.inputElement
+    },
+  },
+]
+```
+
+The context also provides `field`, the form item's `element` (possibly null), and the current `model`. An adapter that ignores cancellation still cannot apply an obsolete focus result. Return null when no real target exists; callers can keep the error summary visible or explain a navigation restriction.

package/docs/guides/form-density.md

@@ -71,3 +71,42 @@ app.provide(FORM_GLOBAL_CONFIG_KEY, { density: 'compact' })
 ```
 
 紧凑搜索的字段默认宽度为 208px，窄屏自动占满可用宽度；显式字段 `attrs.style.width` 仍可覆盖。紧凑数字字段默认隐藏增减按钮，保留键盘 ↑ / ↓、步长、精度及上下限；需要按钮的字段配置 `attrs: { showButton: true }`。控件继续使用 Naive UI 的数值处理与主题，输入为文本，不叠加浏览器原生数字箭头；`attrs.inputProps` 可覆盖可访问名称和数值语义。
+
+## 按容器安排字段
+
+网格可显式设置 `config.grid.minItemWidth`，预算包含标签和控件整体，不是仅输入框宽度。根据当前分栏或弹窗容器的真实宽度调整默认跨度；已有显式 `span` 在宽度足够时保留，只有容纳不了该预算时才扩展，最多占满整行。`cols`、`offset`、`suffix` 与 Naive UI 换行规则不变。
+
+```ts
+const config = {
+  density: 'compact',
+  layout: 'grid',
+  grid: { cols: 24, minItemWidth: 300, xGap: 16, yGap: 8 },
+} as const
+```
+
+未设置该项时保持原有跨度行为；`responsive: false` 禁用自动扩展。容器比最小预算还窄时使用整行，不通过固定 `min-width` 撑破页面。宽度由局部 `ResizeObserver` 提供，停用、重新激活及销毁时管理自身订阅，无全局 resize 监听。
+
+## 定位校验字段
+
+实例方法 `await formRef.revealField(field)` 会先进入字段所在标签页、步骤或展开对应卡片分组，再滚动并聚焦真实可用控件；仅成功获得焦点才返回 `true`。找不到字段、字段隐藏/禁用/只读、布局尚未加载、切换前业务回调或已有校验阻止导航时返回 `false`。它不清除错误、不修改校验规则，也不会替业务切换编辑模式。
+
+```ts
+const focused = await formRef.value?.revealField('customer.name')
+```
+
+定位只使用当前表单实例的字段引用。卸载、KeepAlive 停用、布局改变或新定位请求会取消旧请求，迟到结果不会抢回焦点。自定义或虚拟控件可在字段上配置 `focusTarget`，异步准备后返回真实元素；由表单重新检查访问约束并执行 focus，适配器不要自行聚焦，也不要返回占位元素。
+
+```ts
+const fields = [
+  {
+    type: 'custom-customer',
+    prop: 'customerId',
+    focusTarget: async ({ signal }) => {
+      await customerEditor.ensureMounted(signal)
+      return signal.aborted ? null : customerEditor.inputElement
+    },
+  },
+]
+```
+
+`focusTarget` 上下文还提供 `field`、字段表单项的 `element`（可能为空）和当前 `model`。即使异步适配器忽略取消，库也会拒绝旧元素；没有可聚焦目标时诚实返回 `false`，由使用侧保留错误摘要或提示导航限制。

package/docs/guides/search-workflows.md

@@ -0,0 +1,164 @@
+# 密集搜索区与查询快照
+
+`C_FormSearch` 保留已有 `formItemList`、`v-model`、`formParams`、历史记录和 `@search` 接口。普通接入仍采用 `inline` 布局；复杂业务可显式开启容器网格。组件只管理搜索条件与执行状态，不绑定分页接口、租户规则或特定表格。
+
+## 容器布局与字段
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue'
+  import {
+    C_FormSearch,
+    serializeSearch,
+    type SearchFormItem,
+    type SearchNumberRangeValue,
+    type FormSearchExpose,
+  } from '@robot-admin/naive-ui-components/C_FormSearch'
+
+  interface Query {
+    organization: string
+    keyword: string
+    amount: SearchNumberRangeValue
+    month: string | null
+    enabled: boolean | null
+    customer: string
+  }
+
+  const query = ref<Query>({
+    organization: '001',
+    keyword: '',
+    amount: null,
+    month: null,
+    enabled: false,
+    customer: '',
+  })
+  const search = ref<FormSearchExpose<Query>>()
+  const fields: SearchFormItem<Query>[] = [
+    { type: 'input', prop: 'organization', label: '组织', fixed: true },
+    { type: 'input', prop: 'keyword', label: '关键词' },
+    {
+      type: 'number-range',
+      prop: 'amount',
+      label: '金额范围',
+      span: 2,
+      query: { keys: ['minimumAmount', 'maximumAmount'] },
+    },
+    { type: 'month', prop: 'month', label: '月份', valueMode: 'formatted' },
+    {
+      type: 'select',
+      prop: 'enabled',
+      label: '状态',
+      list: [
+        { label: '启用', value: true },
+        { label: '停用', value: false },
+      ],
+    },
+    {
+      type: 'custom',
+      prop: 'customer',
+      label: '客户',
+      slot: 'customer',
+      defaultValue: '',
+    },
+  ]
+
+  async function execute(params: Query) {
+    const request = serializeSearch(params, fields)
+    // await api.list(request)，或交给已有的 useMachTableQuery 执行器。
+    // 必须返回真实任务的 Promise；仅启动异步任务然后返回 void 无法等待业务完成。
+    await Promise.resolve(request)
+  }
+</script>
+
+<template>
+  <C_FormSearch
+    ref="search"
+    v-model="query"
+    :form-item-list="fields"
+    :config="{
+      density: 'compact',
+      layout: 'grid',
+      columns: 4,
+      fieldMinWidth: 208,
+      labelPlacement: 'left',
+      labelWidth: 88,
+      foldThreshold: 4,
+      onSearch: execute,
+    }"
+  >
+    <template #customer="{ value, model, disabled, updateValue }">
+      <!-- 接入已有客户 Picker；选择结果通过 updateValue 回写。 -->
+      <button
+        type="button"
+        :disabled="disabled"
+        @click="updateValue(model.customer)"
+      >
+        {{ value || '选择客户' }}
+      </button>
+    </template>
+  </C_FormSearch>
+</template>
+```
+
+- `layout: 'grid'` 按**搜索区容器**宽度分栏，`columns` 是最大列数。窄分栏中即使浏览器很宽也会减少列数；不使用视口宽度判断可用空间。
+- `fieldMinWidth` 为基础轨道预算，字段 `span` / `minWidth` 可申请更多空间；实际跨度不会超过容器当前列数。操作区自然位于最后一列。
+- `labelPlacement: 'left' | 'top'` 与 `labelWidth` 对应 Naive UI 表单标签。省略字段 `label` 保持旧的无标签外观。
+- `density` 与表单共用，字段显式 `attrs.size` 和组件 `size` 保持优先。
+- 折叠只影响显示，条件和校验仍有效。隐藏/折叠且有值的字段会显示生效数量；`0`、`false` 也是有效条件。
+
+## 控件与原始模型
+
+支持 `input`、`select`、`number`、`number-range`、`date`、`month`、`date-range`、`custom`、`spacer`。
+
+数字输入继续使用 Naive UI；`attrs` 可配置 `min`、`max`、`precision` 等。紧凑模式的单数字默认隐藏步进按钮，显式 `attrs.showButton` 可覆盖。范围模型为 `[number | null, number | null] | null`，允许先填写单边，两边清空时回到 `null`。范围先后、跨度上限等业务规则通过字段 `rules` 声明，组件不预设业务阈值。
+
+数字控件只用于 `number` 模型。精确十进制字符串、超出安全范围的金额/编号应使用 `custom` 输入与明确的 codec，避免先转 `Number` 导致原值损失。搜索组件不负责计算税额或汇率。
+
+日期/月默认使用时间戳；已有 `date-range` 时间戳模型保持兼容。字符串模型声明 `valueMode: 'formatted'`，包括初始值为 `null` 时。默认格式分别为 `yyyy-MM-dd`、`yyyy-MM`、`yyyy-MM-dd HH:mm`，可通过 `attrs.format` / `attrs.valueFormat` 显式覆盖。展示格式与回写类型分开，清空不会将字符串日期改成时间戳。
+
+`select` 保留字符串、数字、布尔值及多选数组的业务类型。内部布尔编码仅用于适配原生选择器，提交的 `false` 不会变成字符串或 `0`。
+
+## 字典与自定义控件
+
+字段可配置 `dictionary: 'orderStatus'`，由应用已提供的字典 Provider 解析；也可直接传入 `DictionarySource`。搜索不另建字典缓存，使用同一来源的选项、订阅与可取消加载。
+
+显式 `list`（包括空数组）和 `attrs.options` 优先于字典，且不会加载未使用的字典。加载失败在选择器中显示重试入口；字典标签更新不会重置输入草稿。组织切换和字典加载策略仍由应用 Provider 决定。
+
+`custom` 可使用 `slot` 或 `render(context)`；必须声明类型正确的 `defaultValue`，使 reset 和 clear 有确定语义。上下文提供 `value`、只读 `model`、`prop`、`size`、`disabled`、`readonly` 和 `updateValue`。修改走 `updateValue`；`fixed`、`readonly`、`disabled` 字段会拦截控件回写。自定义按钮使用 `type="button"`，避免误触发表单提交。
+
+## 草稿、执行结果和重置
+
+- `v-model` / `formParams` 是可编辑草稿；字段配置或字典选项变化不拿旧 props 覆盖未提交输入。
+- `@search` 是经过校验的执行通知，保留原有时机；它不表示后台查询成功。
+- 使用 `config.onSearch` 返回任务 Promise 后，只有成功完成才更新 `appliedParams` 并发出 `@applied`。回调拒绝或显式返回 `false` 时，`searchFn()` 返回 `false`，保留上一次成功条件并允许重试。可直接返回 `useDataResource.reload()` 的 boolean 结果；接入自行收拢错误的其它控制器时，回调应检查其错误状态并返回 `false`。
+- 仅使用旧 `@search` 的接入无法观察事件监听器异步结果，因此不会伪造 `appliedParams`；需要成功快照时使用 `onSearch`。
+- 查询期间继续输入只改变草稿；成功快照仍是当次发送的条件。`hasUnappliedChanges` 可判断草稿与已执行条件是否不同。
+- `cleanFn()` 只重置草稿，不主动执行查询，也不把重置值标记为成功查询。`defaultValue: 0 / false` 保留原类型；未配置字段、隐藏上下文、分页参数不被清除。
+- `fixed: true` 的字段参与查询，但控件与 reset 不可改写。固定作用域切换时清空已执行快照，迟到请求不能在新作用域下标记成功。宿主仍应在执行器中取消失效请求，防止业务结果覆盖；`fixed` 不是后端授权机制。
+
+原生表单提交（包括 Enter）共享搜索任务锁，验证期间与请求期间都防重；外部 `loading` 仍生效。
+
+## 显式请求编码
+
+`serializeSearch(params, fields, { omitEmpty: true })` 是纯辅助函数，组件不会隐式调用，也不会更改 `onSearch`、事件或 `v-model` 的类型。
+
+字段 `query` 支持：
+
+- `name`：仅将请求字段改名。
+- `keys: ['start', 'end']`：将范围拆成两个请求字段，移除原范围键。
+- `serialize(value)`：显式转换单个字段的传输格式；入参是隔离数据，不能改变草稿。
+
+默认省略已配置字段的空值，保留 `0`、`false`、`'001'`。范围两端分别清理；`omitEmpty: false` 保留显式空值。未配置的上下文字段继续保留。重复目标键和不安全路径会报错，避免编码覆盖固定组织等条件。
+
+表格列表、合计与导出应使用同一次成功执行的条件快照，按各自 target 选择编码或标签。页面负责把该快照交给后端导出任务；不读取用户正在修改的草稿冒充已查询范围。
+
+## 常用条件
+
+通过公开实例的 `applyPreset(values)` 应用“今日”“待处理”等业务预设，无需再封装一个搜索组件。它只更新已声明且可编辑的字段，固定组织、隐藏上下文、只读字段与分页参数保持原值；0/false 不会被丢弃。传入值先隔离复制，失败不会部分改写模型。
+
+```ts
+searchRef.value?.applyPreset({ status: 'running', amountRange: [0, null] })
+// 用户确认执行时再调用 searchFn()；应用预设本身不发请求、不更新 appliedParams。
+```
+
+动态日期和班次的定义留在业务预设中，点击时产生当次值；预设不引入全局存储、额外 watcher 或另一套查询规则。

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.22.1",
+  "version": "0.23.0",
   "description": "基于 Naive UI 的 Vue 3 组件库",
   "packageManager": "bun@1.3.14",
   "engines": {
@@ -35,6 +35,26 @@
         "default": "./dist/config.cjs"
       }
     },
+    "./data": {
+      "import": {
+        "types": "./dist/data.d.ts",
+        "default": "./dist/data.js"
+      },
+      "require": {
+        "types": "./dist/data.d.cts",
+        "default": "./dist/data.cjs"
+      }
+    },
+    "./workflows": {
+      "import": {
+        "types": "./dist/workflows.d.ts",
+        "default": "./dist/workflows.js"
+      },
+      "require": {
+        "types": "./dist/workflows.d.cts",
+        "default": "./dist/workflows.cjs"
+      }
+    },
     "./style.css": "./dist/style.css",
     "./resolver": {
       "import": {